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