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

   1 /*
   2  * Copyright (C) 2009, 2011, 2012  Internet Systems Consortium, Inc. ("ISC")
   3  *
   4  * Permission to use, copy, modify, and/or distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   9  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14  * PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 /* $Id$ */
  18
  19 #ifndef DNS_RRITERATOR_H
  20 #define DNS_RRITERATOR_H 1
  21
  22 /*****
  23  ***** Module Info
  24  *****/
  25
  26 /*! \file dns/rriterator.h
  27  * \brief
  28  * Functions for "walking" a zone database, visiting each RR or RRset in turn.
  29  */
  30
  31 /*****
  32  ***** Imports
  33  *****/
  34
  35 #include <isc/lang.h>
  36 #include <isc/magic.h>
  37 #include <isc/ondestroy.h>
  38 #include <isc/stdtime.h>
  39
  40 #include <dns/db.h>
  41 #include <dns/dbiterator.h>
  42 #include <dns/fixedname.h>
  43 #include <dns/name.h>
  44 #include <dns/rdata.h>
  45 #include <dns/rdataset.h>
  46 #include <dns/rdatasetiter.h>
  47 #include <dns/types.h>
  48
  49 ISC_LANG_BEGINDECLS
  50
  51 /*****
  52  ***** Types
  53  *****/
  54
  55 /*%
  56  * A dns_rriterator_t is an iterator that iterates over an entire database,
  57  * returning one RR at a time, in some arbitrary order.
  58  */
  59
  60 typedef struct dns_rriterator {
  61         unsigned int            magic;
  62         isc_result_t            result;
  63         dns_db_t                *db;
  64         dns_dbiterator_t        *dbit;
  65         dns_dbversion_t         *ver;
  66         isc_stdtime_t           now;
  67         dns_dbnode_t            *node;
  68         dns_fixedname_t         fixedname;
  69         dns_rdatasetiter_t      *rdatasetit;
  70         dns_rdataset_t          rdataset;
  71         dns_rdata_t             rdata;
  72 } dns_rriterator_t;
  73
  74 #define RRITERATOR_MAGIC                ISC_MAGIC('R', 'R', 'I', 't')
  75 #define VALID_RRITERATOR(m)             ISC_MAGIC_VALID(m, RRITERATOR_MAGIC)
  76
  77 isc_result_t
  78 dns_rriterator_init(dns_rriterator_t *it, dns_db_t *db,
  79                        dns_dbversion_t *ver, isc_stdtime_t now);
  80 /*%
  81  * Initialize an rriterator; sets the cursor to the origin node
  82  * of the database.
  83  *
  84  * Requires:
  85  *
  86  * \li  'db' is a valid database.
  87  *
  88  * Returns:
  89  *
  90  * \li  #ISC_R_SUCCESS
  91  * \li  #ISC_R_NOMEMORY
  92  */
  93
  94 isc_result_t
  95 dns_rriterator_first(dns_rriterator_t *it);
  96 /*%<
  97  * Move the rriterator cursor to the first rdata in the database.
  98  *
  99  * Requires:
 100  *\li   'it' is a valid, initialized rriterator
 101  *
 102  * Returns:
 103  *\li   #ISC_R_SUCCESS
 104  *\li   #ISC_R_NOMORE                   There are no rdata in the set.
 105  */
 106
 107 isc_result_t
 108 dns_rriterator_nextrrset(dns_rriterator_t *it);
 109 /*%<
 110  * Move the rriterator cursor to the next rrset in the database,
 111  * skipping over any remaining records that have the same rdatatype
 112  * as the current one.
 113  *
 114  * Requires:
 115  *\li   'it' is a valid, initialized rriterator
 116  *
 117  * Returns:
 118  *\li   #ISC_R_SUCCESS
 119  *\li   #ISC_R_NOMORE                   No more rrsets in the database
 120  */
 121
 122 isc_result_t
 123 dns_rriterator_next(dns_rriterator_t *it);
 124 /*%<
 125  * Move the rriterator cursor to the next rrset in the database,
 126  * skipping over any remaining records that have the same rdatatype
 127  * as the current one.
 128  *
 129  * Requires:
 130  *\li   'it' is a valid, initialized rriterator
 131  *
 132  * Returns:
 133  *\li   #ISC_R_SUCCESS
 134  *\li   #ISC_R_NOMORE                   No more records in the database
 135  */
 136
 137 void
 138 dns_rriterator_current(dns_rriterator_t *it, dns_name_t **name,
 139                           isc_uint32_t *ttl, dns_rdataset_t **rdataset,
 140                           dns_rdata_t **rdata);
 141 /*%<
 142  * Make '*name' refer to the current name.  If 'rdataset' is not NULL,
 143  * make '*rdataset' refer to the current * rdataset.  If '*rdata' is not
 144  * NULL, make '*rdata' refer to the current record.
 145  *
 146  * Requires:
 147  *\li   '*name' is a valid name object
 148  *\li   'rdataset' is NULL or '*rdataset' is NULL
 149  *\li   'rdata' is NULL or '*rdata' is NULL
 150  *
 151  * Ensures:
 152  *\li   'rdata' refers to the rdata at the rdata cursor location of
 153  *\li   'rdataset'.
 154  */
 155
 156 void
 157 dns_rriterator_pause(dns_rriterator_t *it);
 158 /*%<
 159  * Pause rriterator.  Frees any locks held by the database iterator.
 160  * Callers should use this routine any time they are not going to
 161  * execute another rriterator method in the immediate future.
 162  *
 163  * Requires:
 164  *\li   'it' is a valid iterator.
 165  *
 166  * Ensures:
 167  *\li   Any database locks being held for efficiency of iterator access are
 168  *      released.
 169  */
 170
 171 void
 172 dns_rriterator_destroy(dns_rriterator_t *it);
 173 /*%<
 174  * Shut down and free resources in rriterator 'it'.
 175  *
 176  * Requires:
 177  *
 178  *\li   'it' is a valid iterator.
 179  *
 180  * Ensures:
 181  *
 182  *\li   All resources used by the rriterator are freed.
 183  */
 184
 185 ISC_LANG_ENDDECLS
 186
 187 #endif /* DNS_RRITERATOR_H */