1 /* $NetBSD: rdatasetiter.h,v 1.4 2014/12/10 04:37:58 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 1999-2001 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id: rdatasetiter.h,v 1.21 2007/06/19 23:47:17 tbox Exp */ 21 22 #ifndef DNS_RDATASETITER_H 23 #define DNS_RDATASETITER_H 1 24 25 /***** 26 ***** Module Info 27 *****/ 28 29 /*! \file dns/rdatasetiter.h 30 * \brief 31 * The DNS Rdataset Iterator interface allows iteration of all of the 32 * rdatasets at a node. 33 * 34 * The dns_rdatasetiter_t type is like a "virtual class". To actually use 35 * it, an implementation of the class is required. This implementation is 36 * supplied by the database. 37 * 38 * It is the client's responsibility to call dns_rdataset_disassociate() 39 * on all rdatasets returned. 40 * 41 * XXX more XXX 42 * 43 * MP: 44 *\li The iterator itself is not locked. The caller must ensure 45 * synchronization. 46 * 47 *\li The iterator methods ensure appropriate database locking. 48 * 49 * Reliability: 50 *\li No anticipated impact. 51 * 52 * Resources: 53 *\li TBS 54 * 55 * Security: 56 *\li No anticipated impact. 57 * 58 * Standards: 59 *\li None. 60 */ 61 62 /***** 63 ***** Imports 64 *****/ 65 66 #include <isc/lang.h> 67 #include <isc/magic.h> 68 #include <isc/stdtime.h> 69 70 #include <dns/types.h> 71 72 ISC_LANG_BEGINDECLS 73 74 /***** 75 ***** Types 76 *****/ 77 78 typedef struct dns_rdatasetitermethods { 79 void (*destroy)(dns_rdatasetiter_t **iteratorp); 80 isc_result_t (*first)(dns_rdatasetiter_t *iterator); 81 isc_result_t (*next)(dns_rdatasetiter_t *iterator); 82 void (*current)(dns_rdatasetiter_t *iterator, 83 dns_rdataset_t *rdataset); 84 } dns_rdatasetitermethods_t; 85 86 #define DNS_RDATASETITER_MAGIC ISC_MAGIC('D','N','S','i') 87 #define DNS_RDATASETITER_VALID(i) ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC) 88 89 /*% 90 * This structure is actually just the common prefix of a DNS db 91 * implementation's version of a dns_rdatasetiter_t. 92 * \brief 93 * Direct use of this structure by clients is forbidden. DB implementations 94 * may change the structure. 'magic' must be #DNS_RDATASETITER_MAGIC for 95 * any of the dns_rdatasetiter routines to work. DB implementations must 96 * maintain all DB rdataset iterator invariants. 97 */ 98 struct dns_rdatasetiter { 99 /* Unlocked. */ 100 unsigned int magic; 101 dns_rdatasetitermethods_t * methods; 102 dns_db_t * db; 103 dns_dbnode_t * node; 104 dns_dbversion_t * version; 105 isc_stdtime_t now; 106 }; 107 108 void 109 dns_rdatasetiter_destroy(dns_rdatasetiter_t **iteratorp); 110 /*%< 111 * Destroy '*iteratorp'. 112 * 113 * Requires: 114 * 115 *\li '*iteratorp' is a valid iterator. 116 * 117 * Ensures: 118 * 119 *\li All resources used by the iterator are freed. 120 * 121 *\li *iteratorp == NULL. 122 */ 123 124 isc_result_t 125 dns_rdatasetiter_first(dns_rdatasetiter_t *iterator); 126 /*%< 127 * Move the rdataset cursor to the first rdataset at the node (if any). 128 * 129 * Requires: 130 *\li 'iterator' is a valid iterator. 131 * 132 * Returns: 133 *\li ISC_R_SUCCESS 134 *\li ISC_R_NOMORE There are no rdatasets at the node. 135 * 136 *\li Other results are possible, depending on the DB implementation. 137 */ 138 139 isc_result_t 140 dns_rdatasetiter_next(dns_rdatasetiter_t *iterator); 141 /*%< 142 * Move the rdataset cursor to the next rdataset at the node (if any). 143 * 144 * Requires: 145 *\li 'iterator' is a valid iterator. 146 * 147 * Returns: 148 *\li ISC_R_SUCCESS 149 *\li ISC_R_NOMORE There are no more rdatasets at the 150 * node. 151 * 152 *\li Other results are possible, depending on the DB implementation. 153 */ 154 155 void 156 dns_rdatasetiter_current(dns_rdatasetiter_t *iterator, 157 dns_rdataset_t *rdataset); 158 /*%< 159 * Return the current rdataset. 160 * 161 * Requires: 162 *\li 'iterator' is a valid iterator. 163 * 164 *\li 'rdataset' is a valid, disassociated rdataset. 165 * 166 *\li The rdataset cursor of 'iterator' is at a valid location (i.e. the 167 * result of last call to a cursor movement command was #ISC_R_SUCCESS). 168 */ 169 170 ISC_LANG_ENDDECLS 171 172 #endif /* DNS_RDATASETITER_H */ 173