1/*
2 * Copyright (C) 2009, 2011, 2012  Internet Systems Consortium, Inc. ("ISC")
3 *
4 * Permission to use, copy, modify, and/or distribute this software for any
5 * purpose with or without fee is hereby granted, provided that the above
6 * copyright notice and this permission notice appear in all copies.
7 *
8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14 * PERFORMANCE OF THIS SOFTWARE.
15 */
16
17/* $Id$ */
18
19#ifndef DNS_RRITERATOR_H
20#define DNS_RRITERATOR_H 1
21
22/*****
23 ***** Module Info
24 *****/
25
26/*! \file dns/rriterator.h
27 * \brief
28 * Functions for "walking" a zone database, visiting each RR or RRset in turn.
29 */
30
31/*****
32 ***** Imports
33 *****/
34
35#include <isc/lang.h>
36#include <isc/magic.h>
37#include <isc/ondestroy.h>
38#include <isc/stdtime.h>
39
40#include <dns/db.h>
41#include <dns/dbiterator.h>
42#include <dns/fixedname.h>
43#include <dns/name.h>
44#include <dns/rdata.h>
45#include <dns/rdataset.h>
46#include <dns/rdatasetiter.h>
47#include <dns/types.h>
48
49ISC_LANG_BEGINDECLS
50
51/*****
52 ***** Types
53 *****/
54
55/*%
56 * A dns_rriterator_t is an iterator that iterates over an entire database,
57 * returning one RR at a time, in some arbitrary order.
58 */
59
60typedef struct dns_rriterator {
61	unsigned int		magic;
62	isc_result_t		result;
63	dns_db_t		*db;
64	dns_dbiterator_t 	*dbit;
65	dns_dbversion_t 	*ver;
66	isc_stdtime_t		now;
67	dns_dbnode_t		*node;
68	dns_fixedname_t		fixedname;
69	dns_rdatasetiter_t 	*rdatasetit;
70	dns_rdataset_t 		rdataset;
71	dns_rdata_t		rdata;
72} dns_rriterator_t;
73
74#define RRITERATOR_MAGIC		ISC_MAGIC('R', 'R', 'I', 't')
75#define VALID_RRITERATOR(m)		ISC_MAGIC_VALID(m, RRITERATOR_MAGIC)
76
77isc_result_t
78dns_rriterator_init(dns_rriterator_t *it, dns_db_t *db,
79		       dns_dbversion_t *ver, isc_stdtime_t now);
80/*%
81 * Initialize an rriterator; sets the cursor to the origin node
82 * of the database.
83 *
84 * Requires:
85 *
86 * \li	'db' is a valid database.
87 *
88 * Returns:
89 *
90 * \li	#ISC_R_SUCCESS
91 * \li	#ISC_R_NOMEMORY
92 */
93
94isc_result_t
95dns_rriterator_first(dns_rriterator_t *it);
96/*%<
97 * Move the rriterator cursor to the first rdata in the database.
98 *
99 * Requires:
100 *\li	'it' is a valid, initialized rriterator
101 *
102 * Returns:
103 *\li	#ISC_R_SUCCESS
104 *\li	#ISC_R_NOMORE			There are no rdata in the set.
105 */
106
107isc_result_t
108dns_rriterator_nextrrset(dns_rriterator_t *it);
109/*%<
110 * Move the rriterator cursor to the next rrset in the database,
111 * skipping over any remaining records that have the same rdatatype
112 * as the current one.
113 *
114 * Requires:
115 *\li	'it' is a valid, initialized rriterator
116 *
117 * Returns:
118 *\li	#ISC_R_SUCCESS
119 *\li	#ISC_R_NOMORE			No more rrsets in the database
120 */
121
122isc_result_t
123dns_rriterator_next(dns_rriterator_t *it);
124/*%<
125 * Move the rriterator cursor to the next rrset in the database,
126 * skipping over any remaining records that have the same rdatatype
127 * as the current one.
128 *
129 * Requires:
130 *\li	'it' is a valid, initialized rriterator
131 *
132 * Returns:
133 *\li	#ISC_R_SUCCESS
134 *\li	#ISC_R_NOMORE			No more records in the database
135 */
136
137void
138dns_rriterator_current(dns_rriterator_t *it, dns_name_t **name,
139			  isc_uint32_t *ttl, dns_rdataset_t **rdataset,
140			  dns_rdata_t **rdata);
141/*%<
142 * Make '*name' refer to the current name.  If 'rdataset' is not NULL,
143 * make '*rdataset' refer to the current * rdataset.  If '*rdata' is not
144 * NULL, make '*rdata' refer to the current record.
145 *
146 * Requires:
147 *\li	'*name' is a valid name object
148 *\li	'rdataset' is NULL or '*rdataset' is NULL
149 *\li	'rdata' is NULL or '*rdata' is NULL
150 *
151 * Ensures:
152 *\li	'rdata' refers to the rdata at the rdata cursor location of
153 *\li	'rdataset'.
154 */
155
156void
157dns_rriterator_pause(dns_rriterator_t *it);
158/*%<
159 * Pause rriterator.  Frees any locks held by the database iterator.
160 * Callers should use this routine any time they are not going to
161 * execute another rriterator method in the immediate future.
162 *
163 * Requires:
164 *\li	'it' is a valid iterator.
165 *
166 * Ensures:
167 *\li	Any database locks being held for efficiency of iterator access are
168 *	released.
169 */
170
171void
172dns_rriterator_destroy(dns_rriterator_t *it);
173/*%<
174 * Shut down and free resources in rriterator 'it'.
175 *
176 * Requires:
177 *
178 *\li	'it' is a valid iterator.
179 *
180 * Ensures:
181 *
182 *\li	All resources used by the rriterator are freed.
183 */
184
185ISC_LANG_ENDDECLS
186
187#endif /* DNS_RRITERATOR_H */
188