BIND: update vendor tree to 9.5.2-P2
[dragonfly.git] / contrib / bind / 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
69 ISC_LANG_BEGINDECLS
70
71 /*****
72  ***** Types
73  *****/
74
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,
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  */
101 struct 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
110 void
111 dns_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
126 isc_result_t
127 dns_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
141 isc_result_t
142 dns_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
156 isc_result_t
157 dns_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
173 isc_result_t
174 dns_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
189 isc_result_t
190 dns_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
205 isc_result_t
206 dns_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
239 isc_result_t
240 dns_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
264 isc_result_t
265 dns_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
283 void
284 dns_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
295 ISC_LANG_ENDDECLS
296
297 #endif /* DNS_DBITERATOR_H */