Changes between Version 8 and Version 9 of Ticket #1412


Ignore:
Timestamp:
Aug 7, 2012 1:07:33 AM (12 years ago)
Author:
bennylp
Comment:

Legend:

Unmodified
Added
Removed
Modified

  • Ticket #1412 – Description

    v8 v9  
    33== New STUN setting arrangements == 
    44 
    5 The STUN server settings are still in the global {{{pjsua_config}}}. New settings are introduced in the account config to disable or enable STUN for either SIP or media transports: '''{{{sip_stun_use}}}''' and '''{{{media_stun_use}}}'''.  
    6  
    7  Rationale: :: 
    8   This simple arrangement is chosen over providing full STUN server settings in the account config, i.e. having the list of servers in the account config as well as in the global config. There are several difficulties with the complex approach: 
    9       - The STUN servers in the account will need to be rechecked, and this most likely will need to block the {{{pjsua_acc_add()}}}. 
    10       - We need the STUN server when creating SIP UDP transport. Which STUN server to use? We definitely cannot use account's STUN server(s), because account is created later! Hence we need to provide yet another list of STUN servers in the transport config, and possibly need to recheck them too. 
     5The STUN server settings are still in the global {{{pjsua_config}}}. New settings are introduced in the account config to disable or enable STUN for either SIP or media transports: '''{{{sip_stun_use}}}''' and '''{{{media_stun_use}}}''': 
     6 
     7 {{{ 
     8/** 
     9 * This enumeration controls the use of STUN in the account. 
     10 */ 
     11typedef enum pjsua_stun_use 
     12{ 
     13    /** 
     14     * Follow the default setting in the global \a pjsua_config. 
     15     */ 
     16    PJSUA_STUN_USE_DEFAULT, 
     17 
     18    /** 
     19     * Disable STUN. If STUN is not enabled in the global \a pjsua_config, 
     20     * this setting has no effect. 
     21     */ 
     22    PJSUA_STUN_USE_DISABLED 
     23 
     24} pjsua_stun_use; 
     25 
     26struct pjsua_acc_config 
     27{ 
     28    ... 
     29 
     30    /** 
     31     * Control the use of STUN for the SIP signaling. 
     32     * 
     33     * Default: PJSUA_STUN_USE_DEFAULT 
     34     */ 
     35    pjsua_stun_use              sip_stun_use; 
     36 
     37    /** 
     38     * Control the use of STUN for the media transports. 
     39     * 
     40     * Default: PJSUA_STUN_USE_DEFAULT 
     41     */ 
     42    pjsua_stun_use              media_stun_use; 
     43 
     44    ... 
     45}; 
     46 }}} 
    1147 
    1248== ICE and TURN settings per account == 
    1349 
    14 ICE and TURN configurations will be added to account config with the default values values taken from the global media config. Media transport creation will look for the value in account config. 
     50New ICE and TURN configurations in the account config to override the global config in the {{{pjsua_media_config}}}: 
     51 
     52 {{{ 
     53/** 
     54 * This enumeration controls the use of ICE settings in the account. 
     55 */ 
     56typedef enum pjsua_ice_config_use 
     57{ 
     58    /** 
     59     * Use the default settings in the global \a pjsua_media_config. 
     60     */ 
     61    PJSUA_ICE_CONFIG_USE_DEFAULT, 
     62 
     63    /** 
     64     * Use the custom \a pjsua_ice_config setting in the account. 
     65     */ 
     66    PJSUA_ICE_CONFIG_USE_CUSTOM 
     67 
     68} pjsua_ice_config_use; 
     69 
     70/** 
     71 * This enumeration controls the use of TURN settings in the account. 
     72 */ 
     73typedef enum pjsua_turn_config_use 
     74{ 
     75    /** 
     76     * Use the default setting in the global \a pjsua_media_config. 
     77     */ 
     78    PJSUA_TURN_CONFIG_USE_DEFAULT, 
     79 
     80    /** 
     81     * Use the custom \a pjsua_turn_config setting in the account. 
     82     */ 
     83    PJSUA_TURN_CONFIG_USE_CUSTOM 
     84 
     85} pjsua_turn_config_use; 
     86 
     87/** 
     88 * ICE setting. This setting is used in the pjsua_acc_config. 
     89 */ 
     90typedef struct pjsua_ice_config 
     91{ 
     92    /** 
     93     * Enable ICE. 
     94     */ 
     95    pj_bool_t           enable_ice; 
     96 
     97    /** 
     98     * Set the maximum number of host candidates. 
     99     * 
     100     * Default: -1 (maximum not set) 
     101     */ 
     102    int                 ice_max_host_cands; 
     103 
     104    /** 
     105     * ICE session options. 
     106     */ 
     107    pj_ice_sess_options ice_opt; 
     108 
     109    /** 
     110     * Disable RTCP component. 
     111     * 
     112     * Default: no 
     113     */ 
     114    pj_bool_t           ice_no_rtcp; 
     115 
     116} pjsua_ice_config; 
     117 
     118/** 
     119 * TURN setting. This setting is used in the pjsua_acc_config. 
     120 */ 
     121typedef struct pjsua_turn_config 
     122{ 
     123    /** 
     124     * Enable TURN candidate in ICE. 
     125     */ 
     126    pj_bool_t           enable_turn; 
     127 
     128    /** 
     129     * Specify TURN domain name or host name, in in "DOMAIN:PORT" or 
     130     * "HOST:PORT" format. 
     131     */ 
     132    pj_str_t            turn_server; 
     133 
     134    /** 
     135     * Specify the connection type to be used to the TURN server. Valid 
     136     * values are PJ_TURN_TP_UDP or PJ_TURN_TP_TCP. 
     137     * 
     138     * Default: PJ_TURN_TP_UDP 
     139     */ 
     140    pj_turn_tp_type     turn_conn_type; 
     141 
     142    /** 
     143     * Specify the credential to authenticate with the TURN server. 
     144     */ 
     145    pj_stun_auth_cred   turn_auth_cred; 
     146 
     147} pjsua_turn_config; 
     148 
     149struct pjsua_acc_config 
     150{ 
     151    ... 
     152 
     153    /** 
     154     * Control the use of ICE in the account. By default, the settings in the 
     155     * \a pjsua_media_config will be used. 
     156     * 
     157     * Default: PJSUA_ICE_CONFIG_USE_DEFAULT 
     158     */ 
     159    pjsua_ice_config_use        ice_cfg_use; 
     160 
     161    /** 
     162     * The custom ICE setting for this account. This setting will only be 
     163     * used if \a ice_cfg_use is set to PJSUA_ICE_CONFIG_USE_CUSTOM 
     164     */ 
     165    pjsua_ice_config            ice_cfg; 
     166 
     167    /** 
     168     * Control the use of TURN in the account. By default, the settings in the 
     169     * \a pjsua_media_config will be used 
     170     * 
     171     * Default: PJSUA_TURN_CONFIG_USE_DEFAULT 
     172     */ 
     173    pjsua_turn_config_use       turn_cfg_use; 
     174 
     175    /** 
     176     * The custom TURN setting for this account. This setting will only be 
     177     * used if \a turn_cfg_use is set to PJSUA_TURN_CONFIG_USE_CUSTOM 
     178     */ 
     179    pjsua_turn_config           turn_cfg; 
     180 
     181    ... 
     182}; 
     183 
     184 }}} 
    15185 
    16186== Contact header generation == 
    17187 
    18 The initial value of Contact header will take into account whether STUN is enabled or disabled in the account. If it is disabled, local IP will be used. 
     188The initial value of Contact header will take into account whether STUN is enabled or disabled in the account. If it is disabled, local IP will be used. More over, for UDP transport, if STUN is not used or disabled for the account, an attempt will be made to use the correct IP interface to be placed in the Contact URI. 
     189 
     190No change for TCP; the correct IP has already been selected in the Contact URI. 
    19191 
    20192Subsequent update to the Contact header doesn't change. 
    21193 
     194 
    22195== Via sent-by generation == 
    23196 
    24 '''Initial''' Via {{{sent-by}}} value now will be affected by STUN setting. Subsequent update of the value doesn't change; it follows the rules in #1537. 
    25  
    26 For UDP, when STUN is disabled, the Via {{{sent-by}}} value would also use the '''correct''' interface on which the request will be sent, except if the destination is a host name which in this case the default interface will be used. 
     197'''Initial''' Via {{{sent-by}}} value now will be affected by STUN setting in the account. If it is disabled, local IP will be used. More over, for UDP transport, if STUN is not used or disabled for the account, an attempt will be made to use the correct IP interface to be placed in the Contact URI. 
    27198 
    28199No change for TCP; the correct IP has already been displayed in the Via {{{sent-by}}}. 
    29200 
     201Subsequent update of the value doesn't change; it follows the rules in #1537. 
     202 
    30203== Media transports == 
    31204