Home --> Documentations --> PJSIP Reference
Framework to resolve SIP servers based on RFC 3263. More...
|typedef void||pjsip_resolver_callback (pj_status_t status, void *token, const struct pjsip_server_addresses *addr)|
|pj_status_t||pjsip_resolver_create (pj_pool_t *pool, pjsip_resolver_t **p_res)|
|pj_status_t||pjsip_resolver_set_resolver (pjsip_resolver_t *res, pj_dns_resolver *dns_res)|
|pj_status_t||pjsip_resolver_set_ext_resolver (pjsip_resolver_t *res, pjsip_ext_resolver *ext_res)|
|pj_dns_resolver *||pjsip_resolver_get_resolver (pjsip_resolver_t *res)|
|void||pjsip_resolver_destroy (pjsip_resolver_t *resolver)|
|void||pjsip_resolve (pjsip_resolver_t *resolver, pj_pool_t *pool, const pjsip_host_info *target, void *token, pjsip_resolver_callback *cb)|
This is the SIP server resolution framework, which is modelled after RFC 3263 - Locating SIP Servers document. The SIP server resolution framework is asynchronous; callback will be called once the server address has been resolved (successfully or with errors).
The SIP server resolution framework is modelled after RFC 3263 (Locating SIP Servers) document, and it provides a single function (pjsip_resolve()) to resolve a domain into actual IP addresses of the servers, by querying DNS SRV record and DNS A record where necessary.
The pjsip_resolve() function performs the server resolution according to RFC 3263 with some additional fallback mechanisms, as follows:
The above server resolution procedure differs from RFC 3263 in these regards:
When multiple targets are returned in the DNS SRV response, server entries are selected based on the following rule (which is described in RFC 2782):
The above procedure will select one target for each priority, allowing application to fail-over to the next target when the previous target fails. These targets are returned in the pjsip_server_addresses structure argument of the callback.
Some features of the SIP resolver:
The PJSIP server resolution framework uses PJLIB-UTIL DNS resolver engine for performing the asynchronous DNS request. The PJLIB-UTIL DNS resolver has some useful features, such as:
Please consult PJLIB-UTIL DNS resolver documentation for more details.
To maintain backward compatibility, the resolver MUST be enabled manually. With the default settings, the resolver WILL NOT perform DNS SRV resolution, as it will just resolve the name with standard pj_gethostbyname() function.
Application can enable the SRV resolver by creating the PJLIB-UTIL DNS resolver with pjsip_endpt_create_resolver(), configure the nameservers of the PJLIB-UTIL DNS resolver object by calling pj_dns_resolver_set_ns() function, and pass the DNS resolver object to pjsip_resolver_set_resolver() function.
Once the resolver is set, it will be used automatically by PJSIP everytime PJSIP needs to send SIP request/response messages.
As an alternative to enabling PJLIB-UTIL DNS resolver, application can provide its own resolver implementation by defining the callback in pjsip_ext_resolver and pass the callback to pjsip_resolver_set_ext_resolver() function. Please note that if the implementation needs feature from PJLIB-UTL DNS resolver, it has to create its own PJLIB-UTL DNS resolver instance.
|typedef void pjsip_resolver_callback(pj_status_t status, void *token, const struct pjsip_server_addresses *addr)|
The type of callback function to be called when resolver finishes the job.
|status||The status of the operation, which is zero on success.|
|token||The token that was associated with the job when application call the resolve function.|
|addr||The addresses resolved by the operation.|
Create SIP resolver engine. Note that this function is normally called internally by pjsip_endpoint instance.
|pool||Pool to allocate memory from.|
|p_res||Pointer to receive SIP resolver instance.|
Set the DNS resolver instance of the SIP resolver engine. Before the DNS resolver is set, the SIP resolver will use standard pj_gethostbyname() to resolve addresses.
Note that application normally will use pjsip_endpt_set_resolver() instead since it does not normally have access to the SIP resolver instance.
|res||The SIP resolver engine.|
|dns_res||The DNS resolver instance to be used by the SIP resolver. This argument can be NULL to reset the internal DNS instance.|
|pj_status_t pjsip_resolver_set_ext_resolver||(||pjsip_resolver_t *||res,|
Set the DNS external resolver implementation to use in the SIP resolver engine. Naturally when implementing its own resolver, application would not need the internal resolver, hence this function will also destroy the PJLIB-UTIL DNS resolver if any (e.g: set using pjsip_resolver_set_resolver()). Application that needs it, still be able create its own instance.
Note that application normally will use pjsip_endpt_set_ext_resolver() instead since it does not normally have access to the SIP resolver instance.
|res||The SIP resolver engine.|
|ext_res||The external resolver implementation callback. This argument can be NULL to reset the whole external implementation. However, it is prohibited to reset individual callback.|
Get the DNS resolver instance of the SIP resolver engine.
Note that application normally will use pjsip_endpt_get_resolver() instead since it does not normally have access to the SIP resolver instance.
|res||The SIP resolver engine.|
|void pjsip_resolver_destroy||(||pjsip_resolver_t *||resolver||)|
Destroy resolver engine. Note that this will also destroy the internal DNS resolver inside the engine. If application doesn't want the internal DNS resolver to be destroyed, it should set the internal DNS resolver to NULL before calling this function.
Note that this function will normally called by the SIP endpoint instance when the SIP endpoint instance is destroyed.
|void pjsip_resolve||(||pjsip_resolver_t *||resolver,|
|const pjsip_host_info *||target,|
Asynchronously resolve a SIP target host or domain according to rule specified in RFC 3263 (Locating SIP Servers). When the resolving operation has completed, the callback will be called.
Note that application normally will use pjsip_endpt_resolve() instead since it does not normally have access to the SIP resolver instance.
|resolver||The resolver engine.|
|pool||The pool to allocate resolver job.|
|target||The target specification to be resolved.|
|token||A user defined token to be passed back to callback function.|
|cb||The callback function.|