1 /* $NetBSD: dbiterator.h,v 1.4 2014/12/10 04:37:58 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 1999-2001 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id: dbiterator.h,v 1.25 2007/06/19 23:47:16 tbox Exp */ 21 22 #ifndef DNS_DBITERATOR_H 23 #define DNS_DBITERATOR_H 1 24 25 /***** 26 ***** Module Info 27 *****/ 28 29 /*! \file dns/dbiterator.h 30 * \brief 31 * The DNS DB Iterator interface allows iteration of all of the nodes in a 32 * database. 33 * 34 * The dns_dbiterator_t type is like a "virtual class". To actually use 35 * it, an implementation of the class is required. This implementation is 36 * supplied by the database. 37 * 38 * It is the client's responsibility to call dns_db_detachnode() on all 39 * nodes returned. 40 * 41 * XXX <more> XXX 42 * 43 * MP: 44 *\li The iterator itself is not locked. The caller must ensure 45 * synchronization. 46 * 47 *\li The iterator methods ensure appropriate database locking. 48 * 49 * Reliability: 50 *\li No anticipated impact. 51 * 52 * Resources: 53 *\li TBS 54 * 55 * Security: 56 *\li No anticipated impact. 57 * 58 * Standards: 59 *\li None. 60 */ 61 62 /***** 63 ***** Imports 64 *****/ 65 66 #include <isc/lang.h> 67 #include <isc/magic.h> 68 69 #include <dns/types.h> 70 71 ISC_LANG_BEGINDECLS 72 73 /***** 74 ***** Types 75 *****/ 76 77 typedef struct dns_dbiteratormethods { 78 void (*destroy)(dns_dbiterator_t **iteratorp); 79 isc_result_t (*first)(dns_dbiterator_t *iterator); 80 isc_result_t (*last)(dns_dbiterator_t *iterator); 81 isc_result_t (*seek)(dns_dbiterator_t *iterator, dns_name_t *name); 82 isc_result_t (*prev)(dns_dbiterator_t *iterator); 83 isc_result_t (*next)(dns_dbiterator_t *iterator); 84 isc_result_t (*current)(dns_dbiterator_t *iterator, 85 dns_dbnode_t **nodep, dns_name_t *name); 86 isc_result_t (*pause)(dns_dbiterator_t *iterator); 87 isc_result_t (*origin)(dns_dbiterator_t *iterator, 88 dns_name_t *name); 89 } dns_dbiteratormethods_t; 90 91 #define DNS_DBITERATOR_MAGIC ISC_MAGIC('D','N','S','I') 92 #define DNS_DBITERATOR_VALID(dbi) ISC_MAGIC_VALID(dbi, DNS_DBITERATOR_MAGIC) 93 /*% 94 * This structure is actually just the common prefix of a DNS db 95 * implementation's version of a dns_dbiterator_t. 96 * 97 * Clients may use the 'db' field of this structure. Except for that field, 98 * direct use of this structure by clients is forbidden. DB implementations 99 * may change the structure. 'magic' must be DNS_DBITERATOR_MAGIC for any of 100 * the dns_dbiterator routines to work. DB iterator implementations must 101 * maintain all DB iterator invariants. 102 */ 103 struct dns_dbiterator { 104 /* Unlocked. */ 105 unsigned int magic; 106 dns_dbiteratormethods_t * methods; 107 dns_db_t * db; 108 isc_boolean_t relative_names; 109 isc_boolean_t cleaning; 110 }; 111 112 void 113 dns_dbiterator_destroy(dns_dbiterator_t **iteratorp); 114 /*%< 115 * Destroy '*iteratorp'. 116 * 117 * Requires: 118 * 119 *\li '*iteratorp' is a valid iterator. 120 * 121 * Ensures: 122 * 123 *\li All resources used by the iterator are freed. 124 * 125 *\li *iteratorp == NULL. 126 */ 127 128 isc_result_t 129 dns_dbiterator_first(dns_dbiterator_t *iterator); 130 /*%< 131 * Move the node cursor to the first node in the database (if any). 132 * 133 * Requires: 134 *\li 'iterator' is a valid iterator. 135 * 136 * Returns: 137 *\li #ISC_R_SUCCESS 138 *\li #ISC_R_NOMORE There are no nodes in the database. 139 * 140 *\li Other results are possible, depending on the DB implementation. 141 */ 142 143 isc_result_t 144 dns_dbiterator_last(dns_dbiterator_t *iterator); 145 /*%< 146 * Move the node cursor to the last node in the database (if any). 147 * 148 * Requires: 149 *\li 'iterator' is a valid iterator. 150 * 151 * Returns: 152 *\li #ISC_R_SUCCESS 153 *\li #ISC_R_NOMORE There are no nodes in the database. 154 * 155 *\li Other results are possible, depending on the DB implementation. 156 */ 157 158 isc_result_t 159 dns_dbiterator_seek(dns_dbiterator_t *iterator, dns_name_t *name); 160 /*%< 161 * Move the node cursor to the node with name 'name'. 162 * 163 * Requires: 164 *\li 'iterator' is a valid iterator. 165 * 166 *\li 'name' is a valid name. 167 * 168 * Returns: 169 *\li #ISC_R_SUCCESS 170 *\li #ISC_R_NOTFOUND 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 */ 300