/contrib/bind9/lib/dns/include/dns/dbiterator.h

  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 */