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