1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * Permission to use, copy, modify, and/or distribute this software for any 5 * purpose with or without fee is hereby granted, provided that the above 6 * copyright notice and this permission notice appear in all copies. 7 * 8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 14 * PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /* $Id: rdataset.h,v 1.15 2022/06/26 09:43:39 florian Exp $ */ 18 19 #ifndef DNS_RDATASET_H 20 #define DNS_RDATASET_H 1 21 22 /***** 23 ***** Module Info 24 *****/ 25 26 /*! \file dns/rdataset.h 27 * \brief 28 * A DNS rdataset is a handle that can be associated with a collection of 29 * rdata all having a common owner name, class, and type. 30 * 31 * The dns_rdataset_t type is like a "virtual class". To actually use 32 * rdatasets, an implementation of the method suite (e.g. "slabbed rdata") is 33 * required. 34 * 35 * XXX <more> XXX 36 * 37 * MP: 38 *\li Clients of this module must impose any required synchronization. 39 * 40 * Reliability: 41 *\li No anticipated impact. 42 * 43 * Resources: 44 *\li TBS 45 * 46 * Security: 47 *\li No anticipated impact. 48 * 49 * Standards: 50 *\li None. 51 */ 52 53 #include <dns/types.h> 54 55 typedef enum { 56 dns_rdatasetadditional_fromauth, 57 dns_rdatasetadditional_fromcache, 58 dns_rdatasetadditional_fromglue 59 } dns_rdatasetadditional_t; 60 61 typedef struct dns_rdatasetmethods { 62 void (*disassociate)(dns_rdataset_t *rdataset); 63 isc_result_t (*first)(dns_rdataset_t *rdataset); 64 isc_result_t (*next)(dns_rdataset_t *rdataset); 65 void (*current)(dns_rdataset_t *rdataset, 66 dns_rdata_t *rdata); 67 void (*clone)(dns_rdataset_t *source, 68 dns_rdataset_t *target); 69 unsigned int (*count)(dns_rdataset_t *rdataset); 70 } dns_rdatasetmethods_t; 71 72 /*% 73 * Direct use of this structure by clients is strongly discouraged, except 74 * for the 'link' field which may be used however the client wishes. The 75 * 'private', 'current', and 'index' fields MUST NOT be changed by clients. 76 * rdataset implementations may change any of the fields. 77 */ 78 struct dns_rdataset { 79 dns_rdatasetmethods_t * methods; 80 ISC_LINK(dns_rdataset_t) link; 81 /* 82 * XXX do we need these, or should they be retrieved by methods? 83 * Leaning towards the latter, since they are not frequently required 84 * once you have the rdataset. 85 */ 86 dns_rdataclass_t rdclass; 87 dns_rdatatype_t type; 88 dns_ttl_t ttl; 89 dns_rdatatype_t covers; 90 /* 91 * attributes 92 */ 93 unsigned int attributes; 94 /*% 95 * the counter provides the starting point in the "cyclic" order. 96 * The value UINT32_MAX has a special meaning of "picking up a 97 * random value." in order to take care of databases that do not 98 * increment the counter. 99 */ 100 uint32_t count; 101 /*@{*/ 102 /*% 103 * These are for use by the rdataset implementation, and MUST NOT 104 * be changed by clients. 105 */ 106 void * private1; 107 void * private2; 108 /*@}*/ 109 110 }; 111 112 /*! 113 * \def DNS_RDATASETATTR_RENDERED 114 * Used by message.c to indicate that the rdataset was rendered. 115 */ 116 117 #define DNS_RDATASETATTR_QUESTION 0x00000001 118 #define DNS_RDATASETATTR_RENDERED 0x00000002 /*%< Used by message.c */ 119 120 void 121 dns_rdataset_init(dns_rdataset_t *rdataset); 122 /*%< 123 * Make 'rdataset' a valid, disassociated rdataset. 124 * 125 * Requires: 126 *\li 'rdataset' is not NULL. 127 * 128 * Ensures: 129 *\li 'rdataset' is a valid, disassociated rdataset. 130 */ 131 132 void 133 dns_rdataset_disassociate(dns_rdataset_t *rdataset); 134 /*%< 135 * Disassociate 'rdataset' from its rdata, allowing it to be reused. 136 * 137 * Notes: 138 *\li The client must ensure it has no references to rdata in the rdataset 139 * before disassociating. 140 * 141 * Requires: 142 *\li 'rdataset' is a valid, associated rdataset. 143 * 144 * Ensures: 145 *\li 'rdataset' is a valid, disassociated rdataset. 146 */ 147 148 int 149 dns_rdataset_isassociated(dns_rdataset_t *rdataset); 150 /*%< 151 * Is 'rdataset' associated? 152 * 153 * Requires: 154 *\li 'rdataset' is a valid rdataset. 155 * 156 * Returns: 157 *\li #1 'rdataset' is associated. 158 *\li #0 'rdataset' is not associated. 159 */ 160 161 void 162 dns_rdataset_makequestion(dns_rdataset_t *rdataset, dns_rdataclass_t rdclass, 163 dns_rdatatype_t type); 164 /*%< 165 * Make 'rdataset' a valid, associated, question rdataset, with a 166 * question class of 'rdclass' and type 'type'. 167 * 168 * Notes: 169 *\li Question rdatasets have a class and type, but no rdata. 170 * 171 * Requires: 172 *\li 'rdataset' is a valid, disassociated rdataset. 173 * 174 * Ensures: 175 *\li 'rdataset' is a valid, associated, question rdataset. 176 */ 177 178 isc_result_t 179 dns_rdataset_first(dns_rdataset_t *rdataset); 180 /*%< 181 * Move the rdata cursor to the first rdata in the rdataset (if any). 182 * 183 * Requires: 184 *\li 'rdataset' is a valid, associated rdataset. 185 * 186 * Returns: 187 *\li #ISC_R_SUCCESS 188 *\li #ISC_R_NOMORE There are no rdata in the set. 189 */ 190 191 isc_result_t 192 dns_rdataset_next(dns_rdataset_t *rdataset); 193 /*%< 194 * Move the rdata cursor to the next rdata in the rdataset (if any). 195 * 196 * Requires: 197 *\li 'rdataset' is a valid, associated rdataset. 198 * 199 * Returns: 200 *\li #ISC_R_SUCCESS 201 *\li #ISC_R_NOMORE There are no more rdata in the set. 202 */ 203 204 void 205 dns_rdataset_current(dns_rdataset_t *rdataset, dns_rdata_t *rdata); 206 /*%< 207 * Make 'rdata' refer to the current rdata. 208 * 209 * Notes: 210 * 211 *\li The data returned in 'rdata' is valid for the life of the 212 * rdataset; in particular, subsequent changes in the cursor position 213 * do not invalidate 'rdata'. 214 * 215 * Requires: 216 *\li 'rdataset' is a valid, associated rdataset. 217 * 218 *\li The rdata cursor of 'rdataset' is at a valid location (i.e. the 219 * result of last call to a cursor movement command was ISC_R_SUCCESS). 220 * 221 * Ensures: 222 *\li 'rdata' refers to the rdata at the rdata cursor location of 223 *\li 'rdataset'. 224 */ 225 226 isc_result_t 227 dns_rdataset_totext(dns_rdataset_t *rdataset, 228 dns_name_t *owner_name, 229 int omit_final_dot, 230 int question, 231 isc_buffer_t *target); 232 /*%< 233 * Convert 'rdataset' to text format, storing the result in 'target'. 234 * 235 * Notes: 236 *\li The rdata cursor position will be changed. 237 * 238 *\li The 'question' flag should normally be #0. If it is 239 * #1, the TTL and rdata fields are not printed. This is 240 * for use when printing an rdata representing a question section. 241 * 242 *\li This interface is deprecated; use dns_master_rdatasettottext() 243 * and/or dns_master_questiontotext() instead. 244 * 245 * Requires: 246 *\li 'rdataset' is a valid rdataset. 247 * 248 *\li 'rdataset' is not empty. 249 */ 250 251 isc_result_t 252 dns_rdataset_towire(dns_rdataset_t *rdataset, 253 dns_name_t *owner_name, 254 dns_compress_t *cctx, 255 isc_buffer_t *target, 256 unsigned int *countp); 257 /*%< 258 * Convert 'rdataset' to wire format, compressing names as specified 259 * in 'cctx', and storing the result in 'target'. 260 * 261 * Notes: 262 *\li The rdata cursor position will be changed. 263 * 264 *\li The number of RRs added to target will be added to *countp. 265 * 266 * Requires: 267 *\li 'rdataset' is a valid rdataset. 268 * 269 *\li 'rdataset' is not empty. 270 * 271 *\li 'countp' is a valid pointer. 272 * 273 * Ensures: 274 *\li On a return of ISC_R_SUCCESS, 'target' contains a wire format 275 * for the data contained in 'rdataset'. Any error return leaves 276 * the buffer unchanged. 277 * 278 *\li *countp has been incremented by the number of RRs added to 279 * target. 280 * 281 * Returns: 282 *\li #ISC_R_SUCCESS - all ok 283 *\li #ISC_R_NOSPACE - 'target' doesn't have enough room 284 * 285 *\li Any error returned by dns_rdata_towire(), dns_rdataset_next(), 286 * dns_name_towire(). 287 */ 288 289 isc_result_t 290 dns_rdataset_towiresorted(dns_rdataset_t *rdataset, 291 const dns_name_t *owner_name, 292 dns_compress_t *cctx, 293 isc_buffer_t *target, 294 unsigned int *countp); 295 /*%< 296 * Like dns_rdataset_towire(), but sorting the rdatasets according to 297 * the integer value returned by 'order' when called with the rdataset 298 * and 'order_arg' as arguments. 299 * 300 * Requires: 301 *\li All the requirements of dns_rdataset_towire(), and 302 * that order_arg is NULL if and only if order is NULL. 303 */ 304 305 #endif /* DNS_RDATASET_H */ 306