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