BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJLIB-UTIL Reference

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 }
 

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

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.

Enumeration Type Documentation

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

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.

Function Documentation

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
queryThe pending asynchronous query to be cancelled.
notifyIf 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,
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_nameThe domain name part of the name.
res_nameThe full service name, including the transport name and with all the leading underscore characters and ending dot (e.g. "_sip._udp.", "_stun._udp.").
def_portThe port number to be assigned to the resolved address when the DNS SRV resolution fails and the name is resolved with DNS A resolution.
poolMemory pool used to allocate memory for the query.
resolverThe resolver instance.
optionOption 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.
tokenArbitrary data to be associated with this query when the calback is called.
cbPointer to callback function to receive the notification when the resolution process completes.
p_queryOptional 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.

 


PJLIB-UTIL Open Source, small footprint, and portable asynchronous/caching DNS resolver, text scanner, STUN client, and XML library
Copyright (C) 2006-2009 Teluu Inc.