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 */
171