Home --> Documentations --> PJLIB-UTIL Reference
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.
- RFC 2782: A DNS RR for specifying the location of services (DNS SRV)
Opaque declaration for DNS SRV query
Type of callback function to receive notification from the resolver when the resolution process completes.
Flags to be specified when starting the DNS SRV query.
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.
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.
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.
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.
Cancel an outstanding DNS SRV query.
|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.|
- PJ_SUCCESS on success, or the appropriate error code,
Start DNS SRV resolution for the specified name. The full name of the entry will be concatenated from res_name and domain_name fragments.
|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.|
- 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.