2 * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2001 Internet Software Consortium.
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.
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.
18 /* $Id: dbiterator.h,v 1.25 2007/06/19 23:47:16 tbox Exp $ */
20 #ifndef DNS_DBITERATOR_H
21 #define DNS_DBITERATOR_H 1
27 /*! \file dns/dbiterator.h
29 * The DNS DB Iterator interface allows iteration of all of the nodes in a
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.
36 * It is the client's responsibility to call dns_db_detachnode() on all
39 * XXX <more> XXX
42 *\li The iterator itself is not locked. The caller must ensure
45 *\li The iterator methods ensure appropriate database locking.
48 *\li No anticipated impact.
54 *\li No anticipated impact.
65 #include <isc/magic.h>
67 #include <dns/types.h>
75 typedef 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,
87 } dns_dbiteratormethods_t;
89 #define DNS_DBITERATOR_MAGIC ISC_MAGIC('D','N','S','I')
90 #define DNS_DBITERATOR_VALID(dbi) ISC_MAGIC_VALID(dbi, DNS_DBITERATOR_MAGIC)
92 * This structure is actually just the common prefix of a DNS db
93 * implementation's version of a dns_dbiterator_t.
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.
101 struct dns_dbiterator {
104 dns_dbiteratormethods_t * methods;
106 isc_boolean_t relative_names;
107 isc_boolean_t cleaning;
111 dns_dbiterator_destroy(dns_dbiterator_t **iteratorp);
113 * Destroy '*iteratorp'.
117 *\li '*iteratorp' is a valid iterator.
121 *\li All resources used by the iterator are freed.
123 *\li *iteratorp == NULL.
127 dns_dbiterator_first(dns_dbiterator_t *iterator);
129 * Move the node cursor to the first node in the database (if any).
132 *\li 'iterator' is a valid iterator.
136 *\li #ISC_R_NOMORE There are no nodes in the database.
138 *\li Other results are possible, depending on the DB implementation.
142 dns_dbiterator_last(dns_dbiterator_t *iterator);
144 * Move the node cursor to the last node in the database (if any).
147 *\li 'iterator' is a valid iterator.
151 *\li #ISC_R_NOMORE There are no nodes in the database.
153 *\li Other results are possible, depending on the DB implementation.
157 dns_dbiterator_seek(dns_dbiterator_t *iterator, dns_name_t *name);
159 * Move the node cursor to the node with name 'name'.
162 *\li 'iterator' is a valid iterator.
164 *\li 'name' is a valid name.
170 *\li Other results are possible, depending on the DB implementation.
174 dns_dbiterator_prev(dns_dbiterator_t *iterator);
176 * Move the node cursor to the previous node in the database (if any).
179 *\li 'iterator' is a valid iterator.
183 *\li #ISC_R_NOMORE There are no more nodes in the
186 *\li Other results are possible, depending on the DB implementation.
190 dns_dbiterator_next(dns_dbiterator_t *iterator);
192 * Move the node cursor to the next node in the database (if any).
195 *\li 'iterator' is a valid iterator.
199 *\li #ISC_R_NOMORE There are no more nodes in the
202 *\li Other results are possible, depending on the DB implementation.
206 dns_dbiterator_current(dns_dbiterator_t *iterator, dns_dbnode_t **nodep,
209 * Return the current node.
212 *\li If 'name' is not NULL, it will be set to the name of the node.
215 *\li 'iterator' is a valid iterator.
217 *\li nodep != NULL && *nodep == NULL
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).
222 *\li 'name' is NULL, or is a valid name with a dedicated buffer.
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
236 *\li Other results are possible, depending on the DB implementation.
240 dns_dbiterator_pause(dns_dbiterator_t *iterator);
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.
252 *\li 'iterator' is a valid iterator.
255 *\li Any database locks being held for efficiency of iterator access are
261 *\li Other results are possible, depending on the DB implementation.
265 dns_dbiterator_origin(dns_dbiterator_t *iterator, dns_name_t *name);
267 * Return the origin to which returned node names are relative.
271 *\li 'iterator' is a valid relative_names iterator.
273 *\li 'name' is a valid name with a dedicated buffer.
280 *\li Other results are possible, depending on the DB implementation.
284 dns_dbiterator_setcleanmode(dns_dbiterator_t *iterator, isc_boolean_t mode);
286 * Indicate that the given iterator is/is not cleaning the DB.
289 *\li When 'mode' is ISC_TRUE,
292 *\li 'iterator' is a valid iterator.
297 #endif /* DNS_DBITERATOR_H */