contrib/bind-9.5.2/lib/dns/include/dns/dbiterator.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: dbiterator.h,v 1.25 2007/06/19 23:47:16 tbox Exp $ */
  19
  20 #ifndef DNS_DBITERATOR_H
  21 #define DNS_DBITERATOR_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file dns/dbiterator.h
  28  * \brief
  29  * The DNS DB Iterator interface allows iteration of all of the nodes in a
  30  * database.
  31  *
  32  * The dns_dbiterator_t type is like a "virtual class".  To actually use
  33  * it, an implementation of the class is required.  This implementation is
  34  * supplied by the database.
  35  *
  36  * It is the client's responsibility to call dns_db_detachnode() on all
  37  * nodes returned.
  38  *
  39  * XXX &lt;more&gt; XXX
  40  *
  41  * MP:
  42  *\li   The iterator itself is not locked.  The caller must ensure
  43  *      synchronization.
  44  *
  45  *\li   The iterator methods ensure appropriate database locking.
  46  *
  47  * Reliability:
  48  *\li   No anticipated impact.
  49  *
  50  * Resources:
  51  *\li   TBS
  52  *
  53  * Security:
  54  *\li   No anticipated impact.
  55  *
  56  * Standards:
  57  *\li   None.
  58  */
  59
  60 /*****
  61  ***** Imports
  62  *****/
  63
  64 #include <isc/lang.h>
  65 #include <isc/magic.h>
  66
  67 #include <dns/types.h>
  68
  69 ISC_LANG_BEGINDECLS
  70
  71 /*****
  72  ***** Types
  73  *****/
  74
  75 typedef struct dns_dbiteratormethods {
  76         void            (*destroy)(dns_dbiterator_t **iteratorp);
  77         isc_result_t    (*first)(dns_dbiterator_t *iterator);
  78         isc_result_t    (*last)(dns_dbiterator_t *iterator);
  79         isc_result_t    (*seek)(dns_dbiterator_t *iterator, dns_name_t *name);
  80         isc_result_t    (*prev)(dns_dbiterator_t *iterator);
  81         isc_result_t    (*next)(dns_dbiterator_t *iterator);
  82         isc_result_t    (*current)(dns_dbiterator_t *iterator,
  83                                    dns_dbnode_t **nodep, dns_name_t *name);
  84         isc_result_t    (*pause)(dns_dbiterator_t *iterator);
  85         isc_result_t    (*origin)(dns_dbiterator_t *iterator,
  86                                   dns_name_t *name);
  87 } dns_dbiteratormethods_t;
  88
  89 #define DNS_DBITERATOR_MAGIC         ISC_MAGIC('D','N','S','I')
  90 #define DNS_DBITERATOR_VALID(dbi)    ISC_MAGIC_VALID(dbi, DNS_DBITERATOR_MAGIC)
  91 /*%
  92  * This structure is actually just the common prefix of a DNS db
  93  * implementation's version of a dns_dbiterator_t.
  94  *
  95  * Clients may use the 'db' field of this structure.  Except for that field,
  96  * direct use of this structure by clients is forbidden.  DB implementations
  97  * may change the structure.  'magic' must be DNS_DBITERATOR_MAGIC for any of
  98  * the dns_dbiterator routines to work.  DB iterator implementations must
  99  * maintain all DB iterator invariants.
 100  */
 101 struct dns_dbiterator {
 102         /* Unlocked. */
 103         unsigned int                    magic;
 104         dns_dbiteratormethods_t *       methods;
 105         dns_db_t *                      db;
 106         isc_boolean_t                   relative_names;
 107         isc_boolean_t                   cleaning;
 108 };
 109
 110 void
 111 dns_dbiterator_destroy(dns_dbiterator_t **iteratorp);
 112 /*%<
 113  * Destroy '*iteratorp'.
 114  *
 115  * Requires:
 116  *
 117  *\li   '*iteratorp' is a valid iterator.
 118  *
 119  * Ensures:
 120  *
 121  *\li   All resources used by the iterator are freed.
 122  *
 123  *\li   *iteratorp == NULL.
 124  */
 125
 126 isc_result_t
 127 dns_dbiterator_first(dns_dbiterator_t *iterator);
 128 /*%<
 129  * Move the node cursor to the first node in the database (if any).
 130  *
 131  * Requires:
 132  *\li   'iterator' is a valid iterator.
 133  *
 134  * Returns:
 135  *\li   #ISC_R_SUCCESS
 136  *\li   #ISC_R_NOMORE                   There are no nodes in the database.
 137  *
 138  *\li   Other results are possible, depending on the DB implementation.
 139  */
 140
 141 isc_result_t
 142 dns_dbiterator_last(dns_dbiterator_t *iterator);
 143 /*%<
 144  * Move the node cursor to the last node in the database (if any).
 145  *
 146  * Requires:
 147  *\li   'iterator' is a valid iterator.
 148  *
 149  * Returns:
 150  *\li   #ISC_R_SUCCESS
 151  *\li   #ISC_R_NOMORE                   There are no nodes in the database.
 152  *
 153  *\li   Other results are possible, depending on the DB implementation.
 154  */
 155
 156 isc_result_t
 157 dns_dbiterator_seek(dns_dbiterator_t *iterator, dns_name_t *name);
 158 /*%<
 159  * Move the node cursor to the node with name 'name'.
 160  *
 161  * Requires:
 162  *\li   'iterator' is a valid iterator.
 163  *
 164  *\li   'name' is a valid name.
 165  *
 166  * Returns:
 167  *\li   #ISC_R_SUCCESS
 168  *\li   #ISC_R_NOTFOUND
 169  *
 170  *\li   Other results are possible, depending on the DB implementation.
 171  */
 172
 173 isc_result_t
 174 dns_dbiterator_prev(dns_dbiterator_t *iterator);
 175 /*%<
 176  * Move the node cursor to the previous node in the database (if any).
 177  *
 178  * Requires:
 179  *\li   'iterator' is a valid iterator.
 180  *
 181  * Returns:
 182  *\li   #ISC_R_SUCCESS
 183  *\li   #ISC_R_NOMORE                   There are no more nodes in the
 184  *                                      database.
 185  *
 186  *\li   Other results are possible, depending on the DB implementation.
 187  */
 188
 189 isc_result_t
 190 dns_dbiterator_next(dns_dbiterator_t *iterator);
 191 /*%<
 192  * Move the node cursor to the next node in the database (if any).
 193  *
 194  * Requires:
 195  *\li   'iterator' is a valid iterator.
 196  *
 197  * Returns:
 198  *\li   #ISC_R_SUCCESS
 199  *\li   #ISC_R_NOMORE                   There are no more nodes in the
 200  *                                      database.
 201  *
 202  *\li   Other results are possible, depending on the DB implementation.
 203  */
 204
 205 isc_result_t
 206 dns_dbiterator_current(dns_dbiterator_t *iterator, dns_dbnode_t **nodep,
 207                        dns_name_t *name);
 208 /*%<
 209  * Return the current node.
 210  *
 211  * Notes:
 212  *\li   If 'name' is not NULL, it will be set to the name of the node.
 213  *
 214  * Requires:
 215  *\li   'iterator' is a valid iterator.
 216  *
 217  *\li   nodep != NULL && *nodep == NULL
 218  *
 219  *\li   The node cursor of 'iterator' is at a valid location (i.e. the
 220  *      result of last call to a cursor movement command was ISC_R_SUCCESS).
 221  *
 222  *\li   'name' is NULL, or is a valid name with a dedicated buffer.
 223  *
 224  * Returns:
 225  *
 226  *\li   #ISC_R_SUCCESS
 227  *\li   #DNS_R_NEWORIGIN                        If this iterator was created with
 228  *                                      'relative_names' set to ISC_TRUE,
 229  *                                      then #DNS_R_NEWORIGIN will be returned
 230  *                                      when the origin the names are
 231  *                                      relative to changes.  This result
 232  *                                      can occur only when 'name' is not
 233  *                                      NULL.  This is also a successful
 234  *                                      result.
 235  *
 236  *\li   Other results are possible, depending on the DB implementation.
 237  */
 238
 239 isc_result_t
 240 dns_dbiterator_pause(dns_dbiterator_t *iterator);
 241 /*%<
 242  * Pause iteration.
 243  *
 244  * Calling a cursor movement method or dns_dbiterator_current() may cause
 245  * database locks to be acquired.  Rather than reacquire these locks every
 246  * time one of these routines is called, the locks may simply be held.
 247  * Calling dns_dbiterator_pause() releases any such locks.  Iterator clients
 248  * should call this routine any time they are not going to execute another
 249  * iterator method in the immediate future.
 250  *
 251  * Requires:
 252  *\li   'iterator' is a valid iterator.
 253  *
 254  * Ensures:
 255  *\li   Any database locks being held for efficiency of iterator access are
 256  *      released.
 257  *
 258  * Returns:
 259  *\li   #ISC_R_SUCCESS
 260  *
 261  *\li   Other results are possible, depending on the DB implementation.
 262  */
 263
 264 isc_result_t
 265 dns_dbiterator_origin(dns_dbiterator_t *iterator, dns_name_t *name);
 266 /*%<
 267  * Return the origin to which returned node names are relative.
 268  *
 269  * Requires:
 270  *
 271  *\li   'iterator' is a valid relative_names iterator.
 272  *
 273  *\li   'name' is a valid name with a dedicated buffer.
 274  *
 275  * Returns:
 276  *
 277  *\li   #ISC_R_SUCCESS
 278  *\li   #ISC_R_NOSPACE
 279  *
 280  *\li   Other results are possible, depending on the DB implementation.
 281  */
 282
 283 void
 284 dns_dbiterator_setcleanmode(dns_dbiterator_t *iterator, isc_boolean_t mode);
 285 /*%<
 286  * Indicate that the given iterator is/is not cleaning the DB.
 287  *
 288  * Notes:
 289  *\li   When 'mode' is ISC_TRUE,
 290  *
 291  * Requires:
 292  *\li   'iterator' is a valid iterator.
 293  */
 294
 295 ISC_LANG_ENDDECLS
 296
 297 #endif /* DNS_DBITERATOR_H */