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

  1/*
  2 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
  3 * Copyright (C) 1999-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: dbtable.h,v 1.23 2007/06/19 23:47:16 tbox Exp $ */
 19
 20#ifndef DNS_DBTABLE_H
 21#define DNS_DBTABLE_H 1
 22
 23/*****
 24 ***** Module Info
 25 *****/
 26
 27/*! \file dns/dbtable.h
 28 * \brief
 29 * DNS DB Tables
 30 *
 31 * XXX TBS XXX
 32 *
 33 * MP:
 34 *\li	The module ensures appropriate synchronization of data structures it
 35 *	creates and manipulates.
 36 *
 37 * Reliability:
 38 *\li	No anticipated impact.
 39 *
 40 * Resources:
 41 *\li	None.
 42 *
 43 * Security:
 44 *\li	No anticipated impact.
 45 *
 46 * Standards:
 47 *\li	None.
 48 */
 49
 50#include <isc/lang.h>
 51
 52#include <dns/types.h>
 53
 54#define DNS_DBTABLEFIND_NOEXACT		0x01
 55
 56ISC_LANG_BEGINDECLS
 57
 58isc_result_t
 59dns_dbtable_create(isc_mem_t *mctx, dns_rdataclass_t rdclass,
 60		   dns_dbtable_t **dbtablep);
 61/*%<
 62 * Make a new dbtable of class 'rdclass'
 63 *
 64 * Requires:
 65 *\li	mctx != NULL
 66 * \li	dbtablep != NULL && *dptablep == NULL
 67 *\li	'rdclass' is a valid class
 68 *
 69 * Returns:
 70 *\li	#ISC_R_SUCCESS
 71 *\li	#ISC_R_NOMEMORY
 72 *\li	#ISC_R_UNEXPECTED
 73 */
 74
 75void
 76dns_dbtable_attach(dns_dbtable_t *source, dns_dbtable_t **targetp);
 77/*%<
 78 * Attach '*targetp' to 'source'.
 79 *
 80 * Requires:
 81 *
 82 *\li	'source' is a valid dbtable.
 83 *
 84 *\li	'targetp' points to a NULL dns_dbtable_t *.
 85 *
 86 * Ensures:
 87 *
 88 *\li	*targetp is attached to source.
 89 */
 90
 91void
 92dns_dbtable_detach(dns_dbtable_t **dbtablep);
 93/*%<
 94 * Detach *dbtablep from its dbtable.
 95 *
 96 * Requires:
 97 *
 98 *\li	'*dbtablep' points to a valid dbtable.
 99 *
100 * Ensures:
101 *
102 *\li	*dbtablep is NULL.
103 *
104 *\li	If '*dbtablep' is the last reference to the dbtable,
105 *		all resources used by the dbtable will be freed
106 */
107
108isc_result_t
109dns_dbtable_add(dns_dbtable_t *dbtable, dns_db_t *db);
110/*%<
111 * Add 'db' to 'dbtable'.
112 *
113 * Requires:
114 *\li	'dbtable' is a valid dbtable.
115 *
116 *\li	'db' is a valid database with the same class as 'dbtable'
117 */
118
119void
120dns_dbtable_remove(dns_dbtable_t *dbtable, dns_db_t *db);
121/*%<
122 * Remove 'db' from 'dbtable'.
123 *
124 * Requires:
125 *\li	'db' was previously added to 'dbtable'.
126 */
127
128void
129dns_dbtable_adddefault(dns_dbtable_t *dbtable, dns_db_t *db);
130/*%<
131 * Use 'db' as the result of a dns_dbtable_find() if no better match is
132 * available.
133 */
134
135void
136dns_dbtable_getdefault(dns_dbtable_t *dbtable, dns_db_t **db);
137/*%<
138 * Get the 'db' used as the result of a dns_dbtable_find()
139 * if no better match is available.
140 */
141
142void
143dns_dbtable_removedefault(dns_dbtable_t *dbtable);
144/*%<
145 * Remove the default db from 'dbtable'.
146 */
147
148isc_result_t
149dns_dbtable_find(dns_dbtable_t *dbtable, dns_name_t *name,
150		 unsigned int options, dns_db_t **dbp);
151/*%<
152 * Find the deepest match to 'name' in the dbtable, and return it
153 *
154 * Notes:
155 *\li	If the DNS_DBTABLEFIND_NOEXACT option is set, the best partial
156 *	match (if any) to 'name' will be returned.
157 *
158 * Returns:  
159 * \li #ISC_R_SUCCESS		on success
160 *\li	     something else:		no default and match
161 */
162
163ISC_LANG_ENDDECLS
164
165#endif /* DNS_DBTABLE_H */