/usr/include/pjsip/sip_resolve.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 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 | /* $Id: sip_resolve.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 __PJSIP_SIP_RESOLVE_H__
#define __PJSIP_SIP_RESOLVE_H__
/**
* @file sip_resolve.h
* @brief
* This module contains the mechanism to resolve server address as specified by
* RFC 3263 - Locating SIP Servers
*/
#include <pjsip/sip_types.h>
#include <pjlib-util/resolver.h>
#include <pj/sock.h>
PJ_BEGIN_DECL
/**
* @defgroup PJSIP_RESOLVE SIP SRV Server Resolution (RFC 3263 - Locating SIP Servers)
* @ingroup PJSIP_TRANSPORT
* @brief Framework to resolve SIP servers based on RFC 3263.
* @{
* \section PJSIP_RESOLVE_FEATURES Features
*
* This is the SIP server resolution framework, which is modelled after
* RFC 3263 - Locating SIP Servers document. The SIP server resolution
* framework is asynchronous; callback will be called once the server
* address has been resolved (successfully or with errors).
*
* \subsection PJSIP_RESOLVE_CONFORMANT Conformance to RFC 3263
*
* The SIP server resolution framework is modelled after RFC 3263 (Locating
* SIP Servers) document, and it provides a single function (#pjsip_resolve())
* to resolve a domain into actual IP addresses of the servers, by querying
* DNS SRV record and DNS A record where necessary.
*
* The #pjsip_resolve() function performs the server resolution according
* to RFC 3263 with some additional fallback mechanisms, as follows:
* - if the target name is an IP address, the callback will be called
* immediately with the IP address. If port number was specified, this
* port number will be used, otherwise the default port number for the
* transport will be used (5060 for TCP/UDP, 5061 for TLS) if the transport
* is specified. If the transport is not specified, UDP with port number
* 5060 will be used.
* - if target name is not an IP address but it contains port number,
* then the target name is resolved with DNS A (or AAAA, when IPv6 is
* supported in the future) query, and the port is taken from the
* port number argument. The callback will be called once the DNS A
* resolution completes. If the DNS A resolution returns multiple IP
* addresses, these IP addresses will be returned to the caller.
* - if target name is not an IP address and port number is not specified,
* DNS SRV resolution will be performed for the specified name and
* transport type (or UDP when transport is not specified),
* then followed by DNS A (or AAAA, when IPv6 is supported)
* resolution for each target in the SRV record. If DNS SRV
* resolution returns error, DNS A (or AAAA) resolution will be
* performed for the original target (it is assumed that the target domain
* does not support SRV records). 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.
*
* The above server resolution procedure differs from RFC 3263 in these
* regards:
* - currently #pjsip_resolve() doesn't support DNS NAPTR record.
* - if transport is not specified, it is assumed to be UDP (the proper
* behavior is to query the NAPTR record, but we don't support this
* yet).
*
*
* \subsection PJSIP_SIP_RESOLVE_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, #pjsip_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 #pjsip_server_addresses structure
* argument of the callback.
*
* \subsection PJSIP_SIP_RESOLVE_SIP_FEATURES SIP SRV Resolver Features
*
* Some features of the SIP resolver:
* - DNS SRV entries are returned on sorted order based on priority
* to allow failover to the next appropriate server.
* - The procedure in RFC 2782 is used to select server with the same
* priority to load-balance the servers load.
* - A single function (#pjsip_resolve()) performs all server resolution
* works, from resolving the SRV records to getting the actual IP addresses
* of the servers with DNS A (or AAAA) resolution.
* - When multiple DNS SRV records are returned, parallel DNS A (or AAAA)
* queries will be issued simultaneously.
* - The PJLIB-UTIL DNS resolver provides additional functionality such as
* response caching, query aggregation, parallel nameservers, fallback
* nameserver, etc., which will be described below.
*
*
* \subsection PJSIP_RESOLVE_DNS_FEATURES DNS Resolver Features
*
* The PJSIP server resolution framework uses PJLIB-UTIL DNS resolver engine
* for performing the asynchronous DNS request. The PJLIB-UTIL DNS resolver
* has some useful features, such as:
* - queries are asynchronous with configurable timeout,
* - query aggregation to combine multiple pending queries to the same
* DNS target into a single DNS request (to save message round-trip and
* processing),
* - response caching with TTL negotiated between the minimum TTL found in
* the response and the maximum TTL allowed in the configuration,
* - multiple nameservers, with active nameserver is selected from nameserver
* which provides the best response time,
* - fallback nameserver, with periodic detection of which name servers are
* active or down.
* - etc.
*
* Please consult PJLIB-UTIL DNS resolver documentation for more details.
*
*
* \section PJSIP_RESOLVE_USING Using the Resolver
*
* To maintain backward compatibility, the resolver MUST be enabled manually.
* With the default settings, the resolver WILL NOT perform DNS SRV resolution,
* as it will just resolve the name with standard pj_gethostbyname() function.
*
* Application can enable the SRV resolver by creating the PJLIB-UTIL DNS
* resolver with #pjsip_endpt_create_resolver(), configure the
* nameservers of the PJLIB-UTIL DNS resolver object by calling
* pj_dns_resolver_set_ns() function, and pass the DNS resolver object to
* #pjsip_resolver_set_resolver() function.
*
* Once the resolver is set, it will be used automatically by PJSIP everytime
* PJSIP needs to send SIP request/response messages.
*
*
* \section PJSIP_RESOLVE_REFERENCE Reference
*
* Reference:
* - RFC 2782: A DNS RR for specifying the location of services (DNS SRV)
* - RFC 3263: Locating SIP Servers
*/
/**
* The server addresses returned by the resolver.
*/
typedef struct pjsip_server_addresses
{
/** Number of address records. */
unsigned count;
/** Address records. */
struct
{
/** Preferable transport to be used to contact this address. */
pjsip_transport_type_e type;
/** Server priority (the lower the higher the priority). */
unsigned priority;
/** Server weight (the higher the more load it can handle). */
unsigned weight;
/** The server's address. */
pj_sockaddr addr;
/** Address length. */
int addr_len;
} entry[PJSIP_MAX_RESOLVED_ADDRESSES];
} pjsip_server_addresses;
/**
* The type of callback function to be called when resolver finishes the job.
*
* @param status The status of the operation, which is zero on success.
* @param token The token that was associated with the job when application
* call the resolve function.
* @param addr The addresses resolved by the operation.
*/
typedef void pjsip_resolver_callback(pj_status_t status,
void *token,
const struct pjsip_server_addresses *addr);
/**
* Create SIP resolver engine. Note that this function is normally called
* internally by pjsip_endpoint instance.
*
* @param pool Pool to allocate memory from.
* @param p_res Pointer to receive SIP resolver instance.
*
* @return PJ_SUCCESS when resolver can be successfully created.
*/
PJ_DECL(pj_status_t) pjsip_resolver_create(pj_pool_t *pool,
pjsip_resolver_t **p_res);
/**
* Set the DNS resolver instance of the SIP resolver engine. Before the
* DNS resolver is set, the SIP resolver will use standard pj_gethostbyname()
* to resolve addresses.
*
* Note that application normally will use #pjsip_endpt_set_resolver() instead
* since it does not normally have access to the SIP resolver instance.
*
* @param res The SIP resolver engine.
* @param dns_res The DNS resolver instance to be used by the SIP resolver.
* This argument can be NULL to reset the internal DNS
* instance.
*
* @return PJ_SUCCESS on success, or the appropriate error code.
*/
PJ_DECL(pj_status_t) pjsip_resolver_set_resolver(pjsip_resolver_t *res,
pj_dns_resolver *dns_res);
/**
* Get the DNS resolver instance of the SIP resolver engine.
*
* Note that application normally will use #pjsip_endpt_get_resolver() instead
* since it does not normally have access to the SIP resolver instance.
*
* @param res The SIP resolver engine.
*
* @return The DNS resolver instance (may be NULL)
*/
PJ_DECL(pj_dns_resolver*) pjsip_resolver_get_resolver(pjsip_resolver_t *res);
/**
* Destroy resolver engine. Note that this will also destroy the internal
* DNS resolver inside the engine. If application doesn't want the internal
* DNS resolver to be destroyed, it should set the internal DNS resolver
* to NULL before calling this function.
*
* Note that this function will normally called by the SIP endpoint instance
* when the SIP endpoint instance is destroyed.
*
* @param resolver The resolver.
*/
PJ_DECL(void) pjsip_resolver_destroy(pjsip_resolver_t *resolver);
/**
* Asynchronously resolve a SIP target host or domain according to rule
* specified in RFC 3263 (Locating SIP Servers). When the resolving operation
* has completed, the callback will be called.
*
* Note that application normally will use #pjsip_endpt_resolve() instead
* since it does not normally have access to the SIP resolver instance.
*
* @param resolver The resolver engine.
* @param pool The pool to allocate resolver job.
* @param target The target specification to be resolved.
* @param token A user defined token to be passed back to callback function.
* @param cb The callback function.
*/
PJ_DECL(void) pjsip_resolve( pjsip_resolver_t *resolver,
pj_pool_t *pool,
const pjsip_host_info *target,
void *token,
pjsip_resolver_callback *cb);
/**
* @}
*/
PJ_END_DECL
#endif /* __PJSIP_SIP_RESOLVE_H__ */
|