Group PJ_DNS_SRV_RESOLVER

group PJ_DNS_SRV_RESOLVER

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)

Typedefs

typedef struct pj_dns_srv_async_query pj_dns_srv_async_query

Opaque declaration for DNS SRV query

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.

Enums

enum pj_dns_srv_option

Flags to be specified when starting the DNS SRV query.

Values:

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 AAAA if SRV resolution fails, and then to DNS A resolution if the AAAA resolution fails.

enumerator 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_A to make the resolver fallback to AAAA if SRV resolution fails, and then to DNS A resolution if the AAAA resolution fails.

enumerator PJ_DNS_SRV_RESOLVE_AAAA

Specify if the resolver should try to resolve with DNS AAAA resolution first 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.

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)

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.

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,

struct pj_dns_srv_record
#include <srv_resolver.h>

This structure represents DNS SRV records as the result of DNS SRV resolution using pj_dns_srv_resolve().