1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, You can obtain one at http://mozilla.org/MPL/2.0/. 7 * 8 * See the COPYRIGHT file distributed with this work for additional 9 * information regarding copyright ownership. 10 */ 11 12 #ifndef DNS_RDATASETITER_H 13 #define DNS_RDATASETITER_H 1 14 15 /***** 16 ***** Module Info 17 *****/ 18 19 /*! \file dns/rdatasetiter.h 20 * \brief 21 * The DNS Rdataset Iterator interface allows iteration of all of the 22 * rdatasets at a node. 23 * 24 * The dns_rdatasetiter_t type is like a "virtual class". To actually use 25 * it, an implementation of the class is required. This implementation is 26 * supplied by the database. 27 * 28 * It is the client's responsibility to call dns_rdataset_disassociate() 29 * on all rdatasets returned. 30 * 31 * XXX more XXX 32 * 33 * MP: 34 *\li The iterator itself is not locked. The caller must ensure 35 * synchronization. 36 * 37 *\li The iterator methods ensure appropriate database locking. 38 * 39 * Reliability: 40 *\li No anticipated impact. 41 * 42 * Resources: 43 *\li TBS 44 * 45 * Security: 46 *\li No anticipated impact. 47 * 48 * Standards: 49 *\li None. 50 */ 51 52 /***** 53 ***** Imports 54 *****/ 55 56 #include <isc/lang.h> 57 #include <isc/magic.h> 58 #include <isc/stdtime.h> 59 60 #include <dns/types.h> 61 62 ISC_LANG_BEGINDECLS 63 64 /***** 65 ***** Types 66 *****/ 67 68 typedef struct dns_rdatasetitermethods { 69 void (*destroy)(dns_rdatasetiter_t **iteratorp); 70 isc_result_t (*first)(dns_rdatasetiter_t *iterator); 71 isc_result_t (*next)(dns_rdatasetiter_t *iterator); 72 void (*current)(dns_rdatasetiter_t *iterator, dns_rdataset_t *rdataset); 73 } dns_rdatasetitermethods_t; 74 75 #define DNS_RDATASETITER_MAGIC ISC_MAGIC('D', 'N', 'S', 'i') 76 #define DNS_RDATASETITER_VALID(i) ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC) 77 78 /*% 79 * This structure is actually just the common prefix of a DNS db 80 * implementation's version of a dns_rdatasetiter_t. 81 * \brief 82 * Direct use of this structure by clients is forbidden. DB implementations 83 * may change the structure. 'magic' must be #DNS_RDATASETITER_MAGIC for 84 * any of the dns_rdatasetiter routines to work. DB implementations must 85 * maintain all DB rdataset iterator invariants. 86 */ 87 struct dns_rdatasetiter { 88 /* Unlocked. */ 89 unsigned int magic; 90 dns_rdatasetitermethods_t *methods; 91 dns_db_t * db; 92 dns_dbnode_t * node; 93 dns_dbversion_t * version; 94 isc_stdtime_t now; 95 }; 96 97 void 98 dns_rdatasetiter_destroy(dns_rdatasetiter_t **iteratorp); 99 /*%< 100 * Destroy '*iteratorp'. 101 * 102 * Requires: 103 * 104 *\li '*iteratorp' is a valid iterator. 105 * 106 * Ensures: 107 * 108 *\li All resources used by the iterator are freed. 109 * 110 *\li *iteratorp == NULL. 111 */ 112 113 isc_result_t 114 dns_rdatasetiter_first(dns_rdatasetiter_t *iterator); 115 /*%< 116 * Move the rdataset cursor to the first rdataset at the node (if any). 117 * 118 * Requires: 119 *\li 'iterator' is a valid iterator. 120 * 121 * Returns: 122 *\li ISC_R_SUCCESS 123 *\li ISC_R_NOMORE There are no rdatasets at the node. 124 * 125 *\li Other results are possible, depending on the DB implementation. 126 */ 127 128 isc_result_t 129 dns_rdatasetiter_next(dns_rdatasetiter_t *iterator); 130 /*%< 131 * Move the rdataset cursor to the next rdataset at the node (if any). 132 * 133 * Requires: 134 *\li 'iterator' is a valid iterator. 135 * 136 * Returns: 137 *\li ISC_R_SUCCESS 138 *\li ISC_R_NOMORE There are no more rdatasets at the 139 * node. 140 * 141 *\li Other results are possible, depending on the DB implementation. 142 */ 143 144 void 145 dns_rdatasetiter_current(dns_rdatasetiter_t *iterator, 146 dns_rdataset_t * rdataset); 147 /*%< 148 * Return the current rdataset. 149 * 150 * Requires: 151 *\li 'iterator' is a valid iterator. 152 * 153 *\li 'rdataset' is a valid, disassociated rdataset. 154 * 155 *\li The rdataset cursor of 'iterator' is at a valid location (i.e. the 156 * result of last call to a cursor movement command was #ISC_R_SUCCESS). 157 */ 158 159 ISC_LANG_ENDDECLS 160 161 #endif /* DNS_RDATASETITER_H */ 162