1 /*
2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3  *
4  * This Source Code Form is subject to the terms of the Mozilla Public
5  * License, v. 2.0. If a copy of the MPL was not distributed with this
6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7  *
8  * See the COPYRIGHT file distributed with this work for additional
9  * information regarding copyright ownership.
10  */
11 
12 #ifndef DNS_RDATASETITER_H
13 #define DNS_RDATASETITER_H 1
14 
15 /*****
16 ***** Module Info
17 *****/
18 
19 /*! \file dns/rdatasetiter.h
20  * \brief
21  * The DNS Rdataset Iterator interface allows iteration of all of the
22  * rdatasets at a node.
23  *
24  * The dns_rdatasetiter_t type is like a "virtual class".  To actually use
25  * it, an implementation of the class is required.  This implementation is
26  * supplied by the database.
27  *
28  * It is the client's responsibility to call dns_rdataset_disassociate()
29  * on all rdatasets returned.
30  *
31  * XXX more XXX
32  *
33  * MP:
34  *\li	The iterator itself is not locked.  The caller must ensure
35  *	synchronization.
36  *
37  *\li	The iterator methods ensure appropriate database locking.
38  *
39  * Reliability:
40  *\li	No anticipated impact.
41  *
42  * Resources:
43  *\li	TBS
44  *
45  * Security:
46  *\li	No anticipated impact.
47  *
48  * Standards:
49  *\li	None.
50  */
51 
52 /*****
53 ***** Imports
54 *****/
55 
56 #include <isc/lang.h>
57 #include <isc/magic.h>
58 #include <isc/stdtime.h>
59 
60 #include <dns/types.h>
61 
62 ISC_LANG_BEGINDECLS
63 
64 /*****
65 ***** Types
66 *****/
67 
68 typedef struct dns_rdatasetitermethods {
69 	void (*destroy)(dns_rdatasetiter_t **iteratorp);
70 	isc_result_t (*first)(dns_rdatasetiter_t *iterator);
71 	isc_result_t (*next)(dns_rdatasetiter_t *iterator);
72 	void (*current)(dns_rdatasetiter_t *iterator, dns_rdataset_t *rdataset);
73 } dns_rdatasetitermethods_t;
74 
75 #define DNS_RDATASETITER_MAGIC	  ISC_MAGIC('D', 'N', 'S', 'i')
76 #define DNS_RDATASETITER_VALID(i) ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC)
77 
78 /*%
79  * This structure is actually just the common prefix of a DNS db
80  * implementation's version of a dns_rdatasetiter_t.
81  * \brief
82  * Direct use of this structure by clients is forbidden.  DB implementations
83  * may change the structure.  'magic' must be #DNS_RDATASETITER_MAGIC for
84  * any of the dns_rdatasetiter routines to work.  DB implementations must
85  * maintain all DB rdataset iterator invariants.
86  */
87 struct dns_rdatasetiter {
88 	/* Unlocked. */
89 	unsigned int		   magic;
90 	dns_rdatasetitermethods_t *methods;
91 	dns_db_t *		   db;
92 	dns_dbnode_t *		   node;
93 	dns_dbversion_t *	   version;
94 	isc_stdtime_t		   now;
95 };
96 
97 void
98 dns_rdatasetiter_destroy(dns_rdatasetiter_t **iteratorp);
99 /*%<
100  * Destroy '*iteratorp'.
101  *
102  * Requires:
103  *
104  *\li	'*iteratorp' is a valid iterator.
105  *
106  * Ensures:
107  *
108  *\li	All resources used by the iterator are freed.
109  *
110  *\li	*iteratorp == NULL.
111  */
112 
113 isc_result_t
114 dns_rdatasetiter_first(dns_rdatasetiter_t *iterator);
115 /*%<
116  * Move the rdataset cursor to the first rdataset at the node (if any).
117  *
118  * Requires:
119  *\li	'iterator' is a valid iterator.
120  *
121  * Returns:
122  *\li	ISC_R_SUCCESS
123  *\li	ISC_R_NOMORE			There are no rdatasets at the node.
124  *
125  *\li	Other results are possible, depending on the DB implementation.
126  */
127 
128 isc_result_t
129 dns_rdatasetiter_next(dns_rdatasetiter_t *iterator);
130 /*%<
131  * Move the rdataset cursor to the next rdataset at the node (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 more rdatasets at the
139  *					node.
140  *
141  *\li	Other results are possible, depending on the DB implementation.
142  */
143 
144 void
145 dns_rdatasetiter_current(dns_rdatasetiter_t *iterator,
146 			 dns_rdataset_t *    rdataset);
147 /*%<
148  * Return the current rdataset.
149  *
150  * Requires:
151  *\li	'iterator' is a valid iterator.
152  *
153  *\li	'rdataset' is a valid, disassociated rdataset.
154  *
155  *\li	The rdataset cursor of 'iterator' is at a valid location (i.e. the
156  *	result of last call to a cursor movement command was #ISC_R_SUCCESS).
157  */
158 
159 ISC_LANG_ENDDECLS
160 
161 #endif /* DNS_RDATASETITER_H */
162