diff options
| -rw-r--r-- | pjnath/include/pjnath/ice_session.h | 63 | ||||
| -rw-r--r-- | pjnath/include/pjnath/ice_strans.h | 81 | ||||
| -rw-r--r-- | pjnath/include/pjnath/types.h | 68 |
3 files changed, 172 insertions, 40 deletions
diff --git a/pjnath/include/pjnath/ice_session.h b/pjnath/include/pjnath/ice_session.h index b601385c..032b2dcb 100644 --- a/pjnath/include/pjnath/ice_session.h +++ b/pjnath/include/pjnath/ice_session.h @@ -46,6 +46,8 @@ PJ_BEGIN_DECL * This module describes #pj_ice_sess, a transport independent ICE session, * part of PJNATH - the Open Source NAT helper library. * + * \section pj_ice_sess_sec ICE Session + * * An ICE session, represented by #pj_ice_sess structure, is the lowest * abstraction of ICE in PJNATH, and it is used to perform and manage * connectivity checks of transport address candidates <b>within a @@ -62,6 +64,67 @@ PJ_BEGIN_DECL * * For higher abstraction of ICE where transport is included, please * see \ref PJNATH_ICE_STREAM_TRANSPORT. + * + * \subsection pj_ice_sess_using_sec Using The ICE Session + * + * The steps below describe how to use ICE session. Alternatively application + * can use the higher level ICE API, \ref PJNATH_ICE_STREAM_TRANSPORT, + * which has provided the integration of ICE with socket transport. + * + * The steps to use ICE session is similar for both offerer and + * answerer: + * - create ICE session with #pj_ice_sess_create(). Among other things, + * application needs to specify: + * - STUN configuration (pj_stun_config), containing STUN settings + * such as timeout values and the instances of timer heap and + * ioqueue. + * - Session name, useful for identifying this session in the log. + * - Initial ICE role (#pj_ice_sess_role). The role can be changed + * at later time with #pj_ice_sess_change_role(), and ICE session + * can also change its role automatically when it detects role + * conflict. + * - Number of components in the media session. + * - Callback to receive ICE events (#pj_ice_sess_cb) + * - Optional local ICE username and password. If these arguments + * are NULL, they will be generated randomly. + * - Add local candidates for each component, with #pj_ice_sess_add_cand(). + * A candidate is represented with #pj_ice_sess_cand structure. + * Each component must be provided with at least one candidate, and + * all components must have the same number of candidates. Failing + * to comply with this will cause failure during pairing process. + * - Create offer to describe local ICE candidates. ICE session does not + * provide a function to create such offer, but application should be + * able to create one since it knows about all components and candidates. + * If application uses \ref PJNATH_ICE_STREAM_TRANSPORT, it can + * enumerate local candidates by calling #pj_ice_strans_enum_cands(). + * Application may use #pj_ice_sess_find_default_cand() to let ICE + * session chooses the default transport address to be used in SDP + * c= and m= lines. + * - Send the offer to remote endpoint using signaling such as SIP. + * - Once application has received the answer, it should parse this + * answer, build array of remote candidates, and create check lists by + * calling #pj_ice_sess_create_check_list(). This process is known as + * pairing the candidates, and will result in the creation of check lists. + * - Once checklist has been created, application then can call + * #pj_ice_sess_start_check() to instruct ICE session to start + * performing connectivity checks. The ICE session performs the + * connectivity checks by processing each check in the checklists. + * - Application will be notified about the result of ICE connectivity + * checks via the callback that was given in #pj_ice_sess_create() + * above. + * + * To send data, application calls #pj_ice_sess_send_data(). If ICE + * negotiation has not completed, ICE session would simply drop the data, + * and return error to caller. If ICE negotiation has completed + * successfully, ICE session will in turn call the \a on_tx_pkt + * callback of #pj_ice_sess_cb instance that was previously registered + * in #pj_ice_sess_create() above. + * + * When application receives any packets on the underlying sockets, it + * must call #pj_ice_sess_on_rx_pkt(). The ICE session will inspect the + * packet to decide whether to process it locally (if the packet is a + * STUN message and is part of ICE session) or otherwise pass it back to + * application via \a on_rx_data callback. */ /** diff --git a/pjnath/include/pjnath/ice_strans.h b/pjnath/include/pjnath/ice_strans.h index efd09a48..09fedbad 100644 --- a/pjnath/include/pjnath/ice_strans.h +++ b/pjnath/include/pjnath/ice_strans.h @@ -35,7 +35,7 @@ PJ_BEGIN_DECL /** * @defgroup PJNATH_ICE_STREAM_TRANSPORT ICE Stream Transport - * @brief Transport for media stream using ICE + * @brief Transport for media streams using ICE * @ingroup PJNATH_ICE * @{ * @@ -44,7 +44,7 @@ PJ_BEGIN_DECL * library. * * ICE stream transport, as represented by #pj_ice_strans structure, is an ICE - * capable component for transporting media within a media stream. + * capable component for transporting media streams within a media session. * It consists of one or more transport sockets (typically two for RTP * based communication - one for RTP and one for RTCP), and an * \ref PJNATH_ICE_SESSION for performing connectivity checks among the. @@ -67,23 +67,48 @@ PJ_BEGIN_DECL * Regardless of which usage scenario is being used, the ICE stream * transport is capable for restarting the ICE session being used and to * send STUN keep-alives for its STUN server reflexive and relayed - * candidates. + * candidates. When ICE stream transport detects that the STUN mapped + * address has changed in the keep-alive response, it will automatically + * update its address to the new address, and notify the application via + * \a on_addr_change() function of the #pj_ice_strans_cb callback. * - * \subsection PJNATH_ICE_ST_TRA_INIT Stream Transport Initialization + * \subsection PJNATH_ICE_ST_TRA_INIT Initialization * * Application creates the ICE stream transport by calling - * #pj_ice_strans_create() function. + * #pj_ice_strans_create() function. Among other things, application needs + * to specify: + * - STUN configuration (pj_stun_config), containing STUN settings + * such as timeout values and the instances of timer heap and + * ioqueue. + * - Session name, useful for identifying this session in the log. + * - Number of ICE components. + * - Arbitrary user data, useful when associating the ICE session + * with some application's data structure. + * - A callback (#pj_ice_strans_cb) to receive events from the ICE + * stream transport. Two of the most important fields in this + * callback structure are \a on_rx_data() to notify application + * about incoming data (perhaps RTP or RTCP packet), and + * \a on_ice_complete() to notify application that ICE negotiation + * has completed, either successfully or with failure. * * After the ICE stream transport is created, application may set up the * STUN servers to be used to obtain STUN server reflexive and relayed * candidate, by calling #pj_ice_strans_set_stun_domain() or - * #pj_ice_strans_set_stun_srv(). Then it has to create each component by - * calling #pj_ice_strans_create_comp(); this would create an actual socket + * #pj_ice_strans_set_stun_srv(). + * + * Application then creates each component by calling + * #pj_ice_strans_create_comp(); this would create an actual socket * which listens to the specified local address, and it would also * perform lookup to find various transport address candidates for this * socket. + * + * Adding component may involve contacting STUN and TURN servers to get + * STUN mapped address and allocate TURN relay channel, and this process + * may take some time to complete. Once application has added all + * components, it can check whether server reflexive and relayed + * candidates have been acquired, by calling #pj_ice_strans_get_comps_status(). * - * \subsection PJNATH_ICE_ST_TRA_INIT_ICE ICE Session Initialization + * \subsection PJNATH_ICE_ST_TRA_INIT_ICE Starting ICE Session * * When application is about to send an offer containing ICE capability, * or when it receives an offer containing ICE capability, it would @@ -95,12 +120,30 @@ PJ_BEGIN_DECL * * \subsection PJNATH_ICE_ST_TRA_START Starting Connectivity Checks * - * Once application receives the SDP from remote, it can start ICE - * connectivity checks by calling #pj_ice_strans_start_ice(), specifying - * the username, password, and candidates of the remote agent. The ICE - * session/transport will then notify the application via the callback - * when ICE connectivity checks completes, either successfully or with - * failure. + * Once application receives the SDP from remote, it pairs local candidates + * with remote candidates, and can start ICE connectivity checks. This is + * done by calling #pj_ice_strans_start_ice(), specifying + * the remote candidate list, and remote username and password. If the + * pairing process is successful, ICE connectivity checks will begin + * immediately. The ICE session/transport will then notify the application + * via the callback when ICE connectivity checks completes, either + * successfully or with failure. + * + * \subsection PJNATH_ICE_ST_TRA_SEND_RECV Sending and Receiving Data + * + * Application can send data (normally RTP or RTCP packets) at any time + * by calling #pj_ice_strans_sendto(). This function takes a destination + * address as one of the arguments, and this destination address should + * be taken from the default transport address of the component (that is + * the address in SDP c= and m= lines, or in a=rtcp attribute). + * If ICE negotiation is in progress, this function will send the data + * to the destination address. Otherwise if ICE negotiation has completed + * successfully, this function will send the data to the nominated remote + * address, as negotiated by ICE. + * + * Upon receiving incoming data (that is a non-STUN message), the ICE + * stream transport will notify the application by calling \a on_rx_data() + * of the #pj_ice_strans_cb callback. * * \subsection PJNATH_ICE_ST_TRA_STOP Stopping ICE Session * @@ -108,7 +151,11 @@ PJ_BEGIN_DECL * ICE session, so it should call #pj_ice_strans_stop_ice() to destroy the * ICE session within this ICE stream transport. Note that this WILL NOT * destroy the sockets/transports, it only destroys the ICE session - * within this ICE stream transport. + * within this ICE stream transport. It is recommended that application + * retains the ICE stream transport to speed up the process of setting up + * the next call. The ICE stream transport will continue to send STUN + * keep-alive packets to keep the NAT binding open and to detect change + * in STUN mapped address. * * \subsection PJNATH_ICE_ST_TRA_RESTART Restarting ICE Session * @@ -569,8 +616,8 @@ PJ_DECL(pj_status_t) pj_ice_strans_stop_ice(pj_ice_strans *ice_st); /** * Send outgoing packet using this transport. If ICE checks have not * produced a valid check for the specified component ID, this function - * will return with failure. Otherwise it will send the packet to remote - * destination using the nominated local candidate as have been checked + * send to the destination address. Otherwise it will send the packet to + * remote destination using the nominated local candidate as have been checked * previously. * * @param ice_st The ICE stream transport. diff --git a/pjnath/include/pjnath/types.h b/pjnath/include/pjnath/types.h index 91b83fb0..6304dc82 100644 --- a/pjnath/include/pjnath/types.h +++ b/pjnath/include/pjnath/types.h @@ -117,27 +117,40 @@ PJ_END_DECL * * The STUN library is organized as follows: * - * - the lowest layer of the library is \ref PJNATH_STUN_MSG. This layer - * provides STUN message representation, validation, parsing, and - * debugging (dump to log) of STUN messages. + * - for both client and server, the highest abstraction is + * \ref PJNATH_STUN_SESSION, which provides management of incoming + * and outgoing messages and association of STUN credential to + * a STUN session. * - * - for client, the next higher layer is \ref PJNATH_STUN_TRANSACTION, - * which manages retransmissions of STUN request. + * - for client, the next layer below is \ref PJNATH_STUN_TRANSACTION, + * which manages retransmissions of STUN request. Server side STUN + * transaction is handled in \ref PJNATH_STUN_SESSION layer above. * * - \ref PJNATH_STUN_AUTH provides mechanism to verify STUN * credential in incoming STUN messages. * - * - for both client and server, the next higher abstraction is - * \ref PJNATH_STUN_SESSION, which provides management of incoming - * and outgoing messages and association of STUN credential to - * a STUN session. + * - the lowest layer of the library is \ref PJNATH_STUN_MSG. This layer + * provides STUN message representation, validation, parsing, + * encoding MESSAGE-INTEGRITY for outgoing messages, and + * debugging (dump to log) of STUN messages. * - * As mentioned previously, all STUN library components are independent - * of any transports. Application gives incoming packet - * to the STUN components for processing. and it must supply the STUN - * components with callback to send outgoing messages. + * All STUN library components are independent of any transports. + * Application gives incoming packet to the STUN components for processing, + * and it must supply the STUN components with callback to send outgoing + * messages. * * + * \subsection PJNATH_STUN_USING Using STUN Library + * + * [The developers guide documentation can certainly be improved here] + * + * For a sample STUN and TURN client, please see <tt>pjstun-client</tt> + * project under <tt>pjnath/src</tt> directory. + * + * For a sample STUN and TURN server, please see <tt>pjstun-srv-test</tt> + * project under <tt>pjnath/src</tt> directory. + * + * * \subsection PJNATH_STUN_REF STUN Reference * * References for STUN: @@ -170,24 +183,33 @@ PJ_END_DECL * * The ICE library is organized as follows: * - * - the lowest layer is \ref PJNATH_ICE_SESSION, which provides - * ICE management and negotiation in a transport-independent way. - * This layer contains the state machines to perform ICE - * negotiation, and provides the most flexibility to control all - * aspects of ICE session. This layer normally is only usable for - * ICE implementors. + * - the highest abstraction is ICE media transport, which maintains + * ICE stream transport and provides SDP translations to be used + * for SIP offer/answer exchanges. ICE media transport is part + * of PJMEDIA library. * * - higher in the hierarchy is \ref PJNATH_ICE_STREAM_TRANSPORT, * which binds ICE with UDP sockets, and provides STUN binding * and relay/TURN allocation for the sockets. This component can * be directly used by application, although normally application - * should use the next higher abstraction below since it provides + * should use the next higher abstraction since it provides * SDP translations and better integration with other PJ libraries * such as PJSIP and PJMEDIA. * - * - the highest abstraction is ICE media transport, which maintains - * ICE stream transport and provides SDP translations to be used - * for SIP offer/answer exchanges. + * - the lowest layer is \ref PJNATH_ICE_SESSION, which provides + * ICE management and negotiation in a transport-independent way. + * This layer contains the state machines to perform ICE + * negotiation, and provides the most flexibility to control all + * aspects of ICE session. This layer normally is only usable for + * ICE implementors. + * + * \subsection PJNATH_ICE_USING Using the ICE Library + * + * For ICE implementation that has been integrated with socket transport, + * please see \ref PJNATH_ICE_STREAM_TRANSPORT_USING. + * + * For ICE implementation that has not been integrated with socket + * transport, please see \ref pj_ice_sess_using_sec. * * \subsection PJNATH_ICE_REF Reference * |