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

   1 /*
   2  * Copyright (C) 2004-2007, 2016  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  *\li   #DNS_R_PARTIALMATCH
 170  *      (node is at name above requested named when name has children)
 171  *
 172  *\li   Other results are possible, depending on the DB implementation.
 173  */
 174
 175 isc_result_t
 176 dns_dbiterator_prev(dns_dbiterator_t *iterator);
 177 /*%<
 178  * Move the node cursor to the previous node in the database (if any).
 179  *
 180  * Requires:
 181  *\li   'iterator' is a valid iterator.
 182  *
 183  * Returns:
 184  *\li   #ISC_R_SUCCESS
 185  *\li   #ISC_R_NOMORE                   There are no more nodes in the
 186  *                                      database.
 187  *
 188  *\li   Other results are possible, depending on the DB implementation.
 189  */
 190
 191 isc_result_t
 192 dns_dbiterator_next(dns_dbiterator_t *iterator);
 193 /*%<
 194  * Move the node cursor to the next node in the database (if any).
 195  *
 196  * Requires:
 197  *\li   'iterator' is a valid iterator.
 198  *
 199  * Returns:
 200  *\li   #ISC_R_SUCCESS
 201  *\li   #ISC_R_NOMORE                   There are no more nodes in the
 202  *                                      database.
 203  *
 204  *\li   Other results are possible, depending on the DB implementation.
 205  */
 206
 207 isc_result_t
 208 dns_dbiterator_current(dns_dbiterator_t *iterator, dns_dbnode_t **nodep,
 209                        dns_name_t *name);
 210 /*%<
 211  * Return the current node.
 212  *
 213  * Notes:
 214  *\li   If 'name' is not NULL, it will be set to the name of the node.
 215  *
 216  * Requires:
 217  *\li   'iterator' is a valid iterator.
 218  *
 219  *\li   nodep != NULL && *nodep == NULL
 220  *
 221  *\li   The node cursor of 'iterator' is at a valid location (i.e. the
 222  *      result of last call to a cursor movement command was ISC_R_SUCCESS).
 223  *
 224  *\li   'name' is NULL, or is a valid name with a dedicated buffer.
 225  *
 226  * Returns:
 227  *
 228  *\li   #ISC_R_SUCCESS
 229  *\li   #DNS_R_NEWORIGIN                        If this iterator was created with
 230  *                                      'relative_names' set to ISC_TRUE,
 231  *                                      then #DNS_R_NEWORIGIN will be returned
 232  *                                      when the origin the names are
 233  *                                      relative to changes.  This result
 234  *                                      can occur only when 'name' is not
 235  *                                      NULL.  This is also a successful
 236  *                                      result.
 237  *
 238  *\li   Other results are possible, depending on the DB implementation.
 239  */
 240
 241 isc_result_t
 242 dns_dbiterator_pause(dns_dbiterator_t *iterator);
 243 /*%<
 244  * Pause iteration.
 245  *
 246  * Calling a cursor movement method or dns_dbiterator_current() may cause
 247  * database locks to be acquired.  Rather than reacquire these locks every
 248  * time one of these routines is called, the locks may simply be held.
 249  * Calling dns_dbiterator_pause() releases any such locks.  Iterator clients
 250  * should call this routine any time they are not going to execute another
 251  * iterator method in the immediate future.
 252  *
 253  * Requires:
 254  *\li   'iterator' is a valid iterator.
 255  *
 256  * Ensures:
 257  *\li   Any database locks being held for efficiency of iterator access are
 258  *      released.
 259  *
 260  * Returns:
 261  *\li   #ISC_R_SUCCESS
 262  *
 263  *\li   Other results are possible, depending on the DB implementation.
 264  */
 265
 266 isc_result_t
 267 dns_dbiterator_origin(dns_dbiterator_t *iterator, dns_name_t *name);
 268 /*%<
 269  * Return the origin to which returned node names are relative.
 270  *
 271  * Requires:
 272  *
 273  *\li   'iterator' is a valid relative_names iterator.
 274  *
 275  *\li   'name' is a valid name with a dedicated buffer.
 276  *
 277  * Returns:
 278  *
 279  *\li   #ISC_R_SUCCESS
 280  *\li   #ISC_R_NOSPACE
 281  *
 282  *\li   Other results are possible, depending on the DB implementation.
 283  */
 284
 285 void
 286 dns_dbiterator_setcleanmode(dns_dbiterator_t *iterator, isc_boolean_t mode);
 287 /*%<
 288  * Indicate that the given iterator is/is not cleaning the DB.
 289  *
 290  * Notes:
 291  *\li   When 'mode' is ISC_TRUE,
 292  *
 293  * Requires:
 294  *\li   'iterator' is a valid iterator.
 295  */
 296
 297 ISC_LANG_ENDDECLS
 298
 299 #endif /* DNS_DBITERATOR_H */