contrib/bind-9.3/lib/dns/include/dns/dbiterator.h

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