DNS SRV Resolution Helper

Data Structures
struct	pj_dns_srv_record

Typedefs
typedef struct pj_dns_srv_async_query	pj_dns_srv_async_query
typedef void	pj_dns_srv_resolver_cb(void *user_data, pj_status_t status, const pj_dns_srv_record *rec)

Enumerations
enum	pj_dns_srv_option { PJ_DNS_SRV_FALLBACK_A = 1 , PJ_DNS_SRV_FALLBACK_AAAA = 2 , PJ_DNS_SRV_RESOLVE_AAAA = 4 , PJ_DNS_SRV_RESOLVE_AAAA_ONLY = 8 }

Functions
pj_status_t	pj_dns_srv_resolve (const pj_str_t *domain_name, const pj_str_t *res_name, unsigned def_port, pj_pool_t *pool, pj_dns_resolver *resolver, unsigned option, void *token, pj_dns_srv_resolver_cb *cb, pj_dns_srv_async_query **p_query)
pj_status_t	pj_dns_srv_cancel_query (pj_dns_srv_async_query *query, pj_bool_t notify)

Detailed Description

DNS SRV Resolution Helper

This module provides an even higher layer of abstraction for the DNS resolution framework, to resolve DNS SRV names.

The pj_dns_srv_resolve() function will asynchronously resolve the server name into IP address(es) with a single function call. If the SRV name contains multiple names, then each will be resolved with individual DNS A resolution to get the IP addresses. Upon successful completion, application callback will be called with each IP address of the target selected based on the load-balancing and fail-over criteria below.

When the resolver fails to resolve the name using DNS SRV resolution (for example when the DNS SRV record is not present in the DNS server), the resolver will fallback to using DNS A record resolution to resolve the name.

Load-Balancing and Fail-Over

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):

• targets will be sorted based on the priority first.
• for targets with the same priority, pj_dns_srv_resolve() will select only one target according to its weight. To select this one target, the function associates running-sum for all targets, and generates a random number between zero and the total running-sum (inclusive). The target selected is the first target with running-sum greater than or equal to this random number.

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 pj_dns_srv_record structure argument of the callback.

Reference

Reference:

• RFC 2782: A DNS RR for specifying the location of services (DNS SRV)

Typedef Documentation

pj_dns_srv_async_query

typedef struct pj_dns_srv_async_query pj_dns_srv_async_query

Opaque declaration for DNS SRV query

pj_dns_srv_resolver_cb

typedef void pj_dns_srv_resolver_cb(void *user_data, pj_status_t status, const pj_dns_srv_record *rec)

Type of callback function to receive notification from the resolver when the resolution process completes.

Enumeration Type Documentation

pj_dns_srv_option

enum pj_dns_srv_option

Flags to be specified when starting the DNS SRV query.

Enumerator
PJ_DNS_SRV_FALLBACK_A	Specify if the resolver should fallback with DNS A resolution when the SRV resolution fails. This option may be specified together with PJ_DNS_SRV_FALLBACK_AAAA to make the resolver fallback to both DNS A and DNS AAAA resolutions if SRV resolution fails.
PJ_DNS_SRV_FALLBACK_AAAA	Specify if the resolver should fallback with DNS AAAA resolution when the SRV resolution fails. This option may be specified together with PJ_DNS_SRV_FALLBACK_AAAA to make the resolver fallback to both DNS A and DNS AAAA resolutions if SRV resolution fails.
PJ_DNS_SRV_RESOLVE_AAAA	Specify if the resolver should try to resolve with DNS AAAA resolution of each targets in the DNS SRV record. If this option is not specified, the SRV resolver will query the DNS A record for the target instead.
PJ_DNS_SRV_RESOLVE_AAAA_ONLY	Specify if the resolver should try to resolve with DNS AAAA resolution only (i.e: without DNS A resolution) for each targets in the DNS SRV record.

Function Documentation

pj_dns_srv_cancel_query()

pj_status_t pj_dns_srv_cancel_query	(	pj_dns_srv_async_query *	query,
		pj_bool_t	notify
	)

Cancel an outstanding DNS SRV query.

Parameters

query	The pending asynchronous query to be cancelled.
notify	If non-zero, the callback will be called with failure status to notify that the query has been cancelled.

Returns

PJ_SUCCESS on success, or the appropriate error code,

References PJ_END_DECL.

pj_dns_srv_resolve()

pj_status_t pj_dns_srv_resolve	(	const pj_str_t *	domain_name,
		const pj_str_t *	res_name,
		unsigned	def_port,
		pj_pool_t *	pool,
		pj_dns_resolver *	resolver,
		unsigned	option,
		void *	token,
		pj_dns_srv_resolver_cb *	cb,
		pj_dns_srv_async_query **	p_query
	)

Start DNS SRV resolution for the specified name. The full name of the entry will be concatenated from res_name and domain_name fragments.

Parameters

domain_name	The domain name part of the name.
res_name	The full service name, including the transport name and with all the leading underscore characters and ending dot (e.g. "_sip._udp.", "_stun._udp.").
def_port	The port number to be assigned to the resolved address when the DNS SRV resolution fails and the name is resolved with DNS A resolution.
pool	Memory pool used to allocate memory for the query.
resolver	The resolver instance.
option	Option flags, which can be constructed from pj_dns_srv_option bitmask. Note that this argument was called "fallback_a" in pjsip version 0.8.0 and older, but the new option should be backward compatible with existing applications. If application specifies PJ_TRUE as "fallback_a" value, it will correspond to PJ_DNS_SRV_FALLBACK_A option.
token	Arbitrary data to be associated with this query when the calback is called.
cb	Pointer to callback function to receive the notification when the resolution process completes.
p_query	Optional pointer to receive the query object, if one was started. If this pointer is specified, a NULL may be returned if response cache is available immediately.

Returns

PJ_SUCCESS on success, or the appropriate error code.