mirror of
https://github.com/asterisk/asterisk.git
synced 2026-05-05 12:53:45 +00:00
37256ea45d
Review: https://reviewboard.asterisk.org/r/1891/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@369517 65c4cc65-6c06-0410-ace0-fbb531ad65f3
216 lines
7.4 KiB
C
216 lines
7.4 KiB
C
/* $Id$ */
|
|
/*
|
|
* 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__ */
|
|
|