rdataset.h revision 170222
1/* 2 * Copyright (C) 2004-2006 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 1999-2003 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 * PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18/* $Id: rdataset.h,v 1.51.18.7 2006/03/03 00:56:53 marka Exp $ */ 19 20#ifndef DNS_RDATASET_H 21#define DNS_RDATASET_H 1 22 23/***** 24 ***** Module Info 25 *****/ 26 27/*! \file 28 * \brief 29 * A DNS rdataset is a handle that can be associated with a collection of 30 * rdata all having a common owner name, class, and type. 31 * 32 * The dns_rdataset_t type is like a "virtual class". To actually use 33 * rdatasets, an implementation of the method suite (e.g. "slabbed rdata") is 34 * required. 35 * 36 * XXX <more> XXX 37 * 38 * MP: 39 *\li Clients of this module must impose any required synchronization. 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#include <isc/lang.h> 55#include <isc/magic.h> 56#include <isc/stdtime.h> 57 58#include <dns/types.h> 59 60ISC_LANG_BEGINDECLS 61 62typedef enum { 63 dns_rdatasetadditional_fromauth, 64 dns_rdatasetadditional_fromcache, 65 dns_rdatasetadditional_fromglue 66} dns_rdatasetadditional_t; 67 68typedef struct dns_rdatasetmethods { 69 void (*disassociate)(dns_rdataset_t *rdataset); 70 isc_result_t (*first)(dns_rdataset_t *rdataset); 71 isc_result_t (*next)(dns_rdataset_t *rdataset); 72 void (*current)(dns_rdataset_t *rdataset, 73 dns_rdata_t *rdata); 74 void (*clone)(dns_rdataset_t *source, 75 dns_rdataset_t *target); 76 unsigned int (*count)(dns_rdataset_t *rdataset); 77 isc_result_t (*addnoqname)(dns_rdataset_t *rdataset, 78 dns_name_t *name); 79 isc_result_t (*getnoqname)(dns_rdataset_t *rdataset, 80 dns_name_t *name, 81 dns_rdataset_t *nsec, 82 dns_rdataset_t *nsecsig); 83 isc_result_t (*getadditional)(dns_rdataset_t *rdataset, 84 dns_rdatasetadditional_t type, 85 dns_rdatatype_t qtype, 86 dns_acache_t *acache, 87 dns_zone_t **zonep, 88 dns_db_t **dbp, 89 dns_dbversion_t **versionp, 90 dns_dbnode_t **nodep, 91 dns_name_t *fname, 92 dns_message_t *msg, 93 isc_stdtime_t now); 94 isc_result_t (*setadditional)(dns_rdataset_t *rdataset, 95 dns_rdatasetadditional_t type, 96 dns_rdatatype_t qtype, 97 dns_acache_t *acache, 98 dns_zone_t *zone, 99 dns_db_t *db, 100 dns_dbversion_t *version, 101 dns_dbnode_t *node, 102 dns_name_t *fname); 103 isc_result_t (*putadditional)(dns_acache_t *acache, 104 dns_rdataset_t *rdataset, 105 dns_rdatasetadditional_t type, 106 dns_rdatatype_t qtype); 107} dns_rdatasetmethods_t; 108 109#define DNS_RDATASET_MAGIC ISC_MAGIC('D','N','S','R') 110#define DNS_RDATASET_VALID(set) ISC_MAGIC_VALID(set, DNS_RDATASET_MAGIC) 111 112/*% 113 * Direct use of this structure by clients is strongly discouraged, except 114 * for the 'link' field which may be used however the client wishes. The 115 * 'private', 'current', and 'index' fields MUST NOT be changed by clients. 116 * rdataset implementations may change any of the fields. 117 */ 118struct dns_rdataset { 119 unsigned int magic; /* XXX ? */ 120 dns_rdatasetmethods_t * methods; 121 ISC_LINK(dns_rdataset_t) link; 122 /* 123 * XXX do we need these, or should they be retrieved by methods? 124 * Leaning towards the latter, since they are not frequently required 125 * once you have the rdataset. 126 */ 127 dns_rdataclass_t rdclass; 128 dns_rdatatype_t type; 129 dns_ttl_t ttl; 130 dns_trust_t trust; 131 dns_rdatatype_t covers; 132 /* 133 * attributes 134 */ 135 unsigned int attributes; 136 /*% 137 * the counter provides the starting point in the "cyclic" order. 138 * The value ISC_UINT32_MAX has a special meaning of "picking up a 139 * random value." in order to take care of databases that do not 140 * increment the counter. 141 */ 142 isc_uint32_t count; 143 /*@{*/ 144 /*% 145 * These are for use by the rdataset implementation, and MUST NOT 146 * be changed by clients. 147 */ 148 void * private1; 149 void * private2; 150 void * private3; 151 unsigned int privateuint4; 152 void * private5; 153 void * private6; 154 /*@}*/ 155}; 156 157/*! 158 * \def DNS_RDATASETATTR_RENDERED 159 * Used by message.c to indicate that the rdataset was rendered. 160 * 161 * \def DNS_RDATASETATTR_TTLADJUSTED 162 * Used by message.c to indicate that the rdataset's rdata had differing 163 * TTL values, and the rdataset->ttl holds the smallest. 164 * 165 * \def DNS_RDATASETATTR_LOADORDER 166 * Output the RRset in load order. 167 */ 168 169#define DNS_RDATASETATTR_QUESTION 0x00000001 170#define DNS_RDATASETATTR_RENDERED 0x00000002 /*%< Used by message.c */ 171#define DNS_RDATASETATTR_ANSWERED 0x00000004 /*%< Used by server. */ 172#define DNS_RDATASETATTR_CACHE 0x00000008 /*%< Used by resolver. */ 173#define DNS_RDATASETATTR_ANSWER 0x00000010 /*%< Used by resolver. */ 174#define DNS_RDATASETATTR_ANSWERSIG 0x00000020 /*%< Used by resolver. */ 175#define DNS_RDATASETATTR_EXTERNAL 0x00000040 /*%< Used by resolver. */ 176#define DNS_RDATASETATTR_NCACHE 0x00000080 /*%< Used by resolver. */ 177#define DNS_RDATASETATTR_CHAINING 0x00000100 /*%< Used by resolver. */ 178#define DNS_RDATASETATTR_TTLADJUSTED 0x00000200 /*%< Used by message.c */ 179#define DNS_RDATASETATTR_FIXEDORDER 0x00000400 180#define DNS_RDATASETATTR_RANDOMIZE 0x00000800 181#define DNS_RDATASETATTR_CHASE 0x00001000 /*%< Used by resolver. */ 182#define DNS_RDATASETATTR_NXDOMAIN 0x00002000 183#define DNS_RDATASETATTR_NOQNAME 0x00004000 184#define DNS_RDATASETATTR_CHECKNAMES 0x00008000 /*%< Used by resolver. */ 185#define DNS_RDATASETATTR_REQUIREDGLUE 0x00010000 186#define DNS_RDATASETATTR_LOADORDER 0x00020000 187 188/*% 189 * _OMITDNSSEC: 190 * Omit DNSSEC records when rendering ncache records. 191 */ 192#define DNS_RDATASETTOWIRE_OMITDNSSEC 0x0001 193 194void 195dns_rdataset_init(dns_rdataset_t *rdataset); 196/*%< 197 * Make 'rdataset' a valid, disassociated rdataset. 198 * 199 * Requires: 200 *\li 'rdataset' is not NULL. 201 * 202 * Ensures: 203 *\li 'rdataset' is a valid, disassociated rdataset. 204 */ 205 206void 207dns_rdataset_invalidate(dns_rdataset_t *rdataset); 208/*%< 209 * Invalidate 'rdataset'. 210 * 211 * Requires: 212 *\li 'rdataset' is a valid, disassociated rdataset. 213 * 214 * Ensures: 215 *\li If assertion checking is enabled, future attempts to use 'rdataset' 216 * without initializing it will cause an assertion failure. 217 */ 218 219void 220dns_rdataset_disassociate(dns_rdataset_t *rdataset); 221/*%< 222 * Disassociate 'rdataset' from its rdata, allowing it to be reused. 223 * 224 * Notes: 225 *\li The client must ensure it has no references to rdata in the rdataset 226 * before disassociating. 227 * 228 * Requires: 229 *\li 'rdataset' is a valid, associated rdataset. 230 * 231 * Ensures: 232 *\li 'rdataset' is a valid, disassociated rdataset. 233 */ 234 235isc_boolean_t 236dns_rdataset_isassociated(dns_rdataset_t *rdataset); 237/*%< 238 * Is 'rdataset' associated? 239 * 240 * Requires: 241 *\li 'rdataset' is a valid rdataset. 242 * 243 * Returns: 244 *\li #ISC_TRUE 'rdataset' is associated. 245 *\li #ISC_FALSE 'rdataset' is not associated. 246 */ 247 248void 249dns_rdataset_makequestion(dns_rdataset_t *rdataset, dns_rdataclass_t rdclass, 250 dns_rdatatype_t type); 251/*%< 252 * Make 'rdataset' a valid, associated, question rdataset, with a 253 * question class of 'rdclass' and type 'type'. 254 * 255 * Notes: 256 *\li Question rdatasets have a class and type, but no rdata. 257 * 258 * Requires: 259 *\li 'rdataset' is a valid, disassociated rdataset. 260 * 261 * Ensures: 262 *\li 'rdataset' is a valid, associated, question rdataset. 263 */ 264 265void 266dns_rdataset_clone(dns_rdataset_t *source, dns_rdataset_t *target); 267/*%< 268 * Make 'target' refer to the same rdataset as 'source'. 269 * 270 * Requires: 271 *\li 'source' is a valid, associated rdataset. 272 * 273 *\li 'target' is a valid, dissociated rdataset. 274 * 275 * Ensures: 276 *\li 'target' references the same rdataset as 'source'. 277 */ 278 279unsigned int 280dns_rdataset_count(dns_rdataset_t *rdataset); 281/*%< 282 * Return the number of records in 'rdataset'. 283 * 284 * Requires: 285 *\li 'rdataset' is a valid, associated rdataset. 286 * 287 * Returns: 288 *\li The number of records in 'rdataset'. 289 */ 290 291isc_result_t 292dns_rdataset_first(dns_rdataset_t *rdataset); 293/*%< 294 * Move the rdata cursor to the first rdata in the rdataset (if any). 295 * 296 * Requires: 297 *\li 'rdataset' is a valid, associated rdataset. 298 * 299 * Returns: 300 *\li #ISC_R_SUCCESS 301 *\li #ISC_R_NOMORE There are no rdata in the set. 302 */ 303 304isc_result_t 305dns_rdataset_next(dns_rdataset_t *rdataset); 306/*%< 307 * Move the rdata cursor to the next rdata in the rdataset (if any). 308 * 309 * Requires: 310 *\li 'rdataset' is a valid, associated rdataset. 311 * 312 * Returns: 313 *\li #ISC_R_SUCCESS 314 *\li #ISC_R_NOMORE There are no more rdata in the set. 315 */ 316 317void 318dns_rdataset_current(dns_rdataset_t *rdataset, dns_rdata_t *rdata); 319/*%< 320 * Make 'rdata' refer to the current rdata. 321 * 322 * Notes: 323 * 324 *\li The data returned in 'rdata' is valid for the life of the 325 * rdataset; in particular, subsequent changes in the cursor position 326 * do not invalidate 'rdata'. 327 * 328 * Requires: 329 *\li 'rdataset' is a valid, associated rdataset. 330 * 331 *\li The rdata cursor of 'rdataset' is at a valid location (i.e. the 332 * result of last call to a cursor movement command was ISC_R_SUCCESS). 333 * 334 * Ensures: 335 *\li 'rdata' refers to the rdata at the rdata cursor location of 336 *\li 'rdataset'. 337 */ 338 339isc_result_t 340dns_rdataset_totext(dns_rdataset_t *rdataset, 341 dns_name_t *owner_name, 342 isc_boolean_t omit_final_dot, 343 isc_boolean_t question, 344 isc_buffer_t *target); 345/*%< 346 * Convert 'rdataset' to text format, storing the result in 'target'. 347 * 348 * Notes: 349 *\li The rdata cursor position will be changed. 350 * 351 *\li The 'question' flag should normally be #ISC_FALSE. If it is 352 * #ISC_TRUE, the TTL and rdata fields are not printed. This is 353 * for use when printing an rdata representing a question section. 354 * 355 *\li This interface is deprecated; use dns_master_rdatasettottext() 356 * and/or dns_master_questiontotext() instead. 357 * 358 * Requires: 359 *\li 'rdataset' is a valid rdataset. 360 * 361 *\li 'rdataset' is not empty. 362 */ 363 364isc_result_t 365dns_rdataset_towire(dns_rdataset_t *rdataset, 366 dns_name_t *owner_name, 367 dns_compress_t *cctx, 368 isc_buffer_t *target, 369 unsigned int options, 370 unsigned int *countp); 371/*%< 372 * Convert 'rdataset' to wire format, compressing names as specified 373 * in 'cctx', and storing the result in 'target'. 374 * 375 * Notes: 376 *\li The rdata cursor position will be changed. 377 * 378 *\li The number of RRs added to target will be added to *countp. 379 * 380 * Requires: 381 *\li 'rdataset' is a valid rdataset. 382 * 383 *\li 'rdataset' is not empty. 384 * 385 *\li 'countp' is a valid pointer. 386 * 387 * Ensures: 388 *\li On a return of ISC_R_SUCCESS, 'target' contains a wire format 389 * for the data contained in 'rdataset'. Any error return leaves 390 * the buffer unchanged. 391 * 392 *\li *countp has been incremented by the number of RRs added to 393 * target. 394 * 395 * Returns: 396 *\li #ISC_R_SUCCESS - all ok 397 *\li #ISC_R_NOSPACE - 'target' doesn't have enough room 398 * 399 *\li Any error returned by dns_rdata_towire(), dns_rdataset_next(), 400 * dns_name_towire(). 401 */ 402 403isc_result_t 404dns_rdataset_towiresorted(dns_rdataset_t *rdataset, 405 const dns_name_t *owner_name, 406 dns_compress_t *cctx, 407 isc_buffer_t *target, 408 dns_rdatasetorderfunc_t order, 409 const void *order_arg, 410 unsigned int options, 411 unsigned int *countp); 412/*%< 413 * Like dns_rdataset_towire(), but sorting the rdatasets according to 414 * the integer value returned by 'order' when called witih the rdataset 415 * and 'order_arg' as arguments. 416 * 417 * Requires: 418 *\li All the requirements of dns_rdataset_towire(), and 419 * that order_arg is NULL if and only if order is NULL. 420 */ 421 422isc_result_t 423dns_rdataset_towirepartial(dns_rdataset_t *rdataset, 424 const dns_name_t *owner_name, 425 dns_compress_t *cctx, 426 isc_buffer_t *target, 427 dns_rdatasetorderfunc_t order, 428 const void *order_arg, 429 unsigned int options, 430 unsigned int *countp, 431 void **state); 432/*%< 433 * Like dns_rdataset_towiresorted() except that a partial rdataset 434 * may be written. 435 * 436 * Requires: 437 *\li All the requirements of dns_rdataset_towiresorted(). 438 * If 'state' is non NULL then the current position in the 439 * rdataset will be remembered if the rdataset in not 440 * completely written and should be passed on on subsequent 441 * calls (NOT CURRENTLY IMPLEMENTED). 442 * 443 * Returns: 444 *\li #ISC_R_SUCCESS if all of the records were written. 445 *\li #ISC_R_NOSPACE if unable to fit in all of the records. *countp 446 * will be updated to reflect the number of records 447 * written. 448 */ 449 450isc_result_t 451dns_rdataset_additionaldata(dns_rdataset_t *rdataset, 452 dns_additionaldatafunc_t add, void *arg); 453/*%< 454 * For each rdata in rdataset, call 'add' for each name and type in the 455 * rdata which is subject to additional section processing. 456 * 457 * Requires: 458 * 459 *\li 'rdataset' is a valid, non-question rdataset. 460 * 461 *\li 'add' is a valid dns_additionaldatafunc_t 462 * 463 * Ensures: 464 * 465 *\li If successful, dns_rdata_additionaldata() will have been called for 466 * each rdata in 'rdataset'. 467 * 468 *\li If a call to dns_rdata_additionaldata() is not successful, the 469 * result returned will be the result of dns_rdataset_additionaldata(). 470 * 471 * Returns: 472 * 473 *\li #ISC_R_SUCCESS 474 * 475 *\li Any error that dns_rdata_additionaldata() can return. 476 */ 477 478isc_result_t 479dns_rdataset_getnoqname(dns_rdataset_t *rdataset, dns_name_t *name, 480 dns_rdataset_t *nsec, dns_rdataset_t *nsecsig); 481/*%< 482 * Return the noqname proof for this record. 483 * 484 * Requires: 485 *\li 'rdataset' to be valid and #DNS_RDATASETATTR_NOQNAME to be set. 486 *\li 'name' to be valid. 487 *\li 'nsec' and 'nsecsig' to be valid and not associated. 488 */ 489 490isc_result_t 491dns_rdataset_addnoqname(dns_rdataset_t *rdataset, dns_name_t *name); 492/*%< 493 * Associate a noqname proof with this record. 494 * Sets #DNS_RDATASETATTR_NOQNAME if successful. 495 * Adjusts the 'rdataset->ttl' to minimum of the 'rdataset->ttl' and 496 * the 'nsec' and 'rrsig(nsec)' ttl. 497 * 498 * Requires: 499 *\li 'rdataset' to be valid and #DNS_RDATASETATTR_NOQNAME to be set. 500 *\li 'name' to be valid and have NSEC and RRSIG(NSEC) rdatasets. 501 */ 502 503isc_result_t 504dns_rdataset_getadditional(dns_rdataset_t *rdataset, 505 dns_rdatasetadditional_t type, 506 dns_rdatatype_t qtype, 507 dns_acache_t *acache, 508 dns_zone_t **zonep, 509 dns_db_t **dbp, 510 dns_dbversion_t **versionp, 511 dns_dbnode_t **nodep, 512 dns_name_t *fname, 513 dns_message_t *msg, 514 isc_stdtime_t now); 515/*%< 516 * Get cached additional information from the DB node for a particular 517 * 'rdataset.' 'type' is one of dns_rdatasetadditional_fromauth, 518 * dns_rdatasetadditional_fromcache, and dns_rdatasetadditional_fromglue, 519 * which specifies the origin of the information. 'qtype' is intended to 520 * be used for specifying a particular rdata type in the cached information. 521 * 522 * Requires: 523 * \li 'rdataset' is a valid rdataset. 524 * \li 'acache' can be NULL, in which case this function will simply return 525 * ISC_R_FAILURE. 526 * \li For the other pointers, see dns_acache_getentry(). 527 * 528 * Ensures: 529 * \li See dns_acache_getentry(). 530 * 531 * Returns: 532 * \li #ISC_R_SUCCESS 533 * \li #ISC_R_FAILURE - additional information caching is not supported. 534 * \li #ISC_R_NOTFOUND - the corresponding DB node has not cached additional 535 * information for 'rdataset.' 536 * \li Any error that dns_acache_getentry() can return. 537 */ 538 539isc_result_t 540dns_rdataset_setadditional(dns_rdataset_t *rdataset, 541 dns_rdatasetadditional_t type, 542 dns_rdatatype_t qtype, 543 dns_acache_t *acache, 544 dns_zone_t *zone, 545 dns_db_t *db, 546 dns_dbversion_t *version, 547 dns_dbnode_t *node, 548 dns_name_t *fname); 549/*%< 550 * Set cached additional information to the DB node for a particular 551 * 'rdataset.' See dns_rdataset_getadditional for the semantics of 'type' 552 * and 'qtype'. 553 * 554 * Requires: 555 * \li 'rdataset' is a valid rdataset. 556 * \li 'acache' can be NULL, in which case this function will simply return 557 * ISC_R_FAILURE. 558 * \li For the other pointers, see dns_acache_setentry(). 559 * 560 * Ensures: 561 * \li See dns_acache_setentry(). 562 * 563 * Returns: 564 * \li #ISC_R_SUCCESS 565 * \li #ISC_R_FAILURE - additional information caching is not supported. 566 * \li #ISC_R_NOMEMORY 567 * \li Any error that dns_acache_setentry() can return. 568 */ 569 570isc_result_t 571dns_rdataset_putadditional(dns_acache_t *acache, 572 dns_rdataset_t *rdataset, 573 dns_rdatasetadditional_t type, 574 dns_rdatatype_t qtype); 575/*%< 576 * Discard cached additional information stored in the DB node for a particular 577 * 'rdataset.' See dns_rdataset_getadditional for the semantics of 'type' 578 * and 'qtype'. 579 * 580 * Requires: 581 * \li 'rdataset' is a valid rdataset. 582 * \li 'acache' can be NULL, in which case this function will simply return 583 * ISC_R_FAILURE. 584 * 585 * Ensures: 586 * \li See dns_acache_cancelentry(). 587 * 588 * Returns: 589 * \li #ISC_R_SUCCESS 590 * \li #ISC_R_FAILURE - additional information caching is not supported. 591 * \li #ISC_R_NOTFOUND - the corresponding DB node has not cached additional 592 * information for 'rdataset.' 593 */ 594 595ISC_LANG_ENDDECLS 596 597#endif /* DNS_RDATASET_H */ 598