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