contrib/bind9/lib/dns/include/dns/rdataset.h

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