1 /*	$NetBSD: rdatasetiter.h,v 1.4 2014/12/10 04:37:58 christos Exp $	*/
2 
3 /*
4  * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
5  * Copyright (C) 1999-2001  Internet Software Consortium.
6  *
7  * Permission to use, copy, modify, and/or distribute this software for any
8  * purpose with or without fee is hereby granted, provided that the above
9  * copyright notice and this permission notice appear in all copies.
10  *
11  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17  * PERFORMANCE OF THIS SOFTWARE.
18  */
19 
20 /* Id: rdatasetiter.h,v 1.21 2007/06/19 23:47:17 tbox Exp  */
21 
22 #ifndef DNS_RDATASETITER_H
23 #define DNS_RDATASETITER_H 1
24 
25 /*****
26  ***** Module Info
27  *****/
28 
29 /*! \file dns/rdatasetiter.h
30  * \brief
31  * The DNS Rdataset Iterator interface allows iteration of all of the
32  * rdatasets at a node.
33  *
34  * The dns_rdatasetiter_t type is like a "virtual class".  To actually use
35  * it, an implementation of the class is required.  This implementation is
36  * supplied by the database.
37  *
38  * It is the client's responsibility to call dns_rdataset_disassociate()
39  * on all rdatasets returned.
40  *
41  * XXX more XXX
42  *
43  * MP:
44  *\li	The iterator itself is not locked.  The caller must ensure
45  *	synchronization.
46  *
47  *\li	The iterator methods ensure appropriate database locking.
48  *
49  * Reliability:
50  *\li	No anticipated impact.
51  *
52  * Resources:
53  *\li	TBS
54  *
55  * Security:
56  *\li	No anticipated impact.
57  *
58  * Standards:
59  *\li	None.
60  */
61 
62 /*****
63  ***** Imports
64  *****/
65 
66 #include <isc/lang.h>
67 #include <isc/magic.h>
68 #include <isc/stdtime.h>
69 
70 #include <dns/types.h>
71 
72 ISC_LANG_BEGINDECLS
73 
74 /*****
75  ***** Types
76  *****/
77 
78 typedef struct dns_rdatasetitermethods {
79 	void		(*destroy)(dns_rdatasetiter_t **iteratorp);
80 	isc_result_t	(*first)(dns_rdatasetiter_t *iterator);
81 	isc_result_t	(*next)(dns_rdatasetiter_t *iterator);
82 	void		(*current)(dns_rdatasetiter_t *iterator,
83 				   dns_rdataset_t *rdataset);
84 } dns_rdatasetitermethods_t;
85 
86 #define DNS_RDATASETITER_MAGIC	     ISC_MAGIC('D','N','S','i')
87 #define DNS_RDATASETITER_VALID(i)    ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC)
88 
89 /*%
90  * This structure is actually just the common prefix of a DNS db
91  * implementation's version of a dns_rdatasetiter_t.
92  * \brief
93  * Direct use of this structure by clients is forbidden.  DB implementations
94  * may change the structure.  'magic' must be #DNS_RDATASETITER_MAGIC for
95  * any of the dns_rdatasetiter routines to work.  DB implementations must
96  * maintain all DB rdataset iterator invariants.
97  */
98 struct dns_rdatasetiter {
99 	/* Unlocked. */
100 	unsigned int			magic;
101 	dns_rdatasetitermethods_t *	methods;
102 	dns_db_t *			db;
103 	dns_dbnode_t *			node;
104 	dns_dbversion_t *		version;
105 	isc_stdtime_t			now;
106 };
107 
108 void
109 dns_rdatasetiter_destroy(dns_rdatasetiter_t **iteratorp);
110 /*%<
111  * Destroy '*iteratorp'.
112  *
113  * Requires:
114  *
115  *\li	'*iteratorp' is a valid iterator.
116  *
117  * Ensures:
118  *
119  *\li	All resources used by the iterator are freed.
120  *
121  *\li	*iteratorp == NULL.
122  */
123 
124 isc_result_t
125 dns_rdatasetiter_first(dns_rdatasetiter_t *iterator);
126 /*%<
127  * Move the rdataset cursor to the first rdataset at the node (if any).
128  *
129  * Requires:
130  *\li	'iterator' is a valid iterator.
131  *
132  * Returns:
133  *\li	ISC_R_SUCCESS
134  *\li	ISC_R_NOMORE			There are no rdatasets at the node.
135  *
136  *\li	Other results are possible, depending on the DB implementation.
137  */
138 
139 isc_result_t
140 dns_rdatasetiter_next(dns_rdatasetiter_t *iterator);
141 /*%<
142  * Move the rdataset cursor to the next rdataset at the node (if any).
143  *
144  * Requires:
145  *\li	'iterator' is a valid iterator.
146  *
147  * Returns:
148  *\li	ISC_R_SUCCESS
149  *\li	ISC_R_NOMORE			There are no more rdatasets at the
150  *					node.
151  *
152  *\li	Other results are possible, depending on the DB implementation.
153  */
154 
155 void
156 dns_rdatasetiter_current(dns_rdatasetiter_t *iterator,
157 			 dns_rdataset_t *rdataset);
158 /*%<
159  * Return the current rdataset.
160  *
161  * Requires:
162  *\li	'iterator' is a valid iterator.
163  *
164  *\li	'rdataset' is a valid, disassociated rdataset.
165  *
166  *\li	The rdataset cursor of 'iterator' is at a valid location (i.e. the
167  *	result of last call to a cursor movement command was #ISC_R_SUCCESS).
168  */
169 
170 ISC_LANG_ENDDECLS
171 
172 #endif /* DNS_RDATASETITER_H */
173