2 * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2001 Internet Software Consortium.
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.
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.
18 /* $Id: rdatasetiter.h,v 1.21 2007/06/19 23:47:17 tbox Exp $ */
20 #ifndef DNS_RDATASETITER_H
21 #define DNS_RDATASETITER_H 1
27 /*! \file dns/rdatasetiter.h
29 * The DNS Rdataset Iterator interface allows iteration of all of the
30 * rdatasets at a node.
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.
36 * It is the client's responsibility to call dns_rdataset_disassociate()
37 * on all rdatasets returned.
42 *\li The iterator itself is not locked. The caller must ensure
45 *\li The iterator methods ensure appropriate database locking.
48 *\li No anticipated impact.
54 *\li No anticipated impact.
65 #include <isc/magic.h>
66 #include <isc/stdtime.h>
68 #include <dns/types.h>
76 typedef 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
;
84 #define DNS_RDATASETITER_MAGIC ISC_MAGIC('D','N','S','i')
85 #define DNS_RDATASETITER_VALID(i) ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC)
88 * This structure is actually just the common prefix of a DNS db
89 * implementation's version of a dns_rdatasetiter_t.
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.
96 struct dns_rdatasetiter
{
99 dns_rdatasetitermethods_t
* methods
;
102 dns_dbversion_t
* version
;
107 dns_rdatasetiter_destroy(dns_rdatasetiter_t
**iteratorp
);
109 * Destroy '*iteratorp'.
113 *\li '*iteratorp' is a valid iterator.
117 *\li All resources used by the iterator are freed.
119 *\li *iteratorp == NULL.
123 dns_rdatasetiter_first(dns_rdatasetiter_t
*iterator
);
125 * Move the rdataset cursor to the first rdataset at the node (if any).
128 *\li 'iterator' is a valid iterator.
132 *\li ISC_R_NOMORE There are no rdatasets at the node.
134 *\li Other results are possible, depending on the DB implementation.
138 dns_rdatasetiter_next(dns_rdatasetiter_t
*iterator
);
140 * Move the rdataset cursor to the next rdataset at the node (if any).
143 *\li 'iterator' is a valid iterator.
147 *\li ISC_R_NOMORE There are no more rdatasets at the
150 *\li Other results are possible, depending on the DB implementation.
154 dns_rdatasetiter_current(dns_rdatasetiter_t
*iterator
,
155 dns_rdataset_t
*rdataset
);
157 * Return the current rdataset.
160 *\li 'iterator' is a valid iterator.
162 *\li 'rdataset' is a valid, disassociated rdataset.
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).
170 #endif /* DNS_RDATASETITER_H */