diff options
author | Benny Prijono <bennylp@teluu.com> | 2009-08-12 11:03:23 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2009-08-12 11:03:23 +0000 |
commit | 8df6724ddca5de98cfdc21316fb5d7e5de95d726 (patch) | |
tree | e48368d28208f4454071f196f49f7cddf3b0e9ba /pjsip/include | |
parent | c4851558e0c60e8a8929473631b825e1945f239b (diff) |
Ticket #866: Allow application to specify more than one STUN servers for more robustness, and continue application startup if STUN resolution fails
PJSUA-LIB:
- New fields in pjsua_config to specify more than one STUN servers (the stun_srv_cnt and stun_srv array)
- The existing stun_host and stun_domain fields are deprecated, but backward compatibility is maintained. If stun_srv_cnt is zero, the library will import the entries from stun_host and stun_domain
- The library will now resolve the STUN server entries one by one and test it before using it
- New auxiliary API pjsua_resolve_stun_servers() to perform resolution and test against array of STUN servers
pjsua application:
- The "stun-srv" command line options can now be specified more than once
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@2864 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjsip/include')
-rw-r--r-- | pjsip/include/pjsua-lib/pjsua.h | 133 | ||||
-rw-r--r-- | pjsip/include/pjsua-lib/pjsua_internal.h | 28 |
2 files changed, 156 insertions, 5 deletions
diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h index 43db66ea..cd86a524 100644 --- a/pjsip/include/pjsua-lib/pjsua.h +++ b/pjsip/include/pjsua-lib/pjsua.h @@ -891,6 +891,10 @@ typedef struct pjsua_config pj_str_t outbound_proxy[4]; /** + * Warning: deprecated, please use \a stun_srv field instead. To maintain + * backward compatibility, if \a stun_srv_cnt is zero then the value of + * this field will be copied to \a stun_srv field, if present. + * * Specify domain name to be resolved with DNS SRV resolution to get the * address of the STUN server. Alternatively application may specify * \a stun_host instead. @@ -901,12 +905,52 @@ typedef struct pjsua_config pj_str_t stun_domain; /** + * Warning: deprecated, please use \a stun_srv field instead. To maintain + * backward compatibility, if \a stun_srv_cnt is zero then the value of + * this field will be copied to \a stun_srv field, if present. + * * Specify STUN server to be used, in "HOST[:PORT]" format. If port is * not specified, default port 3478 will be used. */ pj_str_t stun_host; /** + * Number of STUN server entries in \a stun_srv array. + */ + unsigned stun_srv_cnt; + + /** + * Array of STUN servers to try. The library will try to resolve and + * contact each of the STUN server entry until it finds one that is + * usable. Each entry may be a domain name, host name, IP address, and + * it may contain an optional port number. For example: + * - "pjsip.org" (domain name) + * - "sip.pjsip.org" (host name) + * - "pjsip.org:33478" (domain name and a non-standard port number) + * - "10.0.0.1:3478" (IP address and port number) + * + * When nameserver is configured in the \a pjsua_config.nameserver field, + * if entry is not an IP address, it will be resolved with DNS SRV + * resolution first, and it will fallback to use DNS A resolution if this + * fails. Port number may be specified even if the entry is a domain name, + * in case the DNS SRV resolution should fallback to a non-standard port. + * + * When nameserver is not configured, entries will be resolved with + * #pj_gethostbyname() if it's not an IP address. Port number may be + * specified if the server is not listening in standard STUN port. + */ + pj_str_t stun_srv[8]; + + /** + * This specifies if the library startup should ignore failure with the + * STUN servers. If this is set to PJ_FALSE, the library will refuse to + * start if it fails to resolve or contact any of the STUN servers. + * + * Default: PJ_TRUE + */ + pj_bool_t stun_ignore_failure; + + /** * Support for adding and parsing NAT type in the SDP to assist * troubleshooting. The valid values are: * - 0: no information will be added in SDP, and parsing is disabled. @@ -1215,6 +1259,46 @@ PJ_DECL(pj_pool_factory*) pjsua_get_pool_factory(void); */ /** + * This structure is used to represent the result of the STUN server + * resolution and testing, the #pjsua_resolve_stun_servers() function. + * This structure will be passed in #pj_stun_resolve_cb callback. + */ +typedef struct pj_stun_resolve_result +{ + /** + * Arbitrary data that was passed to #pjsua_resolve_stun_servers() + * function. + */ + void *token; + + /** + * This will contain PJ_SUCCESS if at least one usable STUN server + * is found, otherwise it will contain the last error code during + * the operation. + */ + pj_status_t status; + + /** + * The server name that yields successful result. This will only + * contain value if status is successful. + */ + pj_str_t name; + + /** + * The server IP address. This will only contain value if status + * is successful. + */ + pj_sockaddr addr; + +} pj_stun_resolve_result; + + +/** + * Typedef of callback to be registered to #pjsua_resolve_stun_servers(). + */ +typedef void (*pj_stun_resolve_cb)(const pj_stun_resolve_result *result); + +/** * This is a utility function to detect NAT type in front of this * endpoint. Once invoked successfully, this function will complete * asynchronously and report the result in \a on_nat_detect() callback @@ -1253,6 +1337,55 @@ PJ_DECL(pj_status_t) pjsua_get_nat_type(pj_stun_nat_type *type); /** + * Auxiliary function to resolve and contact each of the STUN server + * entries (sequentially) to find which is usable. The #pjsua_init() must + * have been called before calling this function. + * + * @param count Number of STUN server entries to try. + * @param srv Array of STUN server entries to try. Please see + * the \a stun_srv field in the #pjsua_config + * documentation about the format of this entry. + * @param wait Specify non-zero to make the function block until + * it gets the result. In this case, the function + * will block while the resolution is being done, + * and the callback will be called before this function + * returns. + * @param token Arbitrary token to be passed back to application + * in the callback. + * @param cb Callback to be called to notify the result of + * the function. + * + * @return If \a wait parameter is non-zero, this will return + * PJ_SUCCESS if one usable STUN server is found. + * Otherwise it will always return PJ_SUCCESS, and + * application will be notified about the result in + * the callback. + */ +PJ_DECL(pj_status_t) pjsua_resolve_stun_servers(unsigned count, + pj_str_t srv[], + pj_bool_t wait, + void *token, + pj_stun_resolve_cb cb); + +/** + * Cancel pending STUN resolution which match the specified token. + * + * @param token The token to match. This token was given to + * #pjsua_resolve_stun_servers() + * @param notify_cb Boolean to control whether the callback should + * be called for cancelled resolutions. When the + * callback is called, the status in the result + * will be set as PJ_ECANCELLED. + * + * @return PJ_SUCCESS if there is at least one pending STUN + * resolution cancelled, or PJ_ENOTFOUND if there is + * no matching one, or other error. + */ +PJ_DECL(pj_status_t) pjsua_cancel_stun_resolution(void *token, + pj_bool_t notify_cb); + + +/** * This is a utility function to verify that valid SIP url is given. If the * URL is valid, PJ_SUCCESS will be returned. * diff --git a/pjsip/include/pjsua-lib/pjsua_internal.h b/pjsip/include/pjsua-lib/pjsua_internal.h index d80f5d1d..03c6627c 100644 --- a/pjsip/include/pjsua-lib/pjsua_internal.h +++ b/pjsip/include/pjsua-lib/pjsua_internal.h @@ -212,6 +212,22 @@ typedef struct pjsua_conf_setting unsigned bits_per_sample; } pjsua_conf_setting; +typedef struct pjsua_stun_resolve +{ + PJ_DECL_LIST_MEMBER(struct pjsua_stun_resolve); + + pj_pool_t *pool; /**< Pool */ + unsigned count; /**< # of entries */ + pj_str_t *srv; /**< Array of entries */ + unsigned idx; /**< Current index */ + void *token; /**< App token */ + pj_stun_resolve_cb cb; /**< App callback */ + pj_bool_t blocking; /**< Blocking? */ + pj_status_t status; /**< Session status */ + pj_sockaddr addr; /**< Result */ + pj_stun_sock *stun_sock; /**< Testing STUN sock */ +} pjsua_stun_resolve; + /** * Global pjsua application data. @@ -241,6 +257,7 @@ struct pjsua_data pj_stun_config stun_cfg; /**< Global STUN settings. */ pj_sockaddr stun_srv; /**< Resolved STUN server address */ pj_status_t stun_status; /**< STUN server status. */ + pjsua_stun_resolve stun_res; /**< List of pending STUN resolution*/ pj_dns_resolver *resolver; /**< DNS resolver. */ /* Detected NAT type */ @@ -350,6 +367,12 @@ PJ_INLINE(pjsua_im_data*) pjsua_im_data_dup(pj_pool_t *pool, #define PJSUA_UNLOCK() #endif +/****** + * STUN resolution + */ +/* Resolve the STUN server */ +pj_status_t resolve_stun_server(pj_bool_t wait); + /** * Normalize route URI (check for ";lr" and append one if it doesn't * exist and pjsua_config.force_lr is set. @@ -357,11 +380,6 @@ PJ_INLINE(pjsua_im_data*) pjsua_im_data_dup(pj_pool_t *pool, pj_status_t normalize_route_uri(pj_pool_t *pool, pj_str_t *uri); /** - * Resolve STUN server. - */ -pj_status_t pjsua_resolve_stun_server(pj_bool_t wait); - -/** * Handle incoming invite request. */ pj_bool_t pjsua_call_on_incoming(pjsip_rx_data *rdata); |