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 49ISC_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 60typedef 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 77isc_result_t 78dns_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 94isc_result_t 95dns_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 107isc_result_t 108dns_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 122isc_result_t 123dns_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 137void 138dns_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 156void 157dns_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 171void 172dns_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 185ISC_LANG_ENDDECLS 186 187#endif /* DNS_RRITERATOR_H */ 188