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

   1 /*
   2  * Copyright (C) 2004-2007, 2011  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  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: zt.h,v 1.40 2011/09/02 23:46:32 tbox Exp $ */
  19
  20 #ifndef DNS_ZT_H
  21 #define DNS_ZT_H 1
  22
  23 /*! \file dns/zt.h */
  24
  25 #include <isc/lang.h>
  26
  27 #include <dns/types.h>
  28
  29 #define DNS_ZTFIND_NOEXACT              0x01
  30
  31 ISC_LANG_BEGINDECLS
  32
  33 typedef isc_result_t
  34 (*dns_zt_allloaded_t)(void *arg);
  35 /*%<
  36  * Method prototype: when all pending zone loads are complete,
  37  * the zone table can inform the caller via a callback function with
  38  * this signature.
  39  */
  40
  41 typedef isc_result_t
  42 (*dns_zt_zoneloaded_t)(dns_zt_t *zt, dns_zone_t *zone, isc_task_t *task);
  43 /*%<
  44  * Method prototype: when a zone finishes loading, the zt object
  45  * can be informed via a callback function with this signature.
  46  */
  47
  48 isc_result_t
  49 dns_zt_create(isc_mem_t *mctx, dns_rdataclass_t rdclass, dns_zt_t **zt);
  50 /*%<
  51  * Creates a new zone table.
  52  *
  53  * Requires:
  54  * \li  'mctx' to be initialized.
  55  *
  56  * Returns:
  57  * \li  #ISC_R_SUCCESS on success.
  58  * \li  #ISC_R_NOMEMORY
  59  */
  60
  61 isc_result_t
  62 dns_zt_mount(dns_zt_t *zt, dns_zone_t *zone);
  63 /*%<
  64  * Mounts the zone on the zone table.
  65  *
  66  * Requires:
  67  * \li  'zt' to be valid
  68  * \li  'zone' to be valid
  69  *
  70  * Returns:
  71  * \li  #ISC_R_SUCCESS
  72  * \li  #ISC_R_EXISTS
  73  * \li  #ISC_R_NOSPACE
  74  * \li  #ISC_R_NOMEMORY
  75  */
  76
  77 isc_result_t
  78 dns_zt_unmount(dns_zt_t *zt, dns_zone_t *zone);
  79 /*%<
  80  * Unmount the given zone from the table.
  81  *
  82  * Requires:
  83  *      'zt' to be valid
  84  * \li  'zone' to be valid
  85  *
  86  * Returns:
  87  * \li  #ISC_R_SUCCESS
  88  * \li  #ISC_R_NOTFOUND
  89  * \li  #ISC_R_NOMEMORY
  90  */
  91
  92 isc_result_t
  93 dns_zt_find(dns_zt_t *zt, dns_name_t *name, unsigned int options,
  94             dns_name_t *foundname, dns_zone_t **zone);
  95 /*%<
  96  * Find the best match for 'name' in 'zt'.  If foundname is non NULL
  97  * then the name of the zone found is returned.
  98  *
  99  * Notes:
 100  * \li  If the DNS_ZTFIND_NOEXACT is set, the best partial match (if any)
 101  *      to 'name' will be returned.
 102  *
 103  * Requires:
 104  * \li  'zt' to be valid
 105  * \li  'name' to be valid
 106  * \li  'foundname' to be initialized and associated with a fixedname or NULL
 107  * \li  'zone' to be non NULL and '*zone' to be NULL
 108  *
 109  * Returns:
 110  * \li  #ISC_R_SUCCESS
 111  * \li  #DNS_R_PARTIALMATCH
 112  * \li  #ISC_R_NOTFOUND
 113  * \li  #ISC_R_NOSPACE
 114  */
 115
 116 void
 117 dns_zt_detach(dns_zt_t **ztp);
 118 /*%<
 119  * Detach the given zonetable, if the reference count goes to zero the
 120  * zonetable will be freed.  In either case 'ztp' is set to NULL.
 121  *
 122  * Requires:
 123  * \li  '*ztp' to be valid
 124  */
 125
 126 void
 127 dns_zt_flushanddetach(dns_zt_t **ztp);
 128 /*%<
 129  * Detach the given zonetable, if the reference count goes to zero the
 130  * zonetable will be flushed and then freed.  In either case 'ztp' is
 131  * set to NULL.
 132  *
 133  * Requires:
 134  * \li  '*ztp' to be valid
 135  */
 136
 137 void
 138 dns_zt_attach(dns_zt_t *zt, dns_zt_t **ztp);
 139 /*%<
 140  * Attach 'zt' to '*ztp'.
 141  *
 142  * Requires:
 143  * \li  'zt' to be valid
 144  * \li  '*ztp' to be NULL
 145  */
 146
 147 isc_result_t
 148 dns_zt_load(dns_zt_t *zt, isc_boolean_t stop);
 149
 150 isc_result_t
 151 dns_zt_loadnew(dns_zt_t *zt, isc_boolean_t stop);
 152
 153 isc_result_t
 154 dns_zt_asyncload(dns_zt_t *zt, dns_zt_allloaded_t alldone, void *arg);
 155 /*%<
 156  * Load all zones in the table.  If 'stop' is ISC_TRUE,
 157  * stop on the first error and return it.  If 'stop'
 158  * is ISC_FALSE, ignore errors.
 159  *
 160  * dns_zt_loadnew() only loads zones that are not yet loaded.
 161  * dns_zt_load() also loads zones that are already loaded and
 162  * and whose master file has changed since the last load.
 163  * dns_zt_asyncload() loads zones asynchronously; when all
 164  * zones in the zone table have finished loaded (or failed due
 165  * to errors), the caller is informed by calling 'alldone'
 166  * with an argument of 'arg'.
 167  *
 168  * Requires:
 169  * \li  'zt' to be valid
 170  */
 171
 172 isc_result_t
 173 dns_zt_freezezones(dns_zt_t *zt, isc_boolean_t freeze);
 174 /*%<
 175  * Freeze/thaw updates to master zones.
 176  * Any pending updates will be flushed.
 177  * Zones will be reloaded on thaw.
 178  */
 179
 180 isc_result_t
 181 dns_zt_apply(dns_zt_t *zt, isc_boolean_t stop,
 182              isc_result_t (*action)(dns_zone_t *, void *), void *uap);
 183
 184 isc_result_t
 185 dns_zt_apply2(dns_zt_t *zt, isc_boolean_t stop, isc_result_t *sub,
 186               isc_result_t (*action)(dns_zone_t *, void *), void *uap);
 187 /*%<
 188  * Apply a given 'action' to all zone zones in the table.
 189  * If 'stop' is 'ISC_TRUE' then walking the zone tree will stop if
 190  * 'action' does not return ISC_R_SUCCESS.
 191  *
 192  * Requires:
 193  * \li  'zt' to be valid.
 194  * \li  'action' to be non NULL.
 195  *
 196  * Returns:
 197  * \li  ISC_R_SUCCESS if action was applied to all nodes.  If 'stop' is
 198  *      ISC_FALSE and 'sub' is non NULL then the first error (if any)
 199  *      reported by 'action' is returned in '*sub';
 200  *      any error code from 'action'.
 201  */
 202
 203 isc_boolean_t
 204 dns_zt_loadspending(dns_zt_t *zt);
 205 /*%<
 206  * Returns ISC_TRUE if and only if there are zones still waiting to
 207  * be loaded in zone table 'zt'.
 208  *
 209  * Requires:
 210  * \li  'zt' to be valid.
 211  */
 212
 213 ISC_LANG_ENDDECLS
 214
 215 #endif /* DNS_ZT_H */