Ignore:
Timestamp:
Jun 6, 2008 2:47:10 PM (16 years ago)
Author:
bennylp
Message:

Major major modifications related to ticket #485 (support for TURN-07):

  • Added STUN socket transport pj_stun_sock
  • Integration of TURN-07 to ICE
  • Major refactoring in ICE stream transport to make it simpler
  • Major modification (i.e. API change) in almost everywhere else
  • Much more elaborate STUN, TURN, and ICE tests in pjnath-test
File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r1914 r1988  
    3030PJ_BEGIN_DECL 
    3131 
     32/** 
     33 * @defgroup PJNATH_TURN TURN Client Library 
     34 */ 
     35 
     36 
    3237/* **************************************************************************/ 
    3338/** 
    34  * @defgroup PJNATH_TURN_SESSION TURN client session 
     39 * @defgroup PJNATH_TURN_SESSION Transport independent TURN client session 
    3540 * @brief Transport independent TURN client session 
    36  * @ingroup PJNATH_STUN 
     41 * @ingroup PJNATH_TURN 
    3742 * @{ 
     43 * 
     44 * This module describes the transport independent TURN client session. This 
     45 * interface is provided for implementors of a TURN client transport, and 
     46 * application usually will want to use \ref PJNATH_TURN_SOCK instead. 
     47 * 
     48 * The transport independent TURN client session is created to facilitate 
     49 * the creation of different types of transports between the client and the 
     50 * TURN server. 
    3851 */ 
    3952 
    … …  
    4255 */ 
    4356typedef struct pj_turn_session pj_turn_session; 
    44  
    45  
    46 #define PJ_TURN_INVALID_CHANNEL     0xFFFF 
    47 #define PJ_TURN_CHANNEL_MIN         0x4000 
    48 #define PJ_TURN_CHANNEL_MAX         0xFFFE  /* inclusive */ 
    49 #define PJ_TURN_NO_TIMEOUT          ((long)0x7FFFFFFF) 
    50 #define PJ_TURN_MAX_PKT_LEN         3000 
    51 #define PJ_TURN_PERM_TIMEOUT        300 /* Must be greater than REFRESH_SEC_BEFORE */ 
    52 #define PJ_TURN_CHANNEL_TIMEOUT     600 /* Must be greater than REFRESH_SEC_BEFORE */ 
    53 #define PJ_TURN_REFRESH_SEC_BEFORE  60 
    54 #define PJ_TURN_KEEP_ALIVE_SEC      15 
    55 #define PJ_TURN_PEER_HTABLE_SIZE    8 
    5657 
    5758 
    … …  
    134135 
    135136 
    136 /* ChannelData header */ 
     137#pragma pack(1) 
     138 
     139/** 
     140 * This structure ChannelData header. All the fields are in network byte 
     141 * order when it's on the wire. 
     142 */ 
    137143typedef struct pj_turn_channel_data 
    138144{ 
    139     pj_uint16_t ch_number; 
    140     pj_uint16_t length; 
     145    pj_uint16_t ch_number;      /**< Channel number.    */ 
     146    pj_uint16_t length;         /**< Payload length.    */ 
    141147} pj_turn_channel_data; 
    142148 
     149 
     150#pragma pack() 
    143151 
    144152 
    … …  
    152160     * needs to send outgoing message. Since the TURN session doesn't 
    153161     * have a socket on its own, this callback must be implemented. 
     162     * 
     163     * @param sess      The TURN session. 
     164     * @param pkt       The packet/data to be sent. 
     165     * @param pkt_len   Length of the packet/data. 
     166     * @param dst_addr  Destination address of the packet. 
     167     * @param addr_len  Length of the destination address. 
     168     * 
     169     * @return          The callback should return the status of the 
     170     *                  send operation.  
    154171     */ 
    155172    pj_status_t (*on_send_pkt)(pj_turn_session *sess, 
    … …  
    157174                               unsigned pkt_len, 
    158175                               const pj_sockaddr_t *dst_addr, 
    159                                unsigned dst_addr_len); 
     176                               unsigned addr_len); 
    160177 
    161178    /** 
    … …  
    163180     * a channel number. 
    164181     * 
    165      * This callback is optional. 
     182     * This callback is optional since the nature of this callback is 
     183     * for information only. 
     184     * 
     185     * @param sess      The TURN session. 
     186     * @param peer_addr The peer address. 
     187     * @param addr_len  Length of the peer address. 
     188     * @param ch_num    The channel number associated with this peer address. 
    166189     */ 
    167190    void (*on_channel_bound)(pj_turn_session *sess, 
    … …  
    174197     * Data indication or ChannelData message from the TURN server. 
    175198     * 
    176      * This callback is optional. 
     199     * @param sess      The TURN session. 
     200     * @param pkt       The data/payload of the Data Indication or ChannelData 
     201     *                  packet. 
     202     * @param pkt_len   Length of the data/payload. 
     203     * @param peer_addr Peer address where this payload was received by 
     204     *                  the TURN server. 
     205     * @param addr_len  Length of the peer address. 
    177206     */ 
    178207    void (*on_rx_data)(pj_turn_session *sess, 
    179                        const pj_uint8_t *pkt, 
     208                       void *pkt, 
    180209                       unsigned pkt_len, 
    181210                       const pj_sockaddr_t *peer_addr, 
    … …  
    186215     * implement this callback at least to know that the TURN session is 
    187216     * going to be destroyed. 
    188      */ 
    189     void (*on_state)(pj_turn_session *sess, pj_turn_state_t old_state, 
     217     * 
     218     * @param sess      The TURN session. 
     219     * @param old_state The previous state of the session. 
     220     * @param new_state The current state of the session. 
     221     */ 
     222    void (*on_state)(pj_turn_session *sess,  
     223                     pj_turn_state_t old_state, 
    190224                     pj_turn_state_t new_state); 
    191225 
    … …  
    194228 
    195229/** 
    196  * Allocate parameter. 
     230 * Allocation parameter, which can be given when application calls  
     231 * pj_turn_session_alloc() to allocate relay address in the TURN server. 
     232 * Application should call pj_turn_alloc_param_default() to initialize 
     233 * this structure with the default values. 
    197234 */ 
    198235typedef struct pj_turn_alloc_param 
    199236{ 
     237    /** 
     238     * The requested BANDWIDTH. Default is zero to not request any 
     239     * specific bandwidth. 
     240     */ 
    200241    int     bandwidth; 
     242 
     243    /** 
     244     * The requested LIFETIME. Default is zero to not request any 
     245     * explicit allocation lifetime. 
     246     */ 
    201247    int     lifetime; 
     248 
     249    /** 
     250     * If set to non-zero, the TURN session will periodically send blank 
     251     * Send Indication every PJ_TURN_KEEP_ALIVE_SEC to refresh local 
     252     * NAT bindings. Default is zero. 
     253     */ 
    202254    int     ka_interval; 
     255 
    203256} pj_turn_alloc_param; 
    204257 
    205258 
    206259/** 
    207  * TURN session info. 
     260 * This structure describes TURN session info. 
    208261 */ 
    209262typedef struct pj_turn_session_info 
    … …  
    215268 
    216269    /** 
     270     * Last error (if session was terminated because of error) 
     271     */ 
     272    pj_status_t     last_status; 
     273 
     274    /** 
    217275     * Type of connection to the TURN server. 
    218276     */ 
    219     pj_turn_tp_type tp_type; 
     277    pj_turn_tp_type conn_type; 
     278 
     279    /** 
     280     * The selected TURN server address. 
     281     */ 
     282    pj_sockaddr     server; 
     283 
     284    /** 
     285     * Mapped address, as reported by the TURN server. 
     286     */ 
     287    pj_sockaddr     mapped_addr; 
    220288 
    221289    /** 
    … …  
    225293 
    226294    /** 
    227      * The selected TURN server address. 
    228      */ 
    229     pj_sockaddr     server; 
    230  
    231     /** 
    232295     * Current seconds before allocation expires. 
    233296     */ 
    … …  
    238301 
    239302/** 
    240  * Create default pj_turn_alloc_param. 
     303 * Initialize pj_turn_alloc_param with the default values. 
     304 * 
     305 * @param prm   The TURN allocation parameter to be initialized. 
    241306 */ 
    242307PJ_DECL(void) pj_turn_alloc_param_default(pj_turn_alloc_param *prm); 
    243308 
     309 
    244310/** 
    245311 * Duplicate pj_turn_alloc_param. 
     312 * 
     313 * @param pool  Pool to allocate memory (currently not used) 
     314 * @param dst   Destination parameter. 
     315 * @param src   Source parameter. 
    246316 */ 
    247317PJ_DECL(void) pj_turn_alloc_param_copy(pj_pool_t *pool,  
    … …  
    250320 
    251321/** 
    252  * Get TURN state name. 
     322 * Get string representation for the given TURN state. 
     323 * 
     324 * @param state The TURN session state. 
     325 * 
     326 * @return      The state name as NULL terminated string. 
    253327 */ 
    254328PJ_DECL(const char*) pj_turn_state_name(pj_turn_state_t state); 
    … …  
    256330 
    257331/** 
    258  * Create TURN client session. 
    259  */ 
    260 PJ_DECL(pj_status_t) pj_turn_session_create(pj_stun_config *cfg, 
     332 * Create a TURN session instance with the specified address family and 
     333 * connection type. Once TURN session instance is created, application 
     334 * must call pj_turn_session_alloc() to allocate a relay address in the TURN 
     335 * server. 
     336 * 
     337 * @param cfg           The STUN configuration which contains among other 
     338 *                      things the ioqueue and timer heap instance for 
     339 *                      the operation of this session. 
     340 * @param name          Optional name to identify this session in the log. 
     341 * @param af            Address family of the client connection. Currently 
     342 *                      pj_AF_INET() and pj_AF_INET6() are supported. 
     343 * @param conn_type     Connection type to the TURN server.  
     344 * @param cb            Callback to receive events from the TURN session. 
     345 * @param options       Option flags, currently this value must be zero. 
     346 * @param user_data     Arbitrary application data to be associated with 
     347 *                      this transport. 
     348 * @param p_sess        Pointer to receive the created instance of the 
     349 *                      TURN session. 
     350 * 
     351 * @return              PJ_SUCCESS if the operation has been successful, 
     352 *                      or the appropriate error code on failure. 
     353 */ 
     354PJ_DECL(pj_status_t) pj_turn_session_create(const pj_stun_config *cfg, 
    261355                                            const char *name, 
    262356                                            int af, 
    263357                                            pj_turn_tp_type conn_type, 
    264358                                            const pj_turn_session_cb *cb, 
     359                                            unsigned options, 
    265360                                            void *user_data, 
    266                                             unsigned options, 
    267361                                            pj_turn_session **p_sess); 
    268362 
    269  
    270 /** 
    271  * Shutdown TURN client session. 
     363/** 
     364 * Shutdown TURN client session. This will gracefully deallocate and 
     365 * destroy the client session. 
     366 * 
     367 * @param sess          The TURN client session. 
     368 * 
     369 * @return              PJ_SUCCESS if the operation has been successful, 
     370 *                      or the appropriate error code on failure. 
    272371 */ 
    273372PJ_DECL(pj_status_t) pj_turn_session_shutdown(pj_turn_session *sess); 
    … …  
    275374 
    276375/** 
    277  * Forcefully destroy the TURN session. 
     376 * Forcefully destroy the TURN session. This will destroy the session 
     377 * immediately. If there is an active allocation, the server will not 
     378 * be notified about the client destruction. 
     379 * 
     380 * @param sess          The TURN client session. 
     381 * 
     382 * @return              PJ_SUCCESS if the operation has been successful, 
     383 *                      or the appropriate error code on failure. 
    278384 */ 
    279385PJ_DECL(pj_status_t) pj_turn_session_destroy(pj_turn_session *sess); 
    … …  
    281387 
    282388/** 
    283  * Get TURN session info. 
     389 * Get the information about this TURN session and the allocation, if 
     390 * any. 
     391 * 
     392 * @param sess          The TURN client session. 
     393 * @param info          The structure to be initialized with the TURN 
     394 *                      session info. 
     395 * 
     396 * @return              PJ_SUCCESS if the operation has been successful, 
     397 *                      or the appropriate error code on failure. 
    284398 */ 
    285399PJ_DECL(pj_status_t) pj_turn_session_get_info(pj_turn_session *sess, 
    … …  
    287401 
    288402/** 
    289  * Re-assign user data. 
     403 * Associate a user data with this TURN session. The user data may then 
     404 * be retrieved later with pj_turn_session_get_user_data(). 
     405 * 
     406 * @param sess          The TURN client session. 
     407 * @param user_data     Arbitrary data. 
     408 * 
     409 * @return              PJ_SUCCESS if the operation has been successful, 
     410 *                      or the appropriate error code on failure. 
    290411 */ 
    291412PJ_DECL(pj_status_t) pj_turn_session_set_user_data(pj_turn_session *sess, 
    … …  
    293414 
    294415/** 
    295  * Retrieve user data. 
     416 * Retrieve the previously assigned user data associated with this TURN 
     417 * session. 
     418 * 
     419 * @param sess          The TURN client session. 
     420 * 
     421 * @return              The user/application data. 
    296422 */ 
    297423PJ_DECL(void*) pj_turn_session_get_user_data(pj_turn_session *sess); 
    298424 
    299 /** 
    300  * Set the server or domain name of the server. 
     425 
     426/** 
     427 * Configure message logging. By default all flags are enabled. 
     428 * 
     429 * @param sess          The TURN client session. 
     430 * @param flags         Bitmask combination of #pj_stun_sess_msg_log_flag 
     431 */ 
     432PJ_DECL(void) pj_turn_session_set_log(pj_turn_session *sess, 
     433                                      unsigned flags); 
     434 
     435 
     436/** 
     437 * Set the server or domain name of the server. Before the application 
     438 * can send Allocate request (with pj_turn_session_alloc()), it must first 
     439 * resolve the server address(es) using this function. This function will 
     440 * resolve the TURN server using DNS SRV resolution if the \a resolver 
     441 * is set. The server resolution process will complete asynchronously, 
     442 * and application will be notified in \a on_state() callback with the 
     443 * session state set to PJ_TURN_STATE_RESOLVED. 
     444 * 
     445 * Application may call with pj_turn_session_alloc() before the server 
     446 * resolution completes. In this case, the operation will be queued by 
     447 * the session, and it will be sent once the server resolution completes. 
     448 * 
     449 * @param sess          The TURN client session. 
     450 * @param domain        The domain, hostname, or IP address of the TURN 
     451 *                      server. When this parameter contains domain name, 
     452 *                      the \a resolver parameter must be set to activate 
     453 *                      DNS SRV resolution. 
     454 * @param default_port  The default TURN port number to use when DNS SRV 
     455 *                      resolution is not used. If DNS SRV resolution is 
     456 *                      used, the server port number will be set from the 
     457 *                      DNS SRV records. 
     458 * @param resolver      If this parameter is not NULL, then the \a domain 
     459 *                      parameter will be first resolved with DNS SRV and 
     460 *                      then fallback to using DNS A/AAAA resolution when 
     461 *                      DNS SRV resolution fails. If this parameter is 
     462 *                      NULL, the \a domain parameter will be resolved as 
     463 *                      hostname. 
     464 * 
     465 * @return              PJ_SUCCESS if the operation has been successfully 
     466 *                      queued, or the appropriate error code on failure. 
     467 *                      When this function returns PJ_SUCCESS, the final 
     468 *                      result of the resolution process will be notified 
     469 *                      to application in \a on_state() callback. 
    301470 */ 
    302471PJ_DECL(pj_status_t) pj_turn_session_set_server(pj_turn_session *sess, 
    … …  
    307476 
    308477/** 
    309  * Set credential to be used by the session. 
     478 * Set credential to be used to authenticate against TURN server.  
     479 * Application must call this function before sending Allocate request 
     480 * with pj_turn_session_alloc(). 
     481 * 
     482 * @param sess          The TURN client session 
     483 * @param cred          STUN credential to be used. 
     484 * 
     485 * @return              PJ_SUCCESS if the operation has been successful, 
     486 *                      or the appropriate error code on failure. 
    310487 */ 
    311488PJ_DECL(pj_status_t) pj_turn_session_set_credential(pj_turn_session *sess, 
    … …  
    314491 
    315492/** 
    316  * Create TURN allocation. 
     493 * Allocate a relay address/resource in the TURN server by sending TURN 
     494 * Allocate request. Application must first initiate the server resolution 
     495 * process with pj_turn_session_set_server() and set the credential to be 
     496 * used with pj_turn_session_set_credential() before calling this function. 
     497 * 
     498 * This function will complete asynchronously, and the application will be 
     499 * notified about the allocation result in \a on_state() callback. The  
     500 * TURN session state will move to PJ_TURN_STATE_READY if allocation is 
     501 * successful, and PJ_TURN_STATE_DEALLOCATING or greater state if allocation 
     502 * has failed. 
     503 * 
     504 * Once allocation has been successful, the TURN session will keep this 
     505 * allocation alive until the session is destroyed, by sending periodic 
     506 * allocation refresh to the TURN server. 
     507 * 
     508 * @param sess          The TURN client session. 
     509 * @param param         Optional TURN allocation parameter. 
     510 * 
     511 * @return              PJ_SUCCESS if the operation has been successfully 
     512 *                      initiated or the appropriate error code on failure. 
    317513 */ 
    318514PJ_DECL(pj_status_t) pj_turn_session_alloc(pj_turn_session *sess, 
    … …  
    321517 
    322518/** 
    323  * Relay data to the specified peer through the session. 
     519 * Send a data to the specified peer address via the TURN relay. This  
     520 * function will encapsulate the data as STUN Send Indication or TURN 
     521 * ChannelData packet and send the message to the TURN server. The TURN 
     522 * server then will send the data to the peer. 
     523 * 
     524 * The allocation (pj_turn_session_alloc()) must have been successfully 
     525 * created before application can relay any data. 
     526 * 
     527 * Since TURN session is transport independent, this function will 
     528 * ultimately call \a on_send_pkt() callback to request the application  
     529 * to actually send the packet containing the data to the TURN server. 
     530 * 
     531 * @param sess          The TURN client session. 
     532 * @param pkt           The data/packet to be sent to peer. 
     533 * @param pkt_len       Length of the data. 
     534 * @param peer_addr     The remote peer address (the ultimate destination 
     535 *                      of the data, and not the TURN server address). 
     536 * @param addr_len      Length of the address. 
     537 * 
     538 * @return              PJ_SUCCESS if the operation has been successful, 
     539 *                      or the appropriate error code on failure. 
    324540 */ 
    325541PJ_DECL(pj_status_t) pj_turn_session_sendto(pj_turn_session *sess, 
    326542                                            const pj_uint8_t *pkt, 
    327543                                            unsigned pkt_len, 
    328                                             const pj_sockaddr_t *addr, 
     544                                            const pj_sockaddr_t *peer_addr, 
    329545                                            unsigned addr_len); 
    330546 
    331547/** 
    332  * Bind a peer address to a channel number. 
     548 * Optionally establish channel binding for the specified a peer address. 
     549 * This function will assign a unique channel number for the peer address 
     550 * and request channel binding to the TURN server for this address. When 
     551 * a channel has been bound to a peer, the TURN client and TURN server 
     552 * will exchange data using ChannelData encapsulation format, which has 
     553 * lower bandwidth overhead than Send Indication (the default format used 
     554 * when peer address is not bound to a channel). 
     555 * 
     556 * This function will complete asynchronously, and application will be 
     557 * notified about the result in \a on_channel_bound() callback. 
     558 * 
     559 * @param sess          The TURN client session. 
     560 * @param peer          The remote peer address. 
     561 * @param addr_len      Length of the address. 
     562 * 
     563 * @return              PJ_SUCCESS if the operation has been successfully 
     564 *                      initiated, or the appropriate error code on failure. 
    333565 */ 
    334566PJ_DECL(pj_status_t) pj_turn_session_bind_channel(pj_turn_session *sess, 
    … …  
    337569 
    338570/** 
    339  * Notify TURN client session upon receiving a packet from server. 
    340  * The packet maybe a STUN packet or ChannelData packet. 
     571 * Notify TURN client session upon receiving a packet from server. Since 
     572 * the TURN session is transport independent, it does not read packet from 
     573 * any sockets, and rather relies on application giving it packets that 
     574 * are received from the TURN server. The session then processes this packet 
     575 * and decides whether it is part of TURN protocol exchange or if it is a 
     576 * data to be reported back to user, which in this case it will call the 
     577 * \a on_rx_data() callback. 
     578 * 
     579 * @param sess          The TURN client session. 
     580 * @param pkt           The packet as received from the TURN server. This 
     581 *                      should contain either STUN encapsulated message or 
     582 *                      a ChannelData packet. 
     583 * @param pkt_len       The length of the packet. 
     584 * 
     585 * @return              The function may return non-PJ_SUCCESS if it receives 
     586 *                      non-STUN and non-ChannelData packet, or if the 
     587 *                      \a on_rx_data() returns non-PJ_SUCCESS; 
    341588 */ 
    342589PJ_DECL(pj_status_t) pj_turn_session_on_rx_pkt(pj_turn_session *sess, 
    343                                                const pj_uint8_t *pkt, 
    344                                                unsigned pkt_len, 
    345                                                pj_bool_t is_datagram); 
     590                                               void *pkt, 
     591                                               unsigned pkt_len); 
    346592 
    347593 
Note: See TracChangeset for help on using the changeset viewer.