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