/usr/include/pjlib-util/srv_resolver.h is in libpjproject-dev 2.1.0.0.ast20130823-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 | /* $Id: srv_resolver.h 3553 2011-05-05 06:14:19Z nanang $ */
/*
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef __PJLIB_UTIL_SRV_RESOLVER_H__
#define __PJLIB_UTIL_SRV_RESOLVER_H__
/**
* @file srv_resolver.h
* @brief DNS SRV resolver
*/
#include <pjlib-util/resolver.h>
PJ_BEGIN_DECL
/**
* @defgroup PJ_DNS_SRV_RESOLVER DNS SRV Resolution Helper
* @ingroup PJ_DNS
* @{
*
* \section PJ_DNS_SRV_RESOLVER_INTRO 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.
*
* \subsection PJ_DNS_SRV_RESOLVER_FAILOVER_LOADBALANCE 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.
*
* \section PJ_DNS_SRV_RESOLVER_REFERENCE Reference
*
* Reference:
* - <A HREF="http://www.ietf.org/rfc/rfc2782.txt">RFC 2782</A>:
* A DNS RR for specifying the location of services (DNS SRV)
*/
/**
* Flags to be specified when starting the DNS SRV query.
*/
typedef enum pj_dns_srv_option
{
/**
* 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_A = 1,
/**
* 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_FALLBACK_AAAA = 2,
/**
* 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.
*/
PJ_DNS_SRV_RESOLVE_AAAA = 4
} pj_dns_srv_option;
/**
* This structure represents DNS SRV records as the result of DNS SRV
* resolution using #pj_dns_srv_resolve().
*/
typedef struct pj_dns_srv_record
{
/** Number of address records. */
unsigned count;
/** Address records. */
struct
{
/** Server priority (the lower the higher the priority). */
unsigned priority;
/** Server weight (the higher the more load it can handle). */
unsigned weight;
/** Port number. */
pj_uint16_t port;
/** The host address. */
pj_dns_a_record server;
} entry[PJ_DNS_SRV_MAX_ADDR];
} pj_dns_srv_record;
/** Opaque declaration for DNS SRV query */
typedef struct pj_dns_srv_async_query pj_dns_srv_async_query;
/**
* Type of callback function to receive notification from the resolver
* when the resolution process completes.
*/
typedef void pj_dns_srv_resolver_cb(void *user_data,
pj_status_t status,
const pj_dns_srv_record *rec);
/**
* Start DNS SRV resolution for the specified name. The full name of the
* entry will be concatenated from \a res_name and \a domain_name fragments.
*
* @param domain_name The domain name part of the name.
* @param 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.").
* @param 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.
* @param pool Memory pool used to allocate memory for the query.
* @param resolver The resolver instance.
* @param 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.
* @param token Arbitrary data to be associated with this query when
* the calback is called.
* @param cb Pointer to callback function to receive the
* notification when the resolution process completes.
* @param 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.
*
* @return PJ_SUCCESS on success, or the appropriate error code.
*/
PJ_DECL(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);
/**
* Cancel an outstanding DNS SRV query.
*
* @param query The pending asynchronous query to be cancelled.
* @param notify If non-zero, the callback will be called with failure
* status to notify that the query has been cancelled.
*
* @return PJ_SUCCESS on success, or the appropriate error code,
*/
PJ_DECL(pj_status_t) pj_dns_srv_cancel_query(pj_dns_srv_async_query *query,
pj_bool_t notify);
/**
* @}
*/
PJ_END_DECL
#endif /* __PJLIB_UTIL_SRV_RESOLVER_H__ */
|