Changeset 1487 for pjproject/trunk


Ignore:
Timestamp:
Oct 7, 2007 12:51:15 PM (17 years ago)
Author:
bennylp
Message:

Updated PJNATH doxygen documentation

Location:
pjproject/trunk/pjnath/include/pjnath
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjnath/include/pjnath/ice_session.h

    r1435 r1487  
    4646 * This module describes #pj_ice_sess, a transport independent ICE session, 
    4747 * part of PJNATH - the Open Source NAT helper library. 
     48 * 
     49 * \section pj_ice_sess_sec ICE Session 
    4850 * 
    4951 * An ICE session, represented by #pj_ice_sess structure, is the lowest  
    … …  
    6365 * For higher abstraction of ICE where transport is included, please  
    6466 * see \ref PJNATH_ICE_STREAM_TRANSPORT. 
     67 * 
     68 * \subsection pj_ice_sess_using_sec Using The ICE Session 
     69 * 
     70 * The steps below describe how to use ICE session. Alternatively application 
     71 * can use the higher level ICE API, \ref PJNATH_ICE_STREAM_TRANSPORT, 
     72 * which has provided the integration of ICE with socket transport. 
     73 * 
     74 * The steps to use ICE session is similar for both offerer and 
     75 * answerer: 
     76 * - create ICE session with #pj_ice_sess_create(). Among other things, 
     77 *   application needs to specify: 
     78 *      - STUN configuration (pj_stun_config), containing STUN settings 
     79 *        such as timeout values and the instances of timer heap and 
     80 *        ioqueue. 
     81 *      - Session name, useful for identifying this session in the log. 
     82 *      - Initial ICE role (#pj_ice_sess_role). The role can be changed 
     83 *        at later time with #pj_ice_sess_change_role(), and ICE session 
     84 *        can also change its role automatically when it detects role 
     85 *        conflict. 
     86 *      - Number of components in the media session. 
     87 *      - Callback to receive ICE events (#pj_ice_sess_cb) 
     88 *      - Optional local ICE username and password. If these arguments 
     89 *        are NULL, they will be generated randomly. 
     90 * - Add local candidates for each component, with #pj_ice_sess_add_cand(). 
     91 *   A candidate is represented with #pj_ice_sess_cand structure. 
     92 *   Each component must be provided with at least one candidate, and 
     93 *   all components must have the same number of candidates. Failing 
     94 *   to comply with this will cause failure during pairing process. 
     95 * - Create offer to describe local ICE candidates. ICE session does not 
     96 *   provide a function to create such offer, but application should be 
     97 *   able to create one since it knows about all components and candidates. 
     98 *   If application uses \ref PJNATH_ICE_STREAM_TRANSPORT, it can 
     99 *   enumerate local candidates by calling #pj_ice_strans_enum_cands(). 
     100 *   Application may use #pj_ice_sess_find_default_cand() to let ICE 
     101 *   session chooses the default transport address to be used in SDP 
     102 *   c= and m= lines. 
     103 * - Send the offer to remote endpoint using signaling such as SIP. 
     104 * - Once application has received the answer, it should parse this 
     105 *   answer, build array of remote candidates, and create check lists by 
     106 *   calling #pj_ice_sess_create_check_list(). This process is known as 
     107 *   pairing the candidates, and will result in the creation of check lists. 
     108 * - Once checklist has been created, application then can call 
     109 *   #pj_ice_sess_start_check() to instruct ICE session to start 
     110 *   performing connectivity checks. The ICE session performs the 
     111 *   connectivity checks by processing each check in the checklists. 
     112 * - Application will be notified about the result of ICE connectivity 
     113 *   checks via the callback that was given in #pj_ice_sess_create() 
     114 *   above. 
     115 * 
     116 * To send data, application calls #pj_ice_sess_send_data(). If ICE 
     117 * negotiation has not completed, ICE session would simply drop the data, 
     118 * and return error to caller. If ICE negotiation has completed 
     119 * successfully, ICE session will in turn call the \a on_tx_pkt 
     120 * callback of #pj_ice_sess_cb instance that was previously registered 
     121 * in #pj_ice_sess_create() above. 
     122 * 
     123 * When application receives any packets on the underlying sockets, it 
     124 * must call #pj_ice_sess_on_rx_pkt(). The ICE session will inspect the 
     125 * packet to decide whether to process it locally (if the packet is a 
     126 * STUN message and is part of ICE session) or otherwise pass it back to 
     127 * application via \a on_rx_data callback. 
    65128 */ 
    66129 

  • pjproject/trunk/pjnath/include/pjnath/ice_strans.h

    r1434 r1487  
    3636/** 
    3737 * @defgroup PJNATH_ICE_STREAM_TRANSPORT ICE Stream Transport 
    38  * @brief Transport for media stream using ICE 
     38 * @brief Transport for media streams using ICE 
    3939 * @ingroup PJNATH_ICE 
    4040 * @{ 
    … …  
    4545 * 
    4646 * ICE stream transport, as represented by #pj_ice_strans structure, is an ICE 
    47  * capable component for transporting media within a media stream.  
     47 * capable component for transporting media streams within a media session.  
    4848 * It consists of one or more transport sockets (typically two for RTP 
    4949 * based communication - one for RTP and one for RTCP), and an  
    … …  
    6868 * transport is capable for restarting the ICE session being used and to 
    6969 * send STUN keep-alives for its STUN server reflexive and relayed 
    70  * candidates. 
    71  * 
    72  * \subsection PJNATH_ICE_ST_TRA_INIT Stream Transport Initialization 
     70 * candidates. When ICE stream transport detects that the STUN mapped 
     71 * address has changed in the keep-alive response, it will automatically 
     72 * update its address to the new address, and notify the application via 
     73 * \a on_addr_change() function of the #pj_ice_strans_cb callback. 
     74 * 
     75 * \subsection PJNATH_ICE_ST_TRA_INIT Initialization 
    7376 * 
    7477 * Application creates the ICE stream transport by calling  
    75  * #pj_ice_strans_create() function. 
     78 * #pj_ice_strans_create() function. Among other things, application needs 
     79 * to specify: 
     80 *      - STUN configuration (pj_stun_config), containing STUN settings 
     81 *        such as timeout values and the instances of timer heap and 
     82 *        ioqueue. 
     83 *      - Session name, useful for identifying this session in the log. 
     84 *      - Number of ICE components. 
     85 *      - Arbitrary user data, useful when associating the ICE session 
     86 *        with some application's data structure. 
     87 *      - A callback (#pj_ice_strans_cb) to receive events from the ICE 
     88 *        stream transport. Two of the most important fields in this 
     89 *        callback structure are \a on_rx_data() to notify application 
     90 *        about incoming data (perhaps RTP or RTCP packet), and 
     91 *        \a on_ice_complete() to notify application that ICE negotiation 
     92 *        has completed, either successfully or with failure. 
    7693 * 
    7794 * After the ICE stream transport is created, application may set up the 
    7895 * STUN servers to be used to obtain STUN server reflexive and relayed 
    7996 * candidate, by calling #pj_ice_strans_set_stun_domain() or  
    80  * #pj_ice_strans_set_stun_srv(). Then it has to create each component by 
    81  * calling #pj_ice_strans_create_comp(); this would create an actual socket 
     97 * #pj_ice_strans_set_stun_srv(). 
     98 * 
     99 * Application then creates each component by calling  
     100 * #pj_ice_strans_create_comp(); this would create an actual socket 
    82101 * which listens to the specified local address, and it would also 
    83102 * perform lookup to find various transport address candidates for this 
    84103 * socket. 
     104 * 
     105 * Adding component may involve contacting STUN and TURN servers to get 
     106 * STUN mapped address and allocate TURN relay channel, and this process 
     107 * may take some time to complete. Once application has added all 
     108 * components, it can check whether server reflexive and relayed  
     109 * candidates have been acquired, by calling #pj_ice_strans_get_comps_status(). 
    85110 *  
    86  * \subsection PJNATH_ICE_ST_TRA_INIT_ICE ICE Session Initialization 
     111 * \subsection PJNATH_ICE_ST_TRA_INIT_ICE Starting ICE Session 
    87112 * 
    88113 * When application is about to send an offer containing ICE capability, 
    … …  
    96121 * \subsection PJNATH_ICE_ST_TRA_START Starting Connectivity Checks 
    97122 * 
    98  * Once application receives the SDP from remote, it can start ICE 
    99  * connectivity checks by calling #pj_ice_strans_start_ice(), specifying 
    100  * the username, password, and candidates of the remote agent. The ICE 
    101  * session/transport will then notify the application via the callback 
    102  * when ICE connectivity checks completes, either successfully or with 
    103  * failure. 
     123 * Once application receives the SDP from remote, it pairs local candidates 
     124 * with remote candidates, and can start ICE connectivity checks. This is 
     125 * done by calling #pj_ice_strans_start_ice(), specifying 
     126 * the remote candidate list, and remote username and password. If the 
     127 * pairing process is successful, ICE connectivity checks will begin 
     128 * immediately. The ICE session/transport will then notify the application  
     129 * via the callback when ICE connectivity checks completes, either  
     130 * successfully or with failure. 
     131 * 
     132 * \subsection PJNATH_ICE_ST_TRA_SEND_RECV Sending and Receiving Data 
     133 * 
     134 * Application can send data (normally RTP or RTCP packets) at any time 
     135 * by calling #pj_ice_strans_sendto(). This function takes a destination 
     136 * address as one of the arguments, and this destination address should 
     137 * be taken from the default transport address of the component (that is 
     138 * the address in SDP c= and m= lines, or in a=rtcp attribute).  
     139 * If ICE negotiation is in progress, this function will send the data  
     140 * to the destination address. Otherwise if ICE negotiation has completed 
     141 * successfully, this function will send the data to the nominated remote  
     142 * address, as negotiated by ICE. 
     143 * 
     144 * Upon receiving incoming data (that is a non-STUN  message), the ICE 
     145 * stream transport will notify the application by calling \a on_rx_data() 
     146 * of the #pj_ice_strans_cb callback. 
    104147 * 
    105148 * \subsection PJNATH_ICE_ST_TRA_STOP Stopping ICE Session 
    … …  
    109152 * ICE session within this ICE stream transport. Note that this WILL NOT 
    110153 * destroy the sockets/transports, it only destroys the ICE session 
    111  * within this ICE stream transport. 
     154 * within this ICE stream transport. It is recommended that application  
     155 * retains the ICE stream transport to speed up the process of setting up 
     156 * the next call. The ICE stream transport will continue to send STUN  
     157 * keep-alive packets to keep the NAT binding open and to detect change  
     158 * in STUN mapped address. 
    112159 * 
    113160 * \subsection PJNATH_ICE_ST_TRA_RESTART Restarting ICE Session 
    … …  
    570617 * Send outgoing packet using this transport. If ICE checks have not  
    571618 * produced a valid check for the specified component ID, this function  
    572  * will return with failure. Otherwise it will send the packet to remote 
    573  * destination using the nominated local candidate as have been checked 
     619 * send to the destination address. Otherwise it will send the packet to 
     620 * remote destination using the nominated local candidate as have been checked 
    574621 * previously. 
    575622 * 

  • pjproject/trunk/pjnath/include/pjnath/types.h

    r1480 r1487  
    118118 * The STUN library is organized as follows: 
    119119 * 
    120  *  - the lowest layer of the library is \ref PJNATH_STUN_MSG. This layer 
    121  *    provides STUN message representation, validation, parsing, and 
    122  *    debugging (dump to log) of STUN messages. 
    123  * 
    124  *  - for client, the next higher layer is \ref PJNATH_STUN_TRANSACTION, 
    125  *    which manages retransmissions of STUN request. 
     120 *  - for both client and server, the highest abstraction is 
     121 *    \ref PJNATH_STUN_SESSION, which provides management of incoming 
     122 *    and outgoing messages and association of STUN credential to 
     123 *    a STUN session.  
     124 * 
     125 *  - for client, the next layer below is \ref PJNATH_STUN_TRANSACTION, 
     126 *    which manages retransmissions of STUN request. Server side STUN 
     127 *    transaction is handled in \ref PJNATH_STUN_SESSION layer above. 
    126128 * 
    127129 *  - \ref PJNATH_STUN_AUTH provides mechanism to verify STUN 
    128130 *    credential in incoming STUN messages. 
    129131 * 
    130  *  - for both client and server, the next higher abstraction is 
    131  *    \ref PJNATH_STUN_SESSION, which provides management of incoming 
    132  *    and outgoing messages and association of STUN credential to 
    133  *    a STUN session. 
    134  * 
    135  * As mentioned previously, all STUN library components are independent 
    136  * of any transports. Application gives incoming packet 
    137  * to the STUN components for processing. and it must supply the STUN  
    138  * components with callback to send outgoing messages. 
    139  *  
     132 *  - the lowest layer of the library is \ref PJNATH_STUN_MSG. This layer 
     133 *    provides STUN message representation, validation, parsing,  
     134 *    encoding MESSAGE-INTEGRITY for outgoing messages, and 
     135 *    debugging (dump to log) of STUN messages. 
     136 * 
     137 * All STUN library components are independent of any transports.  
     138 * Application gives incoming packet to the STUN components for processing, 
     139 * and it must supply the STUN components with callback to send outgoing  
     140 * messages. 
     141 *  
     142 * 
     143 * \subsection PJNATH_STUN_USING Using STUN Library 
     144 * 
     145 * [The developers guide documentation can certainly be improved here] 
     146 * 
     147 * For a sample STUN and TURN client, please see <tt>pjstun-client</tt> 
     148 * project under <tt>pjnath/src</tt> directory. 
     149 * 
     150 * For a sample STUN and TURN server, please see <tt>pjstun-srv-test</tt> 
     151 * project under <tt>pjnath/src</tt> directory. 
     152 * 
    140153 * 
    141154 * \subsection PJNATH_STUN_REF STUN Reference 
    … …  
    171184 * The ICE library is organized as follows: 
    172185 * 
     186 *  - the highest abstraction is ICE media transport, which maintains 
     187 *    ICE stream transport and provides SDP translations to be used 
     188 *    for SIP offer/answer exchanges. ICE media transport is part 
     189 *    of PJMEDIA library. 
     190 * 
     191 *  - higher in the hierarchy is \ref PJNATH_ICE_STREAM_TRANSPORT, 
     192 *    which binds ICE with UDP sockets, and provides STUN binding 
     193 *    and relay/TURN allocation for the sockets. This component can 
     194 *    be directly used by application, although normally application 
     195 *    should use the next higher abstraction since it provides 
     196 *    SDP translations and better integration with other PJ libraries 
     197 *    such as PJSIP and PJMEDIA. 
     198 * 
    173199 *  - the lowest layer is \ref PJNATH_ICE_SESSION, which provides  
    174200 *    ICE management and negotiation in a transport-independent way. 
    … …  
    178204 *    ICE implementors. 
    179205 * 
    180  *  - higher in the hierarchy is \ref PJNATH_ICE_STREAM_TRANSPORT, 
    181  *    which binds ICE with UDP sockets, and provides STUN binding 
    182  *    and relay/TURN allocation for the sockets. This component can 
    183  *    be directly used by application, although normally application 
    184  *    should use the next higher abstraction below since it provides 
    185  *    SDP translations and better integration with other PJ libraries 
    186  *    such as PJSIP and PJMEDIA. 
    187  * 
    188  *  - the highest abstraction is ICE media transport, which maintains 
    189  *    ICE stream transport and provides SDP translations to be used 
    190  *    for SIP offer/answer exchanges. 
     206 * \subsection PJNATH_ICE_USING Using the ICE Library 
     207 * 
     208 * For ICE implementation that has been integrated with socket transport, 
     209 * please see \ref PJNATH_ICE_STREAM_TRANSPORT_USING. 
     210 * 
     211 * For ICE implementation that has not been integrated with socket 
     212 * transport, please see \ref pj_ice_sess_using_sec. 
    191213 * 
    192214 * \subsection PJNATH_ICE_REF Reference 
Note: See TracChangeset for help on using the changeset viewer.