diff options
author | Benny Prijono <bennylp@teluu.com> | 2009-04-22 17:20:24 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2009-04-22 17:20:24 +0000 |
commit | 0b54cf857cd757da2571a62845894c67fb9e8ecf (patch) | |
tree | 50eb7b0b8d4a96314424c35b75f9b99770f8960a /pjnath/include | |
parent | 114bf49a36bd6f5b956ab4fd45cbe97929c17e38 (diff) |
Part of ticket #780: enhance the PJNATH doxygen documentation
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@2642 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjnath/include')
-rw-r--r-- | pjnath/include/pjnath/config.h | 3 | ||||
-rw-r--r-- | pjnath/include/pjnath/errno.h | 1 | ||||
-rw-r--r-- | pjnath/include/pjnath/ice_session.h | 28 | ||||
-rw-r--r-- | pjnath/include/pjnath/ice_strans.h | 64 | ||||
-rw-r--r-- | pjnath/include/pjnath/nat_detect.h | 1 | ||||
-rw-r--r-- | pjnath/include/pjnath/stun_auth.h | 2 | ||||
-rw-r--r-- | pjnath/include/pjnath/stun_config.h | 2 | ||||
-rw-r--r-- | pjnath/include/pjnath/stun_msg.h | 2 | ||||
-rw-r--r-- | pjnath/include/pjnath/stun_session.h | 126 | ||||
-rw-r--r-- | pjnath/include/pjnath/stun_sock.h | 34 | ||||
-rw-r--r-- | pjnath/include/pjnath/stun_transaction.h | 2 | ||||
-rw-r--r-- | pjnath/include/pjnath/turn_session.h | 106 | ||||
-rw-r--r-- | pjnath/include/pjnath/turn_sock.h | 46 | ||||
-rw-r--r-- | pjnath/include/pjnath/types.h | 225 |
14 files changed, 351 insertions, 291 deletions
diff --git a/pjnath/include/pjnath/config.h b/pjnath/include/pjnath/config.h index f418da1f..f9552721 100644 --- a/pjnath/include/pjnath/config.h +++ b/pjnath/include/pjnath/config.h @@ -29,8 +29,9 @@ #include <pj/types.h> /** - * @defgroup PJNATH_CONFIG Configuration + * @defgroup PJNATH_CONFIG Compile-time configurations * @brief Various compile time settings + * @ingroup PJNATH_STUN_BASE * @{ */ diff --git a/pjnath/include/pjnath/errno.h b/pjnath/include/pjnath/errno.h index 719ba412..e17f9460 100644 --- a/pjnath/include/pjnath/errno.h +++ b/pjnath/include/pjnath/errno.h @@ -30,6 +30,7 @@ /** * @defgroup PJNATH_ERROR NAT Helper Library Error Codes * @brief PJNATH specific error code constants + * @ingroup PJNATH_STUN_BASE * @{ */ diff --git a/pjnath/include/pjnath/ice_session.h b/pjnath/include/pjnath/ice_session.h index aaba2511..18f7ffd6 100644 --- a/pjnath/include/pjnath/ice_session.h +++ b/pjnath/include/pjnath/ice_session.h @@ -30,19 +30,11 @@ #include <pj/sock.h> #include <pj/timer.h> -/** - * @defgroup PJNATH_ICE Interactive Connectivity Establishment (ICE) - * @brief Interactive Connectivity Establishment (ICE) - */ - - PJ_BEGIN_DECL /** - * @defgroup PJNATH_ICE_SESSION ICE Session - * @brief Transport Independent ICE Session - * @ingroup PJNATH_ICE + * @addtogroup PJNATH_ICE_SESSION * @{ * * This module describes #pj_ice_sess, a transport independent ICE session, @@ -204,16 +196,22 @@ typedef struct pj_ice_sess_comp */ typedef struct pj_ice_msg_data { + /** Transport ID for this message */ unsigned transport_id; + + /** Flag to indicate whether data.req contains data */ pj_bool_t has_req_data; + /** The data */ union data { + /** Request data */ struct request_data { - pj_ice_sess *ice; - pj_ice_sess_checklist *clist; - unsigned ckid; + pj_ice_sess *ice; /**< ICE session */ + pj_ice_sess_checklist *clist; /**< Checklist */ + unsigned ckid; /**< Check ID */ } req; } data; + } pj_ice_msg_data; @@ -539,7 +537,7 @@ typedef enum pj_ice_sess_role */ typedef struct pj_ice_rx_check { - PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check); + PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check); /**< Standard list */ unsigned comp_id; /**< Component ID. */ unsigned transport_id; /**< Transport ID. */ @@ -600,7 +598,7 @@ struct pj_ice_sess unsigned rcand_cnt; /**< # of remote cand. */ pj_ice_sess_cand rcand[PJ_ICE_MAX_CAND]; /**< Array of cand. */ - /* Array of transport datas */ + /** Array of transport datas */ pj_ice_msg_data tp_data[4]; /* List of eearly checks */ @@ -612,7 +610,7 @@ struct pj_ice_sess /* Valid list */ pj_ice_sess_checklist valid_list; /**< Valid list. */ - /* Temporary buffer for misc stuffs to avoid using stack too much */ + /** Temporary buffer for misc stuffs to avoid using stack too much */ union { char txt[128]; char errmsg[PJ_ERR_MSG_SIZE]; diff --git a/pjnath/include/pjnath/ice_strans.h b/pjnath/include/pjnath/ice_strans.h index e28e8865..02397073 100644 --- a/pjnath/include/pjnath/ice_strans.h +++ b/pjnath/include/pjnath/ice_strans.h @@ -37,9 +37,7 @@ PJ_BEGIN_DECL /** - * @defgroup PJNATH_ICE_STREAM_TRANSPORT ICE Stream Transport - * @brief Transport for media streams using ICE - * @ingroup PJNATH_ICE + * @addtogroup PJNATH_ICE_STREAM_TRANSPORT * @{ * * This module describes ICE stream transport, as represented by #pj_ice_strans @@ -53,6 +51,66 @@ PJ_BEGIN_DECL * \ref PJNATH_ICE_SESSION for performing connectivity checks among the. * various candidates of the transport addresses. * + * + * \section ice_strans_using_sec Using the ICE stream transport + * + * The steps below describe how to use ICE session: + * + * - initialize a #pj_ice_strans_cfg structure. This contains various + * settings for the ICE stream transport, and among other things contains + * the STUN and TURN settings.\n\n + * - create the instance with #pj_ice_strans_create(). Among other things, + * the function needs the following arguments: + * - the #pj_ice_strans_cfg structure for the main configurations + * - number of components to be supported + * - instance of #pj_ice_strans_cb structure to report callbacks to + * application.\n\n + * - while the #pj_ice_strans_create() call completes immediately, the + * initialization will be running in the background to gather the + * candidates (for example STUN and TURN candidates, if they are enabled + * in the #pj_ice_strans_cfg setting). Application will be notified when + * the initialization completes in the \a on_ice_complete callback of + * the #pj_ice_strans_cb structure (the \a op argument of this callback + * will be PJ_ICE_STRANS_OP_INIT).\n\n + * - when media stream is to be started (for example, a call is to be + * started), create an ICE session by calling #pj_ice_strans_init_ice().\n\n + * - the application now typically will need to communicate local ICE + * information to remote host. It can achieve this by using the following + * functions to query local ICE information: + * - #pj_ice_strans_get_ufrag_pwd() + * - #pj_ice_strans_enum_cands() + * - #pj_ice_strans_get_def_cand()\n + * The application may need to encode the above information as SDP.\n\n + * - when the application receives remote ICE information (for example, from + * the SDP received from remote), it can now start ICE negotiation, by + * calling #pj_ice_strans_start_ice(). This function requires some + * information about remote ICE agent such as remote ICE username fragment + * and password as well as array of remote candidates.\n\n + * - note that the PJNATH library does not work with SDP; application would + * need to encode and parse the SDP itself.\n\n + * - once ICE negotiation has been started, application will be notified + * about the completion in the \a on_ice_complete() callback of the + * #pj_ice_strans_cb.\n\n + * - at any time, application may send or receive data. However the ICE + * stream transport may not be able to send it depending on its current + * state. Before ICE negotiation is started, the data will be sent using + * default candidate of the component. After negotiation is completed, + * data will be sent using the candidate from the successful/nominated + * pair. The ICE stream transport may not be able to send data while + * negotiation is in progress.\n\n + * - application sends data by using #pj_ice_strans_sendto(). Incoming + * data will be reported in \a on_rx_data() callback of the + * #pj_ice_strans_cb.\n\n + * - once the media session has finished (e.g. user hangs up the call), + * destroy the ICE session with #pj_ice_strans_stop_ice().\n\n + * - at this point, application may destroy the ICE stream transport itself, + * or let it run so that it can be reused to create other ICE session. + * The benefit of letting the ICE stream transport alive (without any + * session active) is to avoid delay with the initialization, howerver + * keeping the transport alive means the transport needs to keep the + * STUN binding open by using keep-alive and also TURN allocation alive, + * and this will consume power which is an important issue for mobile + * applications.\n\n */ /** Forward declaration for ICE stream transport. */ diff --git a/pjnath/include/pjnath/nat_detect.h b/pjnath/include/pjnath/nat_detect.h index a73781a7..40c88a93 100644 --- a/pjnath/include/pjnath/nat_detect.h +++ b/pjnath/include/pjnath/nat_detect.h @@ -33,6 +33,7 @@ PJ_BEGIN_DECL /** * @defgroup PJNATH_NAT_DETECT NAT Classification/Detection Tool * @brief NAT Classification/Detection Tool + * @ingroup PJNATH * @{ * * This module provides one function to perform NAT classification and diff --git a/pjnath/include/pjnath/stun_auth.h b/pjnath/include/pjnath/stun_auth.h index c1aea038..5befb5e0 100644 --- a/pjnath/include/pjnath/stun_auth.h +++ b/pjnath/include/pjnath/stun_auth.h @@ -35,7 +35,7 @@ PJ_BEGIN_DECL /** * @defgroup PJNATH_STUN_AUTH STUN Authentication * @brief STUN authentication helper - * @ingroup PJNATH_STUN + * @ingroup PJNATH_STUN_BASE * @{ */ diff --git a/pjnath/include/pjnath/stun_config.h b/pjnath/include/pjnath/stun_config.h index 7025db61..c4721471 100644 --- a/pjnath/include/pjnath/stun_config.h +++ b/pjnath/include/pjnath/stun_config.h @@ -38,7 +38,7 @@ PJ_BEGIN_DECL /** * @defgroup PJNATH_STUN_CONFIG STUN Config * @brief STUN config - * @ingroup PJNATH_STUN + * @ingroup PJNATH_STUN_BASE * @{ */ diff --git a/pjnath/include/pjnath/stun_msg.h b/pjnath/include/pjnath/stun_msg.h index cf183d02..57fc38c4 100644 --- a/pjnath/include/pjnath/stun_msg.h +++ b/pjnath/include/pjnath/stun_msg.h @@ -35,7 +35,7 @@ PJ_BEGIN_DECL /* **************************************************************************/ /** * @defgroup PJNATH_STUN_MSG STUN Message Representation and Parsing - * @ingroup PJNATH_STUN + * @ingroup PJNATH_STUN_BASE * @brief Low-level representation and parsing of STUN messages. * @{ */ diff --git a/pjnath/include/pjnath/stun_session.h b/pjnath/include/pjnath/stun_session.h index 714cbf9e..2a6fd022 100644 --- a/pjnath/include/pjnath/stun_session.h +++ b/pjnath/include/pjnath/stun_session.h @@ -37,10 +37,130 @@ PJ_BEGIN_DECL /* **************************************************************************/ /** - * @defgroup PJNATH_STUN_SESSION STUN Client/Server Session - * @brief STUN client and server session - * @ingroup PJNATH_STUN + * @addtogroup PJNATH_STUN_SESSION * @{ + * + * This is is a transport-independent object to manage a client or server + * STUN session. It has the following features: + * + * - <b>transport independent</b>:\n + * the object does not have it's own socket, but rather it provides + * functions and callbacks to send and receive packets. This way the + * object can be used by different transport types (e.g. UDP, TCP, + * TLS, etc.) as well as better integration to application which + * already has its own means to send and receive packets. + * + * - <b>authentication management</b>:\n + * the object manages STUN authentication throughout the lifetime of + * the session. For client sessions, once it's given a credential to + * authenticate itself with the server, the object will automatically + * add authentication info (the MESSAGE-INTEGRITY) to the request as + * well as authenticate the response. It will also handle long-term + * authentication challenges, including handling of nonce expiration, + * and retry the request automatically. For server sessions, it can + * be configured to authenticate incoming requests automatically. + * + * - <b>static or dynamic credential</b>:\n + * application may specify static or dynamic credential to be used by + * the STUN session. Static credential means a static combination of + * username and password (and these cannot change during the session + * duration), while dynamic credential provides callback to ask the + * application about which username/password to use everytime + * authentication is about to be performed. + * + * - <b>client transaction management</b>:\n + * outgoing requests may be sent with a STUN transaction for reliability, + * and the object will manage the transaction internally (including + * performing retransmissions). Application will be notified about the + * result of the request when the response arrives (or the transaction + * times out). When the request is challenged with authentication, the + * object will retry the request with new authentication info, and + * application will be notified about the final result of this request. + * + * - <b>server transaction management</b>:\n + * application may ask response to incoming requests to be cached by + * the object, and in this case the object will check for cached + * response everytime request is received. The cached response will be + * deleted once a timer expires. + * + * \section using_stun_sess_sec Using the STUN session + * + * The following steps describes how to use the STUN session: + * + * - <b>create the object configuration</b>:\n + * The #pj_stun_config contains the configuration to create the STUN + * session, such as the timer heap to register internal timers and + * various STUN timeout values. You can initialize this structure by + * calling #pj_stun_config_init() + * + * - <b>create the STUN session</b>:\n + * by calling #pj_stun_session_create(). Among other things, this + * function requires the instance of #pj_stun_config and also + * #pj_stun_session_cb structure which stores callbacks to send + * outgoing packets as well as to notify application about incoming + * STUN requests, responses, and indicates and other events. + * + * - <b>configure credential:</b>\n + * if authentication is required for the session, configure the + * credential with #pj_stun_session_set_credential() + * + * - <b>configuring other settings:</b>\n + * several APIs are provided to configure the behavior of the STUN + * session (for example, to set the SOFTWARE attribute value, controls + * the logging behavior, fine tune the mutex locking, etc.). Please see + * the API reference for more info. + * + * - <b>creating outgoing STUN requests or indications:</b>\n + * create the STUN message by using #pj_stun_session_create_req() or + * #pj_stun_session_create_ind(). This will create a transmit data + * buffer containing a blank STUN request or indication. You will then + * typically need to add STUN attributes that are relevant to the + * request or indication, but note that some default attributes will + * be added by the session later when the message is sent (such as + * SOFTWARE attribute and attributes related to authentication). + * The message is now ready to be sent. + * + * - <b>sending outgoing message:</b>\n + * use #pj_stun_session_send_msg() to send outgoing STUN messages (this + * includes STUN requests, indications, and responses). The function has + * options whether to retransmit the request (for non reliable transports) + * or to cache the response if we're sending response. This function in + * turn will call the \a on_send_msg() callback of #pj_stun_session_cb + * to request the application to send the packet. + * + * - <b>handling incoming packet:</b>\n + * call #pj_stun_session_on_rx_pkt() everytime the application receives + * a STUN packet. This function will decode the packet and process the + * packet according to the message, and normally this will cause one + * of the callback in the #pj_stun_session_cb to be called to notify + * the application about the event. + * + * - <b>handling incoming requests:</b>\n + * incoming requests are notified to application in the \a on_rx_request + * callback of the #pj_stun_session_cb. If authentication is enabled in + * the session, the application will only receive this callback after + * the incoming request has been authenticated (if the authentication + * fails, the session would respond automatically with 401 error and + * the callback will not be called). Application now must create and + * send response for this request. + * + * - <b>creating and sending response:</b>\n + * create the STUN response with #pj_stun_session_create_res(). This will + * create a transmit data buffer containing a blank STUN response. You + * will then typically need to add STUN attributes that are relevant to + * the response, but note that some default attributes will + * be added by the session later when the message is sent (such as + * SOFTWARE attribute and attributes related to authentication). + * The message is now ready to be sent. Use #pj_stun_session_send_msg() + * (as explained above) to send the response. + * + * - <b>convenient way to send response:</b>\n + * the #pj_stun_session_respond() is provided as a convenient way to + * create and send simple STUN responses, such as error responses. + * + * - <b>destroying the session:</b>\n + * once the session is done, use #pj_stun_session_destroy() to destroy + * the session. */ diff --git a/pjnath/include/pjnath/stun_sock.h b/pjnath/include/pjnath/stun_sock.h index 5dcaad2b..b196b325 100644 --- a/pjnath/include/pjnath/stun_sock.h +++ b/pjnath/include/pjnath/stun_sock.h @@ -34,16 +34,24 @@ PJ_BEGIN_DECL /** - * @defgroup PJNATH_STUN_SOCK STUN aware socket transport - * @brief STUN aware socket transport - * @ingroup PJNATH_STUN + * @addtogroup PJNATH_STUN_SOCK * @{ * * The STUN transport provides asynchronous UDP like socket transport - * with the additional capability to query the publicly mapped transport - * address (using STUN resolution), to refresh the NAT binding, and to - * demultiplex internal STUN messages from application data (the - * application data may be a STUN message as well). + * with the additional STUN capability. It has the following features: + * + * - API to send and receive UDP packets + * + * - multiplex STUN and non-STUN incoming packets and distinguish between + * STUN responses that belong to internal requests with application data + * (the application data may be STUN packets as well) + * + * - DNS SRV resolution to the STUN server (if wanted), along with fallback + * to DNS A resolution if SRV record is not found. + * + * - STUN keep-alive maintenance, and handle changes to the mapped address + * (when the NAT binding changes) + * */ /** @@ -275,7 +283,7 @@ PJ_DECL(void) pj_stun_sock_cfg_default(pj_stun_sock_cfg *cfg); * this transport. * @param p_sock Pointer to receive the created transport instance. * - * @restun PJ_SUCCESS if the operation has been successful, + * @return PJ_SUCCESS if the operation has been successful, * or the appropriate error code on failure. */ PJ_DECL(pj_status_t) pj_stun_sock_create(pj_stun_config *stun_cfg, @@ -327,7 +335,7 @@ PJ_DECL(pj_status_t) pj_stun_sock_start(pj_stun_sock *stun_sock, * * @param sock The STUN transport socket. * - * @restun PJ_SUCCESS if the operation has been successful, + * @return PJ_SUCCESS if the operation has been successful, * or the appropriate error code on failure. */ PJ_DECL(pj_status_t) pj_stun_sock_destroy(pj_stun_sock *sock); @@ -340,7 +348,7 @@ PJ_DECL(pj_status_t) pj_stun_sock_destroy(pj_stun_sock *sock); * @param stun_sock The STUN transport instance. * @param user_data Arbitrary data. * - * @restun PJ_SUCCESS if the operation has been successful, + * @return PJ_SUCCESS if the operation has been successful, * or the appropriate error code on failure. */ PJ_DECL(pj_status_t) pj_stun_sock_set_user_data(pj_stun_sock *stun_sock, @@ -352,7 +360,7 @@ PJ_DECL(pj_status_t) pj_stun_sock_set_user_data(pj_stun_sock *stun_sock, * * @param stun_sock The STUN transport instance. * - * @restun The user/application data. + * @return The user/application data. */ PJ_DECL(void*) pj_stun_sock_get_user_data(pj_stun_sock *stun_sock); @@ -364,7 +372,7 @@ PJ_DECL(void*) pj_stun_sock_get_user_data(pj_stun_sock *stun_sock); * @param stun_sock The STUN transport instance. * @param info Pointer to be filled with STUN transport info. * - * @restun PJ_SUCCESS if the operation has been successful, + * @return PJ_SUCCESS if the operation has been successful, * or the appropriate error code on failure. */ PJ_DECL(pj_status_t) pj_stun_sock_get_info(pj_stun_sock *stun_sock, @@ -376,7 +384,7 @@ PJ_DECL(pj_status_t) pj_stun_sock_get_info(pj_stun_sock *stun_sock, * asynchronously and in this case \a on_data_sent() will be called. * * @param stun_sock The STUN transport instance. - * @param op_key Optional send key for sending the packet down to + * @param send_key Optional send key for sending the packet down to * the ioqueue. This value will be given back to * \a on_data_sent() callback * @param pkt The data/packet to be sent to peer. diff --git a/pjnath/include/pjnath/stun_transaction.h b/pjnath/include/pjnath/stun_transaction.h index 12ff03fa..d73e8146 100644 --- a/pjnath/include/pjnath/stun_transaction.h +++ b/pjnath/include/pjnath/stun_transaction.h @@ -36,7 +36,7 @@ PJ_BEGIN_DECL /** * @defgroup PJNATH_STUN_TRANSACTION STUN Client Transaction * @brief STUN client transaction - * @ingroup PJNATH_STUN + * @ingroup PJNATH_STUN_BASE * @{ * The @ref PJNATH_STUN_TRANSACTION is used to manage outgoing STUN request, diff --git a/pjnath/include/pjnath/turn_session.h b/pjnath/include/pjnath/turn_session.h index 88cf1bfe..64f12787 100644 --- a/pjnath/include/pjnath/turn_session.h +++ b/pjnath/include/pjnath/turn_session.h @@ -30,25 +30,99 @@ PJ_BEGIN_DECL -/** - * @defgroup PJNATH_TURN TURN Client Library - */ - /* **************************************************************************/ /** - * @defgroup PJNATH_TURN_SESSION Transport independent TURN client session - * @brief Transport independent TURN client session - * @ingroup PJNATH_TURN - * @{ - * - * This module describes the transport independent TURN client session. This - * interface is provided for implementors of a TURN client transport, and - * application usually will want to use \ref PJNATH_TURN_SOCK instead. - * - * The transport independent TURN client session is created to facilitate - * the creation of different types of transports between the client and the - * TURN server. +@addtogroup PJNATH_TURN_SESSION +@{ + +The \ref PJNATH_TURN_SESSION is a transport-independent object to +manage a client TURN session. It contains the core logic for manage +the TURN client session as listed in \ref turn_op_sec, but +in transport-independent manner (i.e. it doesn't have a socket), so +that developer can integrate TURN client functionality into existing +framework that already has its own means to send and receive data, +or to support new transport types to TURN, such as TLS. + + +\section turn_sess_using_sec Using the TURN session + +These steps describes how to use the TURN session: + + - <b>Creating the session</b>:\n + use #pj_turn_session_create() to create the session. + + - <b>Configuring credential</b>:\n + all TURN operations requires the use of authentication (it uses STUN + long term autentication method). Use #pj_turn_session_set_credential() + to configure the TURN credential to be used by the session. + + - <b>Configuring server</b>:\n + application must call #pj_turn_session_set_server() before it can send + Allocate request (with pj_turn_session_alloc()). This function will + resolve the TURN server using DNS SRV resolution if the \a resolver + is set. The server resolution process will complete asynchronously, + and application will be notified in \a on_state() callback of the + #pj_turn_session_cb structurewith the session state set to + PJ_TURN_STATE_RESOLVED. + + - <b>Creating allocation</b>:\n + create one "relay port" (or called <b>relayed-transport-address</b> + in TURN terminology) in the TURN server by using #pj_turn_session_alloc(). + This will send Allocate request to the server. This function will complete + immediately, and application will be notified about the allocation + result in the \a on_state() callback of the #pj_turn_session_cb structure. + + - <b>Getting the allocation result</b>:\n + if allocation is successful, the session state will progress to + \a PJ_TURN_STATE_READY, otherwise the state will be + \a PJ_TURN_STATE_DEALLOCATED or higher. Session state progression is + reported in the \a on_state() callback of the #pj_turn_session_cb + structure. On successful allocation, application may retrieve the + allocation info by calling #pj_turn_session_get_info(). + + - <b>Sending data through the relay</b>.\n + Once allocation has been created, client may send data to any remote + endpoints (called peers in TURN terminology) via the "relay port". It does + so by calling #pj_turn_session_sendto(), giving the peer address + in the function argument. But note that at this point peers are not allowed + to send data towards the client (via the "relay port") before permission is + installed for that peer. + + - <b>Creating permissions</b>.\n + Permission needs to be created in the TURN server so that a peer can send + data to the client via the relay port (a peer in this case is identified by + its IP address). Without this, when the TURN server receives data from the + peer in the "relay port", it will drop this data. Create the permission by + calling #pj_turn_session_set_perm(), specifying the peer IP address in the + argument (the port part of the address is ignored). More than one IP + addresses may be specified. + + - <b>Receiving data from peers</b>.\n + Once permission has been installed for the peer, any data received by the + TURN server (from that peer) in the "relay port" will be relayed back to + client by the server, and application will be notified via \a on_rx_data + callback of the #pj_turn_session_cb. + + - <b>Using ChannelData</b>.\n + TURN provides optimized framing to the data by using ChannelData + packetization. The client activates this format for the specified peer by + calling #pj_turn_session_bind_channel(). Data sent or received to/for + this peer will then use ChannelData format instead of Send or Data + Indications. + + - <b>Refreshing the allocation, permissions, and channel bindings</b>.\n + Allocations, permissions, and channel bindings will be refreshed by the + session automatically when they about to expire. + + - <b>Destroying the allocation</b>.\n + Once the "relay port" is no longer needed, client destroys the allocation + by calling #pj_turn_session_shutdown(). This function will return + immediately, and application will be notified about the deallocation + result in the \a on_state() callback of the #pj_turn_session_cb structure. + Once the state has reached PJ_TURN_STATE_DESTROYING, application must + assume that the session will be destroyed shortly after. + */ /** diff --git a/pjnath/include/pjnath/turn_sock.h b/pjnath/include/pjnath/turn_sock.h index e0931ab9..f6776b83 100644 --- a/pjnath/include/pjnath/turn_sock.h +++ b/pjnath/include/pjnath/turn_sock.h @@ -32,17 +32,26 @@ PJ_BEGIN_DECL /* **************************************************************************/ /** - * @defgroup PJNATH_TURN_SOCK TURN client transport - * @brief Client transport utilizing TURN relay - * @ingroup PJNATH_TURN - * @{ - * - * The TURN relay client transport can be used to relay data from the client - * to peer via a TURN relay. The application establishes TURN connection to - * the TURN server using UDP or TCP as the transport, then creates a relay - * address in the TURN server to be advertised to remote peer(s) as the - * transport address. When application sends data to a remote address via - * this transport, the data will be sent via the TURN relay, and vice versa. +@addtogroup PJNATH_TURN_SOCK +@{ + +This is a ready to use object for relaying application data via a TURN server, +by managing all the operations in \ref turn_op_sec. + +\section turnsock_using_sec Using TURN transport + +This object provides a thin wrapper to the \ref PJNATH_TURN_SESSION, hence the +API is very much the same (apart from the obvious difference in the names). +Please see \ref PJNATH_TURN_SESSION for the documentation on how to use the +session. + +\section turnsock_samples_sec Samples + +The \ref turn_client_sample is a sample application to use the +\ref PJNATH_TURN_SOCK. + +Also see <b>\ref samples_page</b> for other samples. + */ @@ -206,6 +215,21 @@ PJ_DECL(void) pj_turn_sock_set_log(pj_turn_sock *turn_sock, unsigned flags); /** + * Configure the SOFTWARE name to be sent in all STUN requests by the + * TURN session. + * + * @param turn_sock The TURN transport instance. + * @param sw Software name string. If this argument is NULL or + * empty, the session will not include SOFTWARE attribute + * in STUN requests and responses. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_turn_sock_set_software_name(pj_turn_sock *turn_sock, + const pj_str_t *sw); + + +/** * Allocate a relay address/resource in the TURN server. This function * will resolve the TURN server using DNS SRV (if desired) and send TURN * \a Allocate request using the specified credential to allocate a relay diff --git a/pjnath/include/pjnath/types.h b/pjnath/include/pjnath/types.h index 0f857d00..c5837e65 100644 --- a/pjnath/include/pjnath/types.h +++ b/pjnath/include/pjnath/types.h @@ -72,230 +72,5 @@ PJ_END_DECL * @} */ -/* Doxygen documentation below: */ - -/** - -@mainpage PJNATH - Open Source ICE, STUN, and TURN Library - -\n -This is the documentation of PJNATH, an Open Source library providing -NAT traversal helper functionalities by using standard based protocols -such as STUN, TURN, and ICE. - -\n -\n - -\section lib_comps Library Components - -\subsection comp_stun STUN - -Session Traversal Utilities (STUN, or previously known as Simple -Traversal of User Datagram Protocol (UDP) Through Network Address -Translators (NAT)s), is a lightweight protocol that serves as a tool for -application protocols in dealing with NAT traversal. It allows a client -to determine the IP address and port allocated to them by a NAT and to -keep NAT bindings open. - -This version of PJNATH implements the following STUN RFC: -- <A HREF="http://www.ietf.org/rfc/rfc5389.txt"><B>RFC 5389</b></A>: - Session Traversal Utilities for (NAT) (STUN), - - -\subsection comp_turn TURN - -Traversal Using Relays around NAT (TURN) allows the host to control the -operation of the relay and to exchange packets with its peers using the relay. - -Features: - - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-13.txt"> - <B>draft-ietf-behave-turn-13</B></A>: Obtaining Relay Addresses - from Simple Traversal Underneath NAT (STUN) - - DNS SRV resolution - - Fallback to DNS A resolution if SRV record is not found - - UDP and TCP connection to TURN server - - automatic management of allocation refresh - - - -\subsection comp_ice ICE - -Interactive Connectivity Establishment (ICE) is a standard based -methodology for traversing Network Address Translator (NAT). This -implementation is aimed to provide a usable and generic ICE transports -for different types of application, including but not limited to -the usage of ICE in SIP/SDP offer/answer. - - -This version of PJNATH implements the following ICE draft: - - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-19.txt"> - <B>draft-ietf-mmusic-ice-19.txt</B></A> draft. The PJNATH ICE - - -\subsection comp_natck NAT Classification Utility - -The PJNATH library also provides NAT classification utility as -described in <A HREF="http://www.ietf.org/rfc/rfc3489.txt">RFC 3489</A>. -While the practice to detect the NAT type to assist NAT traversal -has been deprecated in favor of ICE, the information may still be -useful for troubleshooting purposes, hence the utility is provided. - - -\n -\n - -\section lib_org Library Organization - -The PJNATH library consists of many components with each providing -specific functionality that may or may not be of the interests of -applications (or application developers). This section attempts to -give brief overview on the components provided by PJNATH. - -The PJNATH components from the highest layer to the lower layer are -as follows. - - -\n - -\subsection user_comp High-level Transport Objects - -PJNATH library provides some high-level objects that may be used -by applications: - - -\subsubsection stun_sock STUN Transport - -The \ref PJNATH_STUN_SOCK provides asynchronous UDP like socket transport -with the additional capability to query the publicly mapped transport -address (using STUN resolution), to refresh the NAT binding, and to -demultiplex internal STUN messages from application data (the -application data may be a STUN message as well). - - -\subsubsection turn_sock TURN Client Transport - -The \ref PJNATH_TURN_SOCK may be used by the application to send and -receive data via TURN server. For more information please see the -documentation of \ref PJNATH_TURN_SOCK. - - -\subsubsection ice_strans ICE Stream Transport - -The \ref PJNATH_ICE_STREAM_TRANSPORT provides transport interface to -send and receive data through connection that is negotiated -with ICE protocol. The \ref PJNATH_ICE_STREAM_TRANSPORT naturally -contains both STUN Transport and \ref PJNATH_TURN_SOCK. - -The \ref PJNATH_ICE_STREAM_TRANSPORT interface is suitable for both -SIP or non-SIP use. For SIP use, application may prefer to use the -ICE media transport in PJMEDIA instead where it has been integrated -with the SDP offer and answer mechanism. - - -\subsubsection natck NAT Classification Utility - -PJNATH also provides \a PJNATH_NAT_DETECT to assist troubleshooting -of problems related to NAT traversal. - - - -\n - - -\subsection sessions Transport Independent Sessions Layer - -Right below the high level transports objects are the transport -independent sessions. These sessions don't have access to sockets, -so higher level objects (such as transports) must give incoming -packets to the sessions and provide callback to be called by -sessions to send outgoing packets. - - -\subsubsection ice_sess ICE Session - -The \ref PJNATH_ICE_SESSION is used by the \ref PJNATH_ICE_STREAM_TRANSPORT -and contains the actual logic of the ICE negotiation. - - -\subsubsection turn_sess TURN Session - -The \ref PJNATH_TURN_SESSION is used by the \ref PJNATH_TURN_SOCK -and it contains TURN protocol logic. Implementors may implement -other types of TURN client connection (such as TURN TLS client) -by utilizing this session. - - -\subsubsection stun_sess STUN Session - -The \ref PJNATH_STUN_SESSION manages STUN message exchange between -a client and server (or vice versa). It manages \ref PJNATH_STUN_TRANSACTION -for sending or receiving requests and \ref PJNATH_STUN_AUTH for both -both incoming and outgoing STUN messages. - -The \ref PJNATH_STUN_SESSION is naturally used by the \ref PJNATH_TURN_SESSION -and \ref PJNATH_ICE_SESSION - - -\n - -\subsection stun_tsx STUN Transaction Layer - -The \ref PJNATH_STUN_TRANSACTION is a thin layer to manage retransmission -of STUN requests. - - -\n - - -\subsection stun_msg STUN Messaging Layer - -At the very bottom of the PJNATH components is the \ref PJNATH_STUN_MSG -layer. The API contains various representation of STUN messaging components -and it provides API to encode and decode STUN messages. - - - -\n -\n - -\section class_dia Class Diagram - - -The following class diagram shows the interactions between objects in -PJNATH: - -\image html UML-class-diagram.png "Class Diagram" -\image latex UML-class-diagram.png "Class Diagram" - - - -\n -\n - -\section samples Sample Applications - - -Some sample applications have been provided with PJNATH, and it's available -under <tt>pjnath/src</tt> directory: - - - <b>pjturn-client</b>: this is a stand-alone, console based TURN client - application to be used as a demonstration for PJNATH TURN client - transport API and for simple testing against TURN server implementations. - The client supports both UDP and TCP connection to the TURN server. - - - <b>pjturn-srv</b>: this is a simple TURN server to be used for testing - purposes. It supports both UDP and TCP connections to the clients. - - -*/ - -/** - * @defgroup PJNATH_STUN STUN Library - * @brief Open source STUN library - * - * This module contains implementation of STUN library in PJNATH - - * the open source NAT helper containing STUN and ICE. - */ - #endif /* __PJNATH_TYPES_H__ */ |