PageRenderTime 20ms CodeModel.GetById 16ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/bind9/lib/dns/include/dns/rdatasetiter.h

https://bitbucket.org/freebsd/freebsd-head/
C++ Header | 170 lines | 35 code | 18 blank | 117 comment | 0 complexity | 21d848375dd6d31babfce623f5d45763 MD5 | raw file
  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 */