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