contrib/bind-9.5.2/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
  56 ISC_LANG_BEGINDECLS
  57
  58 isc_result_t
  59 dns_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
  75 void
  76 dns_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
  91 void
  92 dns_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
 108 isc_result_t
 109 dns_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
 119 void
 120 dns_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
 128 void
 129 dns_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
 135 void
 136 dns_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
 142 void
 143 dns_dbtable_removedefault(dns_dbtable_t *dbtable);
 144 /*%<
 145  * Remove the default db from 'dbtable'.
 146  */
 147
 148 isc_result_t
 149 dns_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
 163 ISC_LANG_ENDDECLS
 164
 165 #endif /* DNS_DBTABLE_H */