contrib/bind-9.3/lib/dns/include/dns/rdataset.h

   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.41.2.5.2.10 2006/03/02 00:37:20 marka Exp $ */
  19
  20 #ifndef DNS_RDATASET_H
  21 #define DNS_RDATASET_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * DNS Rdataset
  29  *
  30  * A DNS rdataset is a handle that can be associated with a collection of
  31  * rdata all having a common owner name, class, and type.
  32  *
  33  * The dns_rdataset_t type is like a "virtual class".  To actually use
  34  * rdatasets, an implementation of the method suite (e.g. "slabbed rdata") is
  35  * required.
  36  *
  37  * XXX <more> XXX
  38  *
  39  * MP:
  40  *      Clients of this module must impose any required synchronization.
  41  *
  42  * Reliability:
  43  *      No anticipated impact.
  44  *
  45  * Resources:
  46  *      <TBS>
  47  *
  48  * Security:
  49  *      No anticipated impact.
  50  *
  51  * Standards:
  52  *      None.
  53  */
  54
  55 #include <isc/lang.h>
  56 #include <isc/magic.h>
  57
  58 #include <dns/types.h>
  59
  60 ISC_LANG_BEGINDECLS
  61
  62 typedef struct dns_rdatasetmethods {
  63         void                    (*disassociate)(dns_rdataset_t *rdataset);
  64         isc_result_t            (*first)(dns_rdataset_t *rdataset);
  65         isc_result_t            (*next)(dns_rdataset_t *rdataset);
  66         void                    (*current)(dns_rdataset_t *rdataset,
  67                                            dns_rdata_t *rdata);
  68         void                    (*clone)(dns_rdataset_t *source,
  69                                          dns_rdataset_t *target);
  70         unsigned int            (*count)(dns_rdataset_t *rdataset);
  71         isc_result_t            (*addnoqname)(dns_rdataset_t *rdataset,
  72                                               dns_name_t *name);
  73         isc_result_t            (*getnoqname)(dns_rdataset_t *rdataset,
  74                                               dns_name_t *name,
  75                                               dns_rdataset_t *nsec,
  76                                               dns_rdataset_t *nsecsig);
  77 } dns_rdatasetmethods_t;
  78
  79 #define DNS_RDATASET_MAGIC             ISC_MAGIC('D','N','S','R')
  80 #define DNS_RDATASET_VALID(set)        ISC_MAGIC_VALID(set, DNS_RDATASET_MAGIC)
  81
  82 /*
  83  * Direct use of this structure by clients is strongly discouraged, except
  84  * for the 'link' field which may be used however the client wishes.  The
  85  * 'private', 'current', and 'index' fields MUST NOT be changed by clients.
  86  * rdataset implementations may change any of the fields.
  87  */
  88 struct dns_rdataset {
  89         unsigned int                    magic;          /* XXX ? */
  90         dns_rdatasetmethods_t *         methods;
  91         ISC_LINK(dns_rdataset_t)        link;
  92         /*
  93          * XXX do we need these, or should they be retrieved by methods?
  94          * Leaning towards the latter, since they are not frequently required
  95          * once you have the rdataset.
  96          */
  97         dns_rdataclass_t                rdclass;
  98         dns_rdatatype_t                 type;
  99         dns_ttl_t                       ttl;
 100         dns_trust_t                     trust;
 101         dns_rdatatype_t                 covers;
 102         /*
 103          * attributes
 104          */
 105         unsigned int                    attributes;
 106         /*
 107          * the counter provides the starting point in the "cyclic" order.
 108          * The value ISC_UINT32_MAX has a special meaning of "picking up a
 109          * random value." in order to take care of databases that do not
 110          * increment the counter.
 111          */
 112         isc_uint32_t                    count;
 113         /*
 114          * These are for use by the rdataset implementation, and MUST NOT
 115          * be changed by clients.
 116          */
 117         void *                          private1;
 118         void *                          private2;
 119         void *                          private3;
 120         unsigned int                    privateuint4;
 121         void *                          private5;
 122         void *                          private6;
 123 };
 124
 125 /*
 126  * _RENDERED:
 127  *      Used by message.c to indicate that the rdataset was rendered.
 128  *
 129  * _TTLADJUSTED:
 130  *      Used by message.c to indicate that the rdataset's rdata had differing
 131  *      TTL values, and the rdataset->ttl holds the smallest.
 132  */
 133 #define DNS_RDATASETATTR_QUESTION       0x00000001
 134 #define DNS_RDATASETATTR_RENDERED       0x00000002      /* Used by message.c */
 135 #define DNS_RDATASETATTR_ANSWERED       0x00000004      /* Used by server. */
 136 #define DNS_RDATASETATTR_CACHE          0x00000008      /* Used by resolver. */
 137 #define DNS_RDATASETATTR_ANSWER         0x00000010      /* Used by resolver. */
 138 #define DNS_RDATASETATTR_ANSWERSIG      0x00000020      /* Used by resolver. */
 139 #define DNS_RDATASETATTR_EXTERNAL       0x00000040      /* Used by resolver. */
 140 #define DNS_RDATASETATTR_NCACHE         0x00000080      /* Used by resolver. */
 141 #define DNS_RDATASETATTR_CHAINING       0x00000100      /* Used by resolver. */
 142 #define DNS_RDATASETATTR_TTLADJUSTED    0x00000200      /* Used by message.c */
 143 #define DNS_RDATASETATTR_FIXEDORDER     0x00000400
 144 #define DNS_RDATASETATTR_RANDOMIZE      0x00000800
 145 #define DNS_RDATASETATTR_CHASE          0x00001000      /* Used by resolver. */
 146 #define DNS_RDATASETATTR_NXDOMAIN       0x00002000
 147 #define DNS_RDATASETATTR_NOQNAME        0x00004000
 148 #define DNS_RDATASETATTR_CHECKNAMES     0x00008000      /* Used by resolver. */
 149 #define DNS_RDATASETATTR_REQUIREDGLUE   0x00010000
 150
 151 /*
 152  * _OMITDNSSEC:
 153  *      Omit DNSSEC records when rendering ncache records.
 154  */
 155 #define DNS_RDATASETTOWIRE_OMITDNSSEC   0x0001
 156
 157 void
 158 dns_rdataset_init(dns_rdataset_t *rdataset);
 159 /*
 160  * Make 'rdataset' a valid, disassociated rdataset.
 161  *
 162  * Requires:
 163  *      'rdataset' is not NULL.
 164  *
 165  * Ensures:
 166  *      'rdataset' is a valid, disassociated rdataset.
 167  */
 168
 169 void
 170 dns_rdataset_invalidate(dns_rdataset_t *rdataset);
 171 /*
 172  * Invalidate 'rdataset'.
 173  *
 174  * Requires:
 175  *      'rdataset' is a valid, disassociated rdataset.
 176  *
 177  * Ensures:
 178  *      If assertion checking is enabled, future attempts to use 'rdataset'
 179  *      without initializing it will cause an assertion failure.
 180  */
 181
 182 void
 183 dns_rdataset_disassociate(dns_rdataset_t *rdataset);
 184 /*
 185  * Disassociate 'rdataset' from its rdata, allowing it to be reused.
 186  *
 187  * Notes:
 188  *      The client must ensure it has no references to rdata in the rdataset
 189  *      before disassociating.
 190  *
 191  * Requires:
 192  *      'rdataset' is a valid, associated rdataset.
 193  *
 194  * Ensures:
 195  *      'rdataset' is a valid, disassociated rdataset.
 196  */
 197
 198 isc_boolean_t
 199 dns_rdataset_isassociated(dns_rdataset_t *rdataset);
 200 /*
 201  * Is 'rdataset' associated?
 202  *
 203  * Requires:
 204  *      'rdataset' is a valid rdataset.
 205  *
 206  * Returns:
 207  *      ISC_TRUE                        'rdataset' is associated.
 208  *      ISC_FALSE                       'rdataset' is not associated.
 209  */
 210
 211 void
 212 dns_rdataset_makequestion(dns_rdataset_t *rdataset, dns_rdataclass_t rdclass,
 213                           dns_rdatatype_t type);
 214 /*
 215  * Make 'rdataset' a valid, associated, question rdataset, with a
 216  * question class of 'rdclass' and type 'type'.
 217  *
 218  * Notes:
 219  *      Question rdatasets have a class and type, but no rdata.
 220  *
 221  * Requires:
 222  *      'rdataset' is a valid, disassociated rdataset.
 223  *
 224  * Ensures:
 225  *      'rdataset' is a valid, associated, question rdataset.
 226  */
 227
 228 void
 229 dns_rdataset_clone(dns_rdataset_t *source, dns_rdataset_t *target);
 230 /*
 231  * Make 'target' refer to the same rdataset as 'source'.
 232  *
 233  * Requires:
 234  *      'source' is a valid, associated rdataset.
 235  *
 236  *      'target' is a valid, dissociated rdataset.
 237  *
 238  * Ensures:
 239  *      'target' references the same rdataset as 'source'.
 240  */
 241
 242 unsigned int
 243 dns_rdataset_count(dns_rdataset_t *rdataset);
 244 /*
 245  * Return the number of records in 'rdataset'.
 246  *
 247  * Requires:
 248  *      'rdataset' is a valid, associated rdataset.
 249  *
 250  * Returns:
 251  *      The number of records in 'rdataset'.
 252  */
 253
 254 isc_result_t
 255 dns_rdataset_first(dns_rdataset_t *rdataset);
 256 /*
 257  * Move the rdata cursor to the first rdata in the rdataset (if any).
 258  *
 259  * Requires:
 260  *      'rdataset' is a valid, associated rdataset.
 261  *
 262  * Returns:
 263  *      ISC_R_SUCCESS
 264  *      ISC_R_NOMORE                    There are no rdata in the set.
 265  */
 266
 267 isc_result_t
 268 dns_rdataset_next(dns_rdataset_t *rdataset);
 269 /*
 270  * Move the rdata cursor to the next rdata in the rdataset (if any).
 271  *
 272  * Requires:
 273  *      'rdataset' is a valid, associated rdataset.
 274  *
 275  * Returns:
 276  *      ISC_R_SUCCESS
 277  *      ISC_R_NOMORE                    There are no more rdata in the set.
 278  */
 279
 280 void
 281 dns_rdataset_current(dns_rdataset_t *rdataset, dns_rdata_t *rdata);
 282 /*
 283  * Make 'rdata' refer to the current rdata.
 284  *
 285  * Notes:
 286  *
 287  *      The data returned in 'rdata' is valid for the life of the
 288  *      rdataset; in particular, subsequent changes in the cursor position
 289  *      do not invalidate 'rdata'.
 290  *
 291  * Requires:
 292  *      'rdataset' is a valid, associated rdataset.
 293  *
 294  *      The rdata cursor of 'rdataset' is at a valid location (i.e. the
 295  *      result of last call to a cursor movement command was ISC_R_SUCCESS).
 296  *
 297  * Ensures:
 298  *      'rdata' refers to the rdata at the rdata cursor location of
 299  *      'rdataset'.
 300  */
 301
 302 isc_result_t
 303 dns_rdataset_totext(dns_rdataset_t *rdataset,
 304                     dns_name_t *owner_name,
 305                     isc_boolean_t omit_final_dot,
 306                     isc_boolean_t question,
 307                     isc_buffer_t *target);
 308 /*
 309  * Convert 'rdataset' to text format, storing the result in 'target'.
 310  *
 311  * Notes:
 312  *      The rdata cursor position will be changed.
 313  *
 314  *      The 'question' flag should normally be ISC_FALSE.  If it is
 315  *      ISC_TRUE, the TTL and rdata fields are not printed.  This is
 316  *      for use when printing an rdata representing a question section.
 317  *
 318  *      This interface is deprecated; use dns_master_rdatasettottext()
 319  *      and/or dns_master_questiontotext() instead.
 320  *
 321  * Requires:
 322  *      'rdataset' is a valid rdataset.
 323  *
 324  *      'rdataset' is not empty.
 325  */
 326
 327 isc_result_t
 328 dns_rdataset_towire(dns_rdataset_t *rdataset,
 329                     dns_name_t *owner_name,
 330                     dns_compress_t *cctx,
 331                     isc_buffer_t *target,
 332                     unsigned int options,
 333                     unsigned int *countp);
 334 /*
 335  * Convert 'rdataset' to wire format, compressing names as specified
 336  * in 'cctx', and storing the result in 'target'.
 337  *
 338  * Notes:
 339  *      The rdata cursor position will be changed.
 340  *
 341  *      The number of RRs added to target will be added to *countp.
 342  *
 343  * Requires:
 344  *      'rdataset' is a valid rdataset.
 345  *
 346  *      'rdataset' is not empty.
 347  *
 348  *      'countp' is a valid pointer.
 349  *
 350  * Ensures:
 351  *      On a return of ISC_R_SUCCESS, 'target' contains a wire format
 352  *      for the data contained in 'rdataset'.  Any error return leaves
 353  *      the buffer unchanged.
 354  *
 355  *      *countp has been incremented by the number of RRs added to
 356  *      target.
 357  *
 358  * Returns:
 359  *      ISC_R_SUCCESS           - all ok
 360  *      ISC_R_NOSPACE           - 'target' doesn't have enough room
 361  *
 362  *      Any error returned by dns_rdata_towire(), dns_rdataset_next(),
 363  *      dns_name_towire().
 364  */
 365
 366 isc_result_t
 367 dns_rdataset_towiresorted(dns_rdataset_t *rdataset,
 368                           const dns_name_t *owner_name,
 369                           dns_compress_t *cctx,
 370                           isc_buffer_t *target,
 371                           dns_rdatasetorderfunc_t order,
 372                           const void *order_arg,
 373                           unsigned int options,
 374                           unsigned int *countp);
 375 /*
 376  * Like dns_rdataset_towire(), but sorting the rdatasets according to
 377  * the integer value returned by 'order' when called witih the rdataset
 378  * and 'order_arg' as arguments.
 379  *
 380  * Requires:
 381  *      All the requirements of dns_rdataset_towire(), and
 382  *      that order_arg is NULL if and only if order is NULL.
 383  */
 384
 385 isc_result_t
 386 dns_rdataset_towirepartial(dns_rdataset_t *rdataset,
 387                            const dns_name_t *owner_name,
 388                            dns_compress_t *cctx,
 389                            isc_buffer_t *target,
 390                            dns_rdatasetorderfunc_t order,
 391                            const void *order_arg,
 392                            unsigned int options,
 393                            unsigned int *countp,
 394                            void **state);
 395 /*
 396  * Like dns_rdataset_towiresorted() except that a partial rdataset
 397  * may be written.
 398  *
 399  * Requires:
 400  *      All the requirements of dns_rdataset_towiresorted().
 401  *      If 'state' is non NULL then the current position in the
 402  *      rdataset will be remembered if the rdataset in not
 403  *      completely written and should be passed on on subsequent
 404  *      calls (NOT CURRENTLY IMPLEMENTED).
 405  *
 406  * Returns:
 407  *      ISC_R_SUCCESS if all of the records were written.
 408  *      ISC_R_NOSPACE if unable to fit in all of the records. *countp
 409  *                    will be updated to reflect the number of records
 410  *                    written.
 411  */
 412
 413
 414 isc_result_t
 415 dns_rdataset_additionaldata(dns_rdataset_t *rdataset,
 416                             dns_additionaldatafunc_t add, void *arg);
 417 /*
 418  * For each rdata in rdataset, call 'add' for each name and type in the
 419  * rdata which is subject to additional section processing.
 420  *
 421  * Requires:
 422  *
 423  *      'rdataset' is a valid, non-question rdataset.
 424  *
 425  *      'add' is a valid dns_additionaldatafunc_t
 426  *
 427  * Ensures:
 428  *
 429  *      If successful, dns_rdata_additionaldata() will have been called for
 430  *      each rdata in 'rdataset'.
 431  *
 432  *      If a call to dns_rdata_additionaldata() is not successful, the
 433  *      result returned will be the result of dns_rdataset_additionaldata().
 434  *
 435  * Returns:
 436  *
 437  *      ISC_R_SUCCESS
 438  *
 439  *      Any error that dns_rdata_additionaldata() can return.
 440  */
 441
 442 isc_result_t
 443 dns_rdataset_getnoqname(dns_rdataset_t *rdataset, dns_name_t *name,
 444                         dns_rdataset_t *nsec, dns_rdataset_t *nsecsig);
 445 /*
 446  * Return the noqname proof for this record.
 447  *
 448  * Requires:
 449  *      'rdataset' to be valid and DNS_RDATASETATTR_NOQNAME to be set.
 450  *      'name' to be valid.
 451  *      'nsec' and 'nsecsig' to be valid and not associated.
 452  */
 453
 454 isc_result_t
 455 dns_rdataset_addnoqname(dns_rdataset_t *rdataset, dns_name_t *name);
 456 /*
 457  * Associate a noqname proof with this record.
 458  * Sets DNS_RDATASETATTR_NOQNAME if successful.
 459  * Adjusts the 'rdataset->ttl' to minimum of the 'rdataset->ttl' and
 460  * the 'nsec' and 'rrsig(nsec)' ttl.
 461  *
 462  * Requires:
 463  *      'rdataset' to be valid and DNS_RDATASETATTR_NOQNAME to be set.
 464  *      'name' to be valid and have NSEC and RRSIG(NSEC) rdatasets.
 465  */
 466
 467 ISC_LANG_ENDDECLS
 468
 469 #endif /* DNS_RDATASET_H */