/contrib/bind9/lib/dns/include/dns/forward.h

  1/*
  2 * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
  3 * Copyright (C) 2000, 2001  Internet Software Consortium.
  4 *
  5 * Permission to use, copy, modify, and/or distribute this software for any
  6 * purpose with or without fee is hereby granted, provided that the above
  7 * copyright notice and this permission notice appear in all copies.
  8 *
  9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 11 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 15 * PERFORMANCE OF THIS SOFTWARE.
 16 */
 17
 18/* $Id: forward.h,v 1.13 2009/09/02 23:48:02 tbox Exp $ */
 19
 20#ifndef DNS_FORWARD_H
 21#define DNS_FORWARD_H 1
 22
 23/*! \file dns/forward.h */
 24
 25#include <isc/lang.h>
 26#include <isc/result.h>
 27
 28#include <dns/types.h>
 29
 30ISC_LANG_BEGINDECLS
 31
 32struct dns_forwarders {
 33	isc_sockaddrlist_t	addrs;
 34	dns_fwdpolicy_t		fwdpolicy;
 35};
 36
 37isc_result_t
 38dns_fwdtable_create(isc_mem_t *mctx, dns_fwdtable_t **fwdtablep);
 39/*%<
 40 * Creates a new forwarding table.
 41 *
 42 * Requires:
 43 * \li 	mctx is a valid memory context.
 44 * \li	fwdtablep != NULL && *fwdtablep == NULL
 45 *
 46 * Returns:
 47 * \li	#ISC_R_SUCCESS
 48 * \li	#ISC_R_NOMEMORY
 49 */
 50
 51isc_result_t
 52dns_fwdtable_add(dns_fwdtable_t *fwdtable, dns_name_t *name,
 53		 isc_sockaddrlist_t *addrs, dns_fwdpolicy_t policy);
 54/*%<
 55 * Adds an entry to the forwarding table.  The entry associates
 56 * a domain with a list of forwarders and a forwarding policy.  The
 57 * addrs list is copied if not empty, so the caller should free its copy.
 58 *
 59 * Requires:
 60 * \li	fwdtable is a valid forwarding table.
 61 * \li	name is a valid name
 62 * \li	addrs is a valid list of sockaddrs, which may be empty.
 63 *
 64 * Returns:
 65 * \li	#ISC_R_SUCCESS
 66 * \li	#ISC_R_NOMEMORY
 67 */
 68
 69isc_result_t
 70dns_fwdtable_delete(dns_fwdtable_t *fwdtable, dns_name_t *name);
 71/*%<
 72 * Removes an entry for 'name' from the forwarding table.  If an entry
 73 * that exactly matches 'name' does not exist, ISC_R_NOTFOUND will be returned.
 74 *
 75 * Requires:
 76 * \li	fwdtable is a valid forwarding table.
 77 * \li	name is a valid name
 78 *
 79 * Returns:
 80 * \li	#ISC_R_SUCCESS
 81 * \li	#ISC_R_NOTFOUND
 82 */
 83
 84isc_result_t
 85dns_fwdtable_find(dns_fwdtable_t *fwdtable, dns_name_t *name,
 86		  dns_forwarders_t **forwardersp);
 87/*%<
 88 * Finds a domain in the forwarding table.  The closest matching parent
 89 * domain is returned.
 90 *
 91 * Requires:
 92 * \li	fwdtable is a valid forwarding table.
 93 * \li	name is a valid name
 94 * \li	forwardersp != NULL && *forwardersp == NULL
 95 *
 96 * Returns:
 97 * \li	#ISC_R_SUCCESS
 98 * \li	#ISC_R_NOTFOUND
 99 */
100
101isc_result_t
102dns_fwdtable_find2(dns_fwdtable_t *fwdtable, dns_name_t *name,
103		   dns_name_t *foundname, dns_forwarders_t **forwardersp);
104/*%<
105 * Finds a domain in the forwarding table.  The closest matching parent
106 * domain is returned.
107 *
108 * Requires:
109 * \li	fwdtable is a valid forwarding table.
110 * \li	name is a valid name
111 * \li	forwardersp != NULL && *forwardersp == NULL
112 * \li	foundname to be NULL or a valid name with buffer.
113 *
114 * Returns:
115 * \li	#ISC_R_SUCCESS
116 * \li	#ISC_R_NOTFOUND
117 */
118
119void
120dns_fwdtable_destroy(dns_fwdtable_t **fwdtablep);
121/*%<
122 * Destroys a forwarding table.
123 *
124 * Requires:
125 * \li	fwtablep != NULL && *fwtablep != NULL
126 *
127 * Ensures:
128 * \li	all memory associated with the forwarding table is freed.
129 */
130
131ISC_LANG_ENDDECLS
132
133#endif /* DNS_FORWARD_H */