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