BIND: update vendor tree to 9.5.2-P2
[dragonfly.git] / contrib / bind / lib / dns / include / dns / rdatasetiter.h
CommitLineData
bbbf71a3
JL
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: rdatasetiter.h,v 1.21 2007/06/19 23:47:17 tbox Exp $ */
19
20#ifndef DNS_RDATASETITER_H
21#define DNS_RDATASETITER_H 1
22
23/*****
24 ***** Module Info
25 *****/
26
27/*! \file dns/rdatasetiter.h
28 * \brief
29 * The DNS Rdataset Iterator interface allows iteration of all of the
30 * rdatasets at a node.
31 *
32 * The dns_rdatasetiter_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_rdataset_disassociate()
37 * on all rdatasets 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#include <isc/stdtime.h>
67
68#include <dns/types.h>
69
70ISC_LANG_BEGINDECLS
71
72/*****
73 ***** Types
74 *****/
75
76typedef struct dns_rdatasetitermethods {
77 void (*destroy)(dns_rdatasetiter_t **iteratorp);
78 isc_result_t (*first)(dns_rdatasetiter_t *iterator);
79 isc_result_t (*next)(dns_rdatasetiter_t *iterator);
80 void (*current)(dns_rdatasetiter_t *iterator,
81 dns_rdataset_t *rdataset);
82} dns_rdatasetitermethods_t;
83
84#define DNS_RDATASETITER_MAGIC ISC_MAGIC('D','N','S','i')
85#define DNS_RDATASETITER_VALID(i) ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC)
86
87/*%
88 * This structure is actually just the common prefix of a DNS db
89 * implementation's version of a dns_rdatasetiter_t.
90 * \brief
91 * Direct use of this structure by clients is forbidden. DB implementations
92 * may change the structure. 'magic' must be #DNS_RDATASETITER_MAGIC for
93 * any of the dns_rdatasetiter routines to work. DB implementations must
94 * maintain all DB rdataset iterator invariants.
95 */
96struct dns_rdatasetiter {
97 /* Unlocked. */
98 unsigned int magic;
99 dns_rdatasetitermethods_t * methods;
100 dns_db_t * db;
101 dns_dbnode_t * node;
102 dns_dbversion_t * version;
103 isc_stdtime_t now;
104};
105
106void
107dns_rdatasetiter_destroy(dns_rdatasetiter_t **iteratorp);
108/*%<
109 * Destroy '*iteratorp'.
110 *
111 * Requires:
112 *
113 *\li '*iteratorp' is a valid iterator.
114 *
115 * Ensures:
116 *
117 *\li All resources used by the iterator are freed.
118 *
119 *\li *iteratorp == NULL.
120 */
121
122isc_result_t
123dns_rdatasetiter_first(dns_rdatasetiter_t *iterator);
124/*%<
125 * Move the rdataset cursor to the first rdataset at the node (if any).
126 *
127 * Requires:
128 *\li 'iterator' is a valid iterator.
129 *
130 * Returns:
131 *\li ISC_R_SUCCESS
132 *\li ISC_R_NOMORE There are no rdatasets at the node.
133 *
134 *\li Other results are possible, depending on the DB implementation.
135 */
136
137isc_result_t
138dns_rdatasetiter_next(dns_rdatasetiter_t *iterator);
139/*%<
140 * Move the rdataset cursor to the next rdataset at the node (if any).
141 *
142 * Requires:
143 *\li 'iterator' is a valid iterator.
144 *
145 * Returns:
146 *\li ISC_R_SUCCESS
147 *\li ISC_R_NOMORE There are no more rdatasets at the
148 * node.
149 *
150 *\li Other results are possible, depending on the DB implementation.
151 */
152
153void
154dns_rdatasetiter_current(dns_rdatasetiter_t *iterator,
155 dns_rdataset_t *rdataset);
156/*%<
157 * Return the current rdataset.
158 *
159 * Requires:
160 *\li 'iterator' is a valid iterator.
161 *
162 *\li 'rdataset' is a valid, disassociated rdataset.
163 *
164 *\li The rdataset cursor of 'iterator' is at a valid location (i.e. the
165 * result of last call to a cursor movement command was #ISC_R_SUCCESS).
166 */
167
168ISC_LANG_ENDDECLS
169
170#endif /* DNS_RDATASETITER_H */