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/ice_strans.h

    r1487 r1988  
    2626 */ 
    2727#include <pjnath/ice_session.h> 
     28#include <pjnath/stun_sock.h> 
     29#include <pjnath/turn_sock.h> 
    2830#include <pjlib-util/resolver.h> 
    2931#include <pj/ioqueue.h> 
    … …  
    4547 * 
    4648 * ICE stream transport, as represented by #pj_ice_strans structure, is an ICE 
    47  * capable component for transporting media streams within a media session.  
     49 * capable class for transporting media streams within a media session.  
    4850 * It consists of one or more transport sockets (typically two for RTP 
    4951 * based communication - one for RTP and one for RTCP), and an  
    … …  
    5153 * various candidates of the transport addresses. 
    5254 * 
    53  * \section PJNATH_ICE_STREAM_TRANSPORT_USING Using the ICE Stream Transport 
    54  * 
    55  * Application may use the ICE stream transport in two ways: 
    56  *  - it can create the ICE stream transports once during application  
    57  *    initialization and keep them alive throughout application lifetime, or 
    58  *  - it can create and destroy the ICE stream transport as needed everytime  
    59  *     a call is made and destroyed.  
    60  * 
    61  * Keeping the ICE stream transport alive throughout 
    62  * application's lifetime is normally preferable, as initializing the 
    63  * ICE stream transport may incur delay because the ICE stream transport 
    64  * would need to communicate with the STUN/TURN server to get the 
    65  * server reflexive and relayed candidates for the transports. 
    66  * 
    67  * Regardless of which usage scenario is being used, the ICE stream 
    68  * transport is capable for restarting the ICE session being used and to 
    69  * send STUN keep-alives for its STUN server reflexive and relayed 
    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 
    76  * 
    77  * Application creates the ICE stream transport by calling  
    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. 
    93  * 
    94  * After the ICE stream transport is created, application may set up the 
    95  * STUN servers to be used to obtain STUN server reflexive and relayed 
    96  * candidate, by calling #pj_ice_strans_set_stun_domain() or  
    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 
    101  * which listens to the specified local address, and it would also 
    102  * perform lookup to find various transport address candidates for this 
    103  * 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(). 
    110  *  
    111  * \subsection PJNATH_ICE_ST_TRA_INIT_ICE Starting ICE Session 
    112  * 
    113  * When application is about to send an offer containing ICE capability, 
    114  * or when it receives an offer containing ICE capability, it would 
    115  * create the ICE session by calling #pj_ice_strans_init_ice(). This would 
    116  * register all transport address aliases for each component to the ICE 
    117  * session as candidates. After this application can enumerate all local 
    118  * candidates by calling #pj_ice_strans_enum_cands(), and encode these 
    119  * candidates in the SDP to be sent to remote agent. 
    120  * 
    121  * \subsection PJNATH_ICE_ST_TRA_START Starting Connectivity Checks 
    122  * 
    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. 
    147  * 
    148  * \subsection PJNATH_ICE_ST_TRA_STOP Stopping ICE Session 
    149  * 
    150  * Once the call is terminated, application no longer needs to keep the 
    151  * ICE session, so it should call #pj_ice_strans_stop_ice() to destroy the 
    152  * ICE session within this ICE stream transport. Note that this WILL NOT 
    153  * destroy the sockets/transports, it only destroys the ICE session 
    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. 
    159  * 
    160  * \subsection PJNATH_ICE_ST_TRA_RESTART Restarting ICE Session 
    161  * 
    162  * When a new call is made, application can repeat the above 
    163  * #pj_ice_strans_init_ice() to #pj_ice_strans_stop_ice() cycle for  
    164  * the new call, using this same ICE stream transport. 
    165  * 
    166  * \subsection PJNATH_ICE_ST_TRA_DESTROY Destroying ICE Stream Transport 
    167  * 
    168  * Finally, when the ICE stream transport itself is no longer needed, 
    169  * for example when the application quits, application should call 
    170  * #pj_ice_strans_destroy() to release back all resources allocated by this 
    171  * ICE stream transport. 
    172  * 
    17355 */ 
    17456 
    17557/** Forward declaration for ICE stream transport. */ 
    17658typedef struct pj_ice_strans pj_ice_strans; 
     59 
     60/** Transport operation types to be reported on \a on_status() callback */ 
     61typedef enum pj_ice_strans_op 
     62{ 
     63    /** Initialization (candidate gathering) */ 
     64    PJ_ICE_STRANS_OP_INIT, 
     65 
     66    /** Negotiation */ 
     67    PJ_ICE_STRANS_OP_NEGOTIATION 
     68 
     69} pj_ice_strans_op; 
    17770 
    17871/**  
    … …  
    20194 
    20295    /** 
    203      * This callback will be called when ICE checks have completed. 
    204      * This callback is optional. 
     96     * Callback to report status. 
    20597     *  
    20698     * @param ice_st        The ICE stream transport. 
    207      * @param status        The ICE connectivity check status. 
     99     * @param op            The operation 
     100     * @param status        Operation status. 
    208101     */ 
    209102    void    (*on_ice_complete)(pj_ice_strans *ice_st,  
     103                               pj_ice_strans_op op, 
    210104                               pj_status_t status); 
    211105 
    212     /** 
    213      * This callback will be called when ICE transport has detected that 
    214      * the STUN mapped address of a candidate has changed. 
     106} pj_ice_strans_cb; 
     107 
     108 
     109/** 
     110 * This structure describes ICE stream transport configuration. Application 
     111 * should initialize the structure by calling #pj_ice_strans_cfg_default() 
     112 * before changing the settings. 
     113 */ 
     114typedef struct pj_ice_strans_cfg 
     115{ 
     116    /** 
     117     * Address family, IPv4 or IPv6. Currently only pj_AF_INET() (IPv4) 
     118     * is supported, and this is the default value. 
     119     */ 
     120    int                 af; 
     121 
     122    /** 
     123     * STUN configuration which contains the timer heap and 
     124     * ioqueue instance to be used, and STUN retransmission 
     125     * settings. This setting is mandatory. 
    215126     * 
    216      * @param ice_st        The ICE stream transport. 
    217      * @param comp_id       Component ID. 
    218      * @param cand_id       Candidate ID. 
    219      */ 
    220     void    (*on_addr_change)(pj_ice_strans *ice_st,  
    221                               unsigned comp_id,  
    222                               unsigned cand_id); 
    223                                
    224 } pj_ice_strans_cb; 
    225  
    226  
    227 /** 
    228  * Various flags that can be specified when creating a component with 
    229  * #pj_ice_strans_create_comp(). These options may be combined together 
    230  * with bitmask operation. 
    231  */ 
    232 enum pj_ice_strans_option 
    233 { 
    234     /** 
    235      * If this option is specified, only a listening socket will be 
    236      * created for the component, and no candidate will be added to 
    237      * the component. Application must add the component manually 
    238      * by inspecting the socket and transport address of the component. 
    239      */ 
    240     PJ_ICE_ST_OPT_DONT_ADD_CAND = 1, 
    241  
    242     /** 
    243      * If this option is specified, then no STUN reflexive candidate 
    244      * will be added to the component. 
    245      */ 
    246     PJ_ICE_ST_OPT_DISABLE_STUN  = 2, 
    247  
    248     /** 
    249      * If this option is specified, then no STUN relay candidate 
    250      * will be added to the component. 
    251      */ 
    252     PJ_ICE_ST_OPT_DISABLE_RELAY = 4, 
    253  
    254     /** 
    255      * If this option is specified, then when the function fails to 
    256      * bind the socket to the specified port, it WILL NOT try to 
    257      * bind the socket to the next available port. 
     127     * The default value is all zero. Application must initialize 
     128     * this setting with #pj_stun_config_init(). 
     129     */ 
     130    pj_stun_config       stun_cfg; 
     131 
     132    /** 
     133     * DNS resolver to be used to resolve servers. If DNS SRV 
     134     * resolution is required, the resolver must be set. 
    258135     * 
    259      * If this option is NOT specified, then the function will try to 
    260      * bind the socket to next port+2, repetitively until the socket 
    261      * is bound successfully. 
    262      */ 
    263     PJ_ICE_ST_OPT_NO_PORT_RETRY = 8, 
    264 }; 
    265  
    266  
    267 /** 
    268  * This structure describes ICE stream transport candidate. A "candidate" 
    269  * in ICE stream transport can be viewed as alias transport address 
    270  * for the socket. 
    271  */ 
    272 typedef struct pj_ice_strans_cand 
    273 { 
    274     /** 
    275      * Candidate type. 
    276      */ 
    277     pj_ice_cand_type    type; 
    278  
    279     /**  
    280      * Status of this candidate. This status is useful for ICE reflexive 
    281      * and relay candidate, where the address needs to be resolved  
    282      * asynchronously by sending STUN request to STUN server. 
    283      * 
    284      * The value will be PJ_SUCCESS if candidate address has been resolved 
    285      * successfully, PJ_EPENDING when the address resolution process is 
    286      * in progress, or other value when the address resolution has 
    287      * completed with failure. 
    288      */ 
    289     pj_status_t         status; 
    290  
    291     /** 
    292      * The candidate transport address. 
    293      */ 
    294     pj_sockaddr         addr; 
    295  
    296     /** 
    297      * The ICE session candidate ID after this candidate has been registered 
    298      * to an ICE session. Before ICE session is created, or after ICE 
    299      * session has been destroyed, the value will be -1. 
    300      */ 
    301     int                 ice_cand_id; 
    302  
    303     /** 
    304      * Local preference value, which typically is 65535. 
    305      */ 
    306     pj_uint16_t         local_pref; 
    307  
    308     /** 
    309      * Foundation associated with this candidate, which value normally will be 
    310      * calculated by the function. 
    311      */ 
    312     pj_str_t            foundation; 
    313  
    314 } pj_ice_strans_cand; 
    315  
    316  
    317 /** 
    318  * This structure describes an ICE stream transport component. A component 
    319  * in ICE stream transport typically corresponds to a single socket created 
    320  * for this component, and bound to a specific transport address. This 
    321  * component may have multiple alias addresses, for example one alias  
    322  * address for each interfaces in multi-homed host, another for server 
    323  * reflexive alias, and another for relayed alias. For each transport 
    324  * address alias, an ICE stream transport candidate (#pj_ice_strans_cand) will 
    325  * be created, and these candidates will eventually registered to the ICE 
    326  * session. 
    327  */ 
    328 typedef struct pj_ice_strans_comp 
    329 { 
    330     pj_ice_strans       *ice_st;        /**< ICE stream transport.      */ 
    331     unsigned             comp_id;       /**< Component ID.              */ 
    332     pj_uint32_t          options;       /**< Option flags.              */ 
    333     pj_sock_t            sock;          /**< Socket descriptor.         */ 
    334  
    335     pj_stun_session     *stun_sess;     /**< STUN session.              */ 
    336     pj_uint8_t           ka_tsx_id[12]; /**< ID for keep STUN alives    */ 
    337  
    338     pj_sockaddr          local_addr;    /**< Local/base address.        */ 
    339  
    340     unsigned             pending_cnt;   /**< Pending resolution cnt.    */ 
    341     pj_status_t          last_status;   /**< Last status.               */ 
    342  
    343     unsigned             cand_cnt;      /**< # of candidates/aliaes.    */ 
    344     pj_ice_strans_cand   cand_list[PJ_ICE_ST_MAX_CAND]; /**< Cand array */ 
    345     int                  default_cand;  /**< Default candidate selected */ 
    346  
    347     pj_ioqueue_key_t    *key;           /**< ioqueue key.               */ 
    348     pj_uint8_t           pkt[1500];     /**< Incoming packet buffer.    */ 
    349     pj_ioqueue_op_key_t  read_op;       /**< ioqueue read operation key */ 
    350     pj_ioqueue_op_key_t  write_op;      /**< ioqueue write op. key      */ 
    351     pj_sockaddr          src_addr;      /**< source packet address buf. */ 
    352     int                  src_addr_len;  /**< length of src addr. buf.   */ 
    353  
    354 } pj_ice_strans_comp; 
    355  
    356  
    357 /** 
    358  * This structure represents the ICE stream transport. 
    359  */ 
    360 struct pj_ice_strans 
    361 { 
    362     char                     obj_name[PJ_MAX_OBJ_NAME]; /**< Log ID.    */ 
    363  
    364     pj_pool_t               *pool;      /**< Pool used by this object.  */ 
    365     void                    *user_data; /**< Application data.          */ 
    366     pj_stun_config           stun_cfg;  /**< STUN settings.             */ 
    367     pj_ice_strans_cb         cb;        /**< Application callback.      */ 
    368  
    369     pj_ice_sess             *ice;       /**< ICE session.               */ 
    370  
    371     unsigned                 comp_cnt;  /**< Number of components.      */ 
    372     pj_ice_strans_comp     **comp;      /**< Components array.          */ 
    373  
    374     pj_dns_resolver         *resolver;  /**< The resolver instance.     */ 
    375     pj_bool_t                has_rjob;  /**< Has pending resolve?       */ 
    376     pj_sockaddr_in           stun_srv;  /**< STUN server address.       */ 
    377     pj_sockaddr_in           turn_srv;  /**< TURN server address.       */ 
    378  
    379     pj_timer_entry           ka_timer;  /**< STUN keep-alive timer.     */ 
    380 }; 
    381  
    382  
    383 /** 
    384  * Create the ICE stream transport containing the specified number of 
    385  * components. After the ICE stream transport is created, application 
    386  * may initialize the STUN server settings, and after that it has to  
    387  * initialize each components by calling #pj_ice_strans_create_comp() 
    388  * function. 
    389  * 
    390  * @param stun_cfg      The STUN settings. 
     136     * The default value is NULL. 
     137     */ 
     138    pj_dns_resolver     *resolver; 
     139 
     140    /** 
     141     * STUN and local transport settings. This specifies the  
     142     * settings for local UDP socket, which will be resolved 
     143     * to get the STUN mapped address. 
     144     */ 
     145    struct { 
     146        /** 
     147         * Optional configuration for STUN transport. The default 
     148         * value will be initialized with #pj_stun_sock_cfg_default(). 
     149         */ 
     150        pj_stun_sock_cfg     cfg; 
     151 
     152        /** 
     153         * Disable host candidates. When this option is set, no 
     154         * host candidates will be added. 
     155         * 
     156         * Default: PJ_FALSE 
     157         */ 
     158        pj_bool_t            no_host_cands; 
     159 
     160        /** 
     161         * Include loopback addresses in the host candidates. 
     162         * 
     163         * Default: PJ_FALSE 
     164         */ 
     165        pj_bool_t            loop_addr; 
     166 
     167        /** 
     168         * Specify the STUN server domain or hostname or IP address. 
     169         * If DNS SRV resolution is required, application must fill 
     170         * in this setting with the domain name of the STUN server  
     171         * and set the resolver instance in the \a resolver field. 
     172         * Otherwise if the \a resolver setting is not set, this 
     173         * field will be resolved with hostname resolution and in 
     174         * this case the \a port field must be set. 
     175         * 
     176         * The \a port field should also be set even when DNS SRV 
     177         * resolution is used, in case the DNS SRV resolution fails. 
     178         * 
     179         * When this field is empty, STUN mapped address resolution 
     180         * will not be performed. In this case only ICE host candidates 
     181         * will be added to the ICE transport, unless if \a no_host_cands 
     182         * field is set. In this case, both host and srflx candidates  
     183         * are disabled. 
     184         * 
     185         * The default value is empty. 
     186         */ 
     187        pj_str_t             server; 
     188 
     189        /** 
     190         * The port number of the STUN server, when \a server 
     191         * field specifies a hostname rather than domain name. This 
     192         * field should also be set even when the \a server 
     193         * specifies a domain name, to allow DNS SRV resolution 
     194         * to fallback to DNS A/AAAA resolution when the DNS SRV 
     195         * resolution fails. 
     196         * 
     197         * The default value is PJ_STUN_PORT. 
     198         */ 
     199        pj_uint16_t          port; 
     200 
     201    } stun; 
     202 
     203    /** 
     204     * TURN specific settings. 
     205     */ 
     206    struct { 
     207        /** 
     208         * Specify the TURN server domain or hostname or IP address. 
     209         * If DNS SRV resolution is required, application must fill 
     210         * in this setting with the domain name of the TURN server  
     211         * and set the resolver instance in the \a resolver field. 
     212         * Otherwise if the \a resolver setting is not set, this 
     213         * field will be resolved with hostname resolution and in 
     214         * this case the \a port field must be set. 
     215         * 
     216         * The \a port field should also be set even when DNS SRV 
     217         * resolution is used, in case the DNS SRV resolution fails. 
     218         * 
     219         * When this field is empty, relay candidate will not be 
     220         * created. 
     221         * 
     222         * The default value is empty. 
     223         */ 
     224        pj_str_t             server; 
     225 
     226        /** 
     227         * The port number of the TURN server, when \a server 
     228         * field specifies a hostname rather than domain name. This 
     229         * field should also be set even when the \a server 
     230         * specifies a domain name, to allow DNS SRV resolution 
     231         * to fallback to DNS A/AAAA resolution when the DNS SRV 
     232         * resolution fails. 
     233         * 
     234         * Default is zero. 
     235         */ 
     236        pj_uint16_t          port; 
     237 
     238        /** 
     239         * Type of connection to the TURN server. 
     240         * 
     241         * Default is PJ_TURN_TP_UDP. 
     242         */ 
     243        pj_turn_tp_type      conn_type; 
     244 
     245        /** 
     246         * Credential to be used for the TURN session. This setting 
     247         * is mandatory. 
     248         * 
     249         * Default is to have no credential. 
     250         */ 
     251        pj_stun_auth_cred    auth_cred; 
     252 
     253        /** 
     254         * Optional TURN Allocate parameter. The default value will be 
     255         * initialized by #pj_turn_alloc_param_default(). 
     256         */ 
     257        pj_turn_alloc_param  alloc_param; 
     258 
     259    } turn; 
     260 
     261} pj_ice_strans_cfg; 
     262 
     263 
     264/**  
     265 * Initialize ICE transport configuration with default values. 
     266 * 
     267 * @param cfg           The configuration to be initialized. 
     268 */ 
     269PJ_DECL(void) pj_ice_strans_cfg_default(pj_ice_strans_cfg *cfg); 
     270 
     271 
     272/** 
     273 * Copy configuration. 
     274 * 
     275 * @param pool          Pool. 
     276 * @param dst           Destination. 
     277 * @param src           Source. 
     278 */ 
     279PJ_DECL(void) pj_ice_strans_cfg_copy(pj_pool_t *pool, 
     280                                     pj_ice_strans_cfg *dst, 
     281                                     const pj_ice_strans_cfg *src); 
     282 
     283 
     284/** 
     285 * Create and initialize the ICE stream transport with the specified 
     286 * parameters.  
     287 * 
    391288 * @param name          Optional name for logging identification. 
     289 * @param cfg           Configuration. 
    392290 * @param comp_cnt      Number of components. 
    393291 * @param user_data     Arbitrary user data to be associated with this 
    … …  
    400298 *                      successfully. 
    401299 */ 
    402 PJ_DECL(pj_status_t) pj_ice_strans_create(pj_stun_config *stun_cfg, 
    403                                           const char *name, 
     300PJ_DECL(pj_status_t) pj_ice_strans_create(const char *name, 
     301                                          const pj_ice_strans_cfg *cfg, 
    404302                                          unsigned comp_cnt, 
    405303                                          void *user_data, 
    … …  
    420318 
    421319/** 
    422  * Set the domain to be used when resolving the STUN servers. If application 
    423  * wants to utillize STUN, then STUN server must be specified, either by 
    424  * calling this function or by calling #pj_ice_strans_set_stun_srv(). 
    425  * 
    426  * If application calls this function, then the STUN/TURN servers will 
    427  * be resolved by querying DNS SRV records for the specified domain. 
    428  * 
    429  * @param ice_st        The ICE stream transport. 
    430  * @param resolver      The resolver instance that will be used to 
    431  *                      resolve the STUN/TURN servers. 
    432  * @param domain        The target domain. 
    433  * 
    434  * @return              PJ_SUCCESS if DNS SRV resolution job can be 
    435  *                      started. The resolution process itself will 
    436  *                      complete asynchronously. 
    437  */ 
    438 PJ_DECL(pj_status_t) pj_ice_strans_set_stun_domain(pj_ice_strans *ice_st, 
    439                                                    pj_dns_resolver *resolver, 
    440                                                    const pj_str_t *domain); 
    441  
    442 /** 
    443  * Set the STUN and TURN server addresses. If application 
    444  * wants to utillize STUN, then STUN server must be specified, either by 
    445  * calling this function or by calling #pj_ice_strans_set_stun_domain(). 
    446  * 
    447  * With this function, the STUN and TURN server addresses will be  
    448  * assigned immediately, that is no DNS resolution will need to be  
    449  * performed. 
    450  * 
    451  * @param ice_st        The ICE stream transport. 
    452  * @param stun_srv      The STUN server address, or NULL if STUN 
    453  *                      reflexive candidate is not to be used. 
    454  * @param turn_srv      The TURN server address, or NULL if STUN 
    455  *                      relay candidate is not to be used. 
    456  * 
    457  * @return              PJ_SUCCESS, or the appropriate error code. 
    458  */ 
    459 PJ_DECL(pj_status_t)  
    460 pj_ice_strans_set_stun_srv( pj_ice_strans *ice_st, 
    461                             const pj_sockaddr_in *stun_srv, 
    462                             const pj_sockaddr_in *turn_srv); 
    463  
    464 /** 
    465  * Create and initialize the specified component. This function will 
    466  * instantiate the socket descriptor for this component, optionally 
    467  * bind the socket to the specified address (or bind to any address/port 
    468  * if the \a addr parameter is NULL), and start finding all alias 
    469  * addresses for this socket. For each alias addresses that if finds, 
    470  * it will add an ICE stream transport candidate for this component. 
    471  * 
    472  * After all components have been initialized, application should poll 
    473  * the #pj_ice_strans_get_comps_status() peridically to check if STUN 
    474  * server reflexive and relayed candidates have been obtained 
    475  * successfully. 
    476  * 
    477  * @param ice_st        The ICE stream transport. 
    478  * @param comp_id       The component ID, which value must be greater than 
    479  *                      zero and less than or equal to the number of  
    480  *                      components in this ICE stream transport. 
    481  * @param options       Options, see #pj_ice_strans_option. 
    482  * @param addr          Local address where socket will be bound to. This 
    483  *                      address will be used as follows: 
    484  *                      - if the value is NULL, then socket will be bound 
    485  *                        to any available port. 
    486  *                      - if the value is not NULL, then if the port number 
    487  *                        is not zero, it will used as the starting port  
    488  *                        where the socket will be bound to. If bind() to 
    489  *                        this port fails, this function will try to bind 
    490  *                        to port+2, repeatedly until it succeeded. 
    491  *                        If application doesn't want this function to  
    492  *                        retry binding the socket to other port, it can 
    493  *                        specify PJ_ICE_ST_OPT_NO_PORT_RETRY option. 
    494  *                      - if the value is not NULL, then if the address 
    495  *                        is not INADDR_ANY, this function will bind the 
    496  *                        socket to this particular interface only, and 
    497  *                        no other host candidates will be added for this 
    498  *                        socket. 
    499  *                       
    500  * 
    501  * @return              PJ_SUCCESS, or the appropriate error code. 
    502  */ 
    503 PJ_DECL(pj_status_t) pj_ice_strans_create_comp(pj_ice_strans *ice_st, 
    504                                                unsigned comp_id, 
    505                                                pj_uint32_t options, 
    506                                                const pj_sockaddr_in *addr); 
    507  
    508 /** 
    509  * Manually add a candidate (transport address alias) for the specified 
    510  * component. Normally application shouldn't need to use this function, 
    511  * as candidates will be added automatically when component is created 
    512  * with #pj_ice_strans_create_comp(). 
    513  * 
    514  * @param ice_st        ICE stream transport. 
    515  * @param comp_id       The component ID. 
    516  * @param type          The candidate type. 
    517  * @param local_pref    The local preference for this candidate 
    518  *                      (typically the value is 65535). 
    519  * @param addr          The candidate address. 
    520  * @param set_default   Set to non-zero to make this candidate the  
    521  *                      default candidate for this component. 
    522  * 
    523  * @return              PJ_SUCCESS, or the appropriate error code. 
    524  */ 
    525 PJ_DECL(pj_status_t) pj_ice_strans_add_cand(pj_ice_strans *ice_st, 
    526                                             unsigned comp_id, 
    527                                             pj_ice_cand_type type, 
    528                                             pj_uint16_t local_pref, 
    529                                             const pj_sockaddr_in *addr, 
    530                                             pj_bool_t set_default); 
    531  
    532 /** 
    533  * Get the status of components in the ICE stream transports. Since 
    534  * some IP address candidates have to be obtained asynchronously (for 
    535  * example, the STUN reflexive or relay candidate), application can 
    536  * use this function to know whether the address resolution has  
    537  * completed. 
    538  * 
    539  * @param ice_st        The ICE stream transport. 
    540  * 
    541  * @return              PJ_SUCCESS if all candidates have been resolved 
    542  *                      successfully, PJ_EPENDING if transport resolution 
    543  *                      is still in progress, or other status on failure. 
    544  */ 
    545 PJ_DECL(pj_status_t) pj_ice_strans_get_comps_status(pj_ice_strans *ice_st); 
     320 * Get the user data associated with the ICE stream transport. 
     321 * 
     322 * @param ice_st        The ICE stream transport. 
     323 * 
     324 * @return              The user data. 
     325 */ 
     326PJ_DECL(void*) pj_ice_strans_get_user_data(pj_ice_strans *ice_st); 
     327 
    546328 
    547329/** 
    548330 * Initialize the ICE session in the ICE stream transport. 
     331 * When application is about to send an offer containing ICE capability, 
     332 * or when it receives an offer containing ICE capability, it must 
     333 * call this function to initialize the internal ICE session. This would 
     334 * register all transport address aliases for each component to the ICE 
     335 * session as candidates. Then application can enumerate all local 
     336 * candidates by calling #pj_ice_strans_enum_cands(), and encode these 
     337 * candidates in the SDP to be sent to remote agent. 
    549338 * 
    550339 * @param ice_st        The ICE stream transport. 
    … …  
    561350 
    562351/** 
    563  * Enumerate the local candidates. This function can only be called 
    564  * after the ICE session has been created in the ICE stream transport. 
    565  * 
    566  * @param ice_st        The ICE stream transport. 
     352 * Enumerate the local candidates for the specified component. 
     353 * 
     354 * @param ice_st        The ICE stream transport. 
     355 * @param comp_id       Component ID. 
    567356 * @param count         On input, it specifies the maximum number of 
    568357 *                      elements. On output, it will be filled with 
    … …  
    574363 */ 
    575364PJ_DECL(pj_status_t) pj_ice_strans_enum_cands(pj_ice_strans *ice_st, 
     365                                              unsigned comp_id, 
    576366                                              unsigned *count, 
    577367                                              pj_ice_sess_cand cand[]); 
    578368 
    579369/** 
     370 * Get the default candidate for the specified component. When this 
     371 * function is called before ICE negotiation completes, the default 
     372 * candidate is selected according to local preference criteria. When 
     373 * this function is called after ICE negotiation completes, the 
     374 * default candidate is the candidate that forms the valid pair. 
     375 * 
     376 * @param ice_st        The ICE stream transport. 
     377 * @param comp_id       Component ID. 
     378 * @param cand          Pointer to receive the default candidate 
     379 *                      information. 
     380 */ 
     381PJ_DECL(pj_status_t) pj_ice_strans_get_def_cand(pj_ice_strans *ice_st, 
     382                                                unsigned comp_id, 
     383                                                pj_ice_sess_cand *cand); 
     384 
     385/** 
     386 * Get the current ICE role. ICE session must have been initialized 
     387 * before this function can be called. 
     388 * 
     389 * @param ice_st        The ICE stream transport. 
     390 * 
     391 * @return              Current ICE role. 
     392 */ 
     393PJ_DECL(pj_ice_sess_role) pj_ice_strans_get_role(pj_ice_strans *ice_st); 
     394 
     395 
     396/** 
     397 * Change session role. This happens for example when ICE session was 
     398 * created with controlled role when receiving an offer, but it turns out 
     399 * that the offer contains "a=ice-lite" attribute when the SDP gets 
     400 * inspected. ICE session must have been initialized before this function 
     401 * can be called. 
     402 * 
     403 * @param ice_st        The ICE stream transport. 
     404 * @param new_role      The new role to be set. 
     405 * 
     406 * @return              PJ_SUCCESS on success, or the appropriate error. 
     407 */ 
     408PJ_DECL(pj_status_t) pj_ice_strans_change_role(pj_ice_strans *ice_st, 
     409                                               pj_ice_sess_role new_role); 
     410 
     411 
     412/** 
    580413 * Start ICE connectivity checks. This function can only be called 
    581  * after the ICE session has been created in the ICE stream transport. 
    582  * 
    583  * This function will pair the local and remote candidates to create  
    584  * check list. Once the check list is created and sorted based on the 
    585  * priority, ICE periodic checks will be started. This function will  
    586  * return immediately, and application will be notified about the  
    587  * connectivity check status in the callback. 
     414 * after the ICE session has been created in the ICE stream transport 
     415 * with #pj_ice_strans_init_ice(). 
     416 * 
     417 * This function must be called once application has received remote 
     418 * candidate list (typically from the remote SDP). This function pairs 
     419 * local candidates with remote candidates, and starts ICE connectivity 
     420 * checks. The ICE session/transport will then notify the application  
     421 * via the callback when ICE connectivity checks completes, either  
     422 * successfully or with failure. 
    588423 * 
    589424 * @param ice_st        The ICE stream transport. 
    … …  
    592427 * @param rem_passwd    Remote password, as seen in the SDP received from 
    593428 *                      the remote agent. 
    594  * @param rem_cand_cnt  Number of remote candidates. 
    595  * @param rem_cand      Remote candidate array. 
     429 * @param rcand_cnt     Number of remote candidates in the array. 
     430 * @param rcand         Remote candidates array. 
    596431 * 
    597432 * @return              PJ_SUCCESS, or the appropriate error code. 
    598433 */ 
    599 PJ_DECL(pj_status_t)  
    600 pj_ice_strans_start_ice( pj_ice_strans *ice_st, 
    601                          const pj_str_t *rem_ufrag, 
    602                          const pj_str_t *rem_passwd, 
    603                          unsigned rem_cand_cnt, 
    604                          const pj_ice_sess_cand rem_cand[]); 
    605  
    606 /** 
    607  * Stop and destroy the ICE session inside this media transport. 
     434PJ_DECL(pj_status_t) pj_ice_strans_start_ice(pj_ice_strans *ice_st, 
     435                                             const pj_str_t *rem_ufrag, 
     436                                             const pj_str_t *rem_passwd, 
     437                                             unsigned rcand_cnt, 
     438                                             const pj_ice_sess_cand rcand[]); 
     439 
     440/** 
     441 * Retrieve the candidate pair that has been nominated and successfully 
     442 * checked for the specified component. If ICE negotiation is still in 
     443 * progress or it has failed, this function will return NULL. 
     444 * 
     445 * @param ice_st        The ICE stream transport. 
     446 * @param comp_id       Component ID. 
     447 * 
     448 * @return              The valid pair as ICE checklist structure if the 
     449 *                      pair exist. 
     450 */ 
     451PJ_DECL(const pj_ice_sess_check*)  
     452pj_ice_strans_get_valid_pair(const pj_ice_strans *ice_st, 
     453                             unsigned comp_id); 
     454 
     455/** 
     456 * Stop and destroy the ICE session inside this media transport. Application 
     457 * needs to call this function once the media session is over (the call has 
     458 * been disconnected). 
     459 * 
     460 * Application MAY reuse this ICE stream transport for subsequent calls. 
     461 * In this case, it must call #pj_ice_strans_stop_ice() when the call is 
     462 * disconnected, and reinitialize the ICE stream transport for subsequent 
     463 * call with #pj_ice_strans_init_ice()/#pj_ice_strans_start_ice(). In this 
     464 * case, the ICE stream transport will maintain the internal sockets and 
     465 * continue to send STUN keep-alive packets and TURN Refresh request to  
     466 * keep the NAT binding/TURN allocation open and to detect change in STUN 
     467 * mapped address. 
     468 * 
     469 * If application does not want to reuse the ICE stream transport for 
     470 * subsequent calls, it must call #pj_ice_strans_destroy() to destroy the 
     471 * ICE stream transport altogether. 
    608472 * 
    609473 * @param ice_st        The ICE stream transport. 
    … …  
    615479 
    616480/** 
    617  * Send outgoing packet using this transport. If ICE checks have not  
    618  * produced a valid check for the specified component ID, this function  
    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 
    621  * previously. 
     481 * Send outgoing packet using this transport.  
     482 * Application can send data (normally RTP or RTCP packets) at any time 
     483 * by calling this function. This function takes a destination 
     484 * address as one of the arguments, and this destination address should 
     485 * be taken from the default transport address of the component (that is 
     486 * the address in SDP c= and m= lines, or in a=rtcp attribute).  
     487 * If ICE negotiation is in progress, this function will send the data  
     488 * to the destination address. Otherwise if ICE negotiation has completed 
     489 * successfully, this function will send the data to the nominated remote  
     490 * address, as negotiated by ICE. 
    622491 * 
    623492 * @param ice_st        The ICE stream transport. 
Note: See TracChangeset for help on using the changeset viewer.