contrib/bind-9.2.4rc7/lib/dns/include/dns/rdataset.h

   1 /*
   2  * Copyright (C) 2004  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.6 2004/03/09 06:11: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 } dns_rdatasetmethods_t;
  72
  73 #define DNS_RDATASET_MAGIC             ISC_MAGIC('D','N','S','R')
  74 #define DNS_RDATASET_VALID(set)        ISC_MAGIC_VALID(set, DNS_RDATASET_MAGIC)
  75
  76 /*
  77  * Direct use of this structure by clients is strongly discouraged, except
  78  * for the 'link' field which may be used however the client wishes.  The
  79  * 'private', 'current', and 'index' fields MUST NOT be changed by clients.
  80  * rdataset implementations may change any of the fields.
  81  */
  82 struct dns_rdataset {
  83         unsigned int                    magic;          /* XXX ? */
  84         dns_rdatasetmethods_t *         methods;
  85         ISC_LINK(dns_rdataset_t)        link;
  86         /*
  87          * XXX do we need these, or should they be retrieved by methods?
  88          * Leaning towards the latter, since they are not frequently required
  89          * once you have the rdataset.
  90          */
  91         dns_rdataclass_t                rdclass;
  92         dns_rdatatype_t                 type;
  93         dns_ttl_t                       ttl;
  94         dns_trust_t                     trust;
  95         dns_rdatatype_t                 covers;
  96         /*
  97          * attributes
  98          */
  99         unsigned int                    attributes;
 100         /*
 101          * These are for use by the rdataset implementation, and MUST NOT
 102          * be changed by clients.
 103          */
 104         void *                          private1;
 105         void *                          private2;
 106         void *                          private3;
 107         unsigned int                    privateuint4;
 108         void *                          private5;
 109 };
 110
 111 /*
 112  * _RENDERED:
 113  *      Used by message.c to indicate that the rdataset was rendered.
 114  *
 115  * _TTLADJUSTED:
 116  *      Used by message.c to indicate that the rdataset's rdata had differing
 117  *      TTL values, and the rdataset->ttl holds the smallest.
 118  */
 119 #define DNS_RDATASETATTR_QUESTION       0x0001
 120 #define DNS_RDATASETATTR_RENDERED       0x0002          /* Used by message.c */
 121 #define DNS_RDATASETATTR_ANSWERED       0x0004          /* Used by server. */
 122 #define DNS_RDATASETATTR_CACHE          0x0008          /* Used by resolver. */
 123 #define DNS_RDATASETATTR_ANSWER         0x0010          /* Used by resolver. */
 124 #define DNS_RDATASETATTR_ANSWERSIG      0x0020          /* Used by resolver. */
 125 #define DNS_RDATASETATTR_EXTERNAL       0x0040          /* Used by resolver. */
 126 #define DNS_RDATASETATTR_NCACHE         0x0080          /* Used by resolver. */
 127 #define DNS_RDATASETATTR_CHAINING       0x0100          /* Used by resolver. */
 128 #define DNS_RDATASETATTR_TTLADJUSTED    0x0200          /* Used by message.c */
 129 #define DNS_RDATASETATTR_FIXEDORDER     0x0400
 130 #define DNS_RDATASETATTR_RANDOMIZE      0x0800
 131 #define DNS_RDATASETATTR_CHASE          0x1000          /* Used by resolver. */
 132 #define DNS_RDATASETATTR_NXDOMAIN       0x2000
 133
 134 void
 135 dns_rdataset_init(dns_rdataset_t *rdataset);
 136 /*
 137  * Make 'rdataset' a valid, disassociated rdataset.
 138  *
 139  * Requires:
 140  *      'rdataset' is not NULL.
 141  *
 142  * Ensures:
 143  *      'rdataset' is a valid, disassociated rdataset.
 144  */
 145
 146 void
 147 dns_rdataset_invalidate(dns_rdataset_t *rdataset);
 148 /*
 149  * Invalidate 'rdataset'.
 150  *
 151  * Requires:
 152  *      'rdataset' is a valid, disassociated rdataset.
 153  *
 154  * Ensures:
 155  *      If assertion checking is enabled, future attempts to use 'rdataset'
 156  *      without initializing it will cause an assertion failure.
 157  */
 158
 159 void
 160 dns_rdataset_disassociate(dns_rdataset_t *rdataset);
 161 /*
 162  * Disassociate 'rdataset' from its rdata, allowing it to be reused.
 163  *
 164  * Notes:
 165  *      The client must ensure it has no references to rdata in the rdataset
 166  *      before disassociating.
 167  *
 168  * Requires:
 169  *      'rdataset' is a valid, associated rdataset.
 170  *
 171  * Ensures:
 172  *      'rdataset' is a valid, disassociated rdataset.
 173  */
 174
 175 isc_boolean_t
 176 dns_rdataset_isassociated(dns_rdataset_t *rdataset);
 177 /*
 178  * Is 'rdataset' associated?
 179  *
 180  * Requires:
 181  *      'rdataset' is a valid rdataset.
 182  *
 183  * Returns:
 184  *      ISC_TRUE                        'rdataset' is associated.
 185  *      ISC_FALSE                       'rdataset' is not associated.
 186  */
 187
 188 void
 189 dns_rdataset_makequestion(dns_rdataset_t *rdataset, dns_rdataclass_t rdclass,
 190                           dns_rdatatype_t type);
 191 /*
 192  * Make 'rdataset' a valid, associated, question rdataset, with a
 193  * question class of 'rdclass' and type 'type'.
 194  *
 195  * Notes:
 196  *      Question rdatasets have a class and type, but no rdata.
 197  *
 198  * Requires:
 199  *      'rdataset' is a valid, disassociated rdataset.
 200  *
 201  * Ensures:
 202  *      'rdataset' is a valid, associated, question rdataset.
 203  */
 204
 205 void
 206 dns_rdataset_clone(dns_rdataset_t *source, dns_rdataset_t *target);
 207 /*
 208  * Make 'target' refer to the same rdataset as 'source'.
 209  *
 210  * Requires:
 211  *      'source' is a valid, associated rdataset.
 212  *
 213  *      'target' is a valid, dissociated rdataset.
 214  *
 215  * Ensures:
 216  *      'target' references the same rdataset as 'source'.
 217  */
 218
 219 unsigned int
 220 dns_rdataset_count(dns_rdataset_t *rdataset);
 221 /*
 222  * Return the number of records in 'rdataset'.
 223  *
 224  * Requires:
 225  *      'rdataset' is a valid, associated rdataset.
 226  *
 227  * Returns:
 228  *      The number of records in 'rdataset'.
 229  */
 230
 231 isc_result_t
 232 dns_rdataset_first(dns_rdataset_t *rdataset);
 233 /*
 234  * Move the rdata cursor to the first rdata in the rdataset (if any).
 235  *
 236  * Requires:
 237  *      'rdataset' is a valid, associated rdataset.
 238  *
 239  * Returns:
 240  *      ISC_R_SUCCESS
 241  *      ISC_R_NOMORE                    There are no rdata in the set.
 242  */
 243
 244 isc_result_t
 245 dns_rdataset_next(dns_rdataset_t *rdataset);
 246 /*
 247  * Move the rdata cursor to the next rdata in the rdataset (if any).
 248  *
 249  * Requires:
 250  *      'rdataset' is a valid, associated rdataset.
 251  *
 252  * Returns:
 253  *      ISC_R_SUCCESS
 254  *      ISC_R_NOMORE                    There are no more rdata in the set.
 255  */
 256
 257 void
 258 dns_rdataset_current(dns_rdataset_t *rdataset, dns_rdata_t *rdata);
 259 /*
 260  * Make 'rdata' refer to the current rdata.
 261  *
 262  * Notes:
 263  *
 264  *      The data returned in 'rdata' is valid for the life of the
 265  *      rdataset; in particular, subsequent changes in the cursor position
 266  *      do not invalidate 'rdata'.
 267  *
 268  * Requires:
 269  *      'rdataset' is a valid, associated rdataset.
 270  *
 271  *      The rdata cursor of 'rdataset' is at a valid location (i.e. the
 272  *      result of last call to a cursor movement command was ISC_R_SUCCESS).
 273  *
 274  * Ensures:
 275  *      'rdata' refers to the rdata at the rdata cursor location of
 276  *      'rdataset'.
 277  */
 278
 279 isc_result_t
 280 dns_rdataset_totext(dns_rdataset_t *rdataset,
 281                     dns_name_t *owner_name,
 282                     isc_boolean_t omit_final_dot,
 283                     isc_boolean_t question,
 284                     isc_buffer_t *target);
 285 /*
 286  * Convert 'rdataset' to text format, storing the result in 'target'.
 287  *
 288  * Notes:
 289  *      The rdata cursor position will be changed.
 290  *
 291  *      The 'question' flag should normally be ISC_FALSE.  If it is
 292  *      ISC_TRUE, the TTL and rdata fields are not printed.  This is
 293  *      for use when printing an rdata representing a question section.
 294  *
 295  *      This interface is deprecated; use dns_master_rdatasettottext()
 296  *      and/or dns_master_questiontotext() instead.
 297  *
 298  * Requires:
 299  *      'rdataset' is a valid rdataset.
 300  *
 301  *      'rdataset' is not empty.
 302  */
 303
 304 isc_result_t
 305 dns_rdataset_towire(dns_rdataset_t *rdataset,
 306                     dns_name_t *owner_name,
 307                     dns_compress_t *cctx,
 308                     isc_buffer_t *target,
 309                     unsigned int *countp);
 310 /*
 311  * Convert 'rdataset' to wire format, compressing names as specified
 312  * in 'cctx', and storing the result in 'target'.
 313  *
 314  * Notes:
 315  *      The rdata cursor position will be changed.
 316  *
 317  *      The number of RRs added to target will be added to *countp.
 318  *
 319  * Requires:
 320  *      'rdataset' is a valid rdataset.
 321  *
 322  *      'rdataset' is not empty.
 323  *
 324  *      'countp' is a valid pointer.
 325  *
 326  * Ensures:
 327  *      On a return of ISC_R_SUCCESS, 'target' contains a wire format
 328  *      for the data contained in 'rdataset'.  Any error return leaves
 329  *      the buffer unchanged.
 330  *
 331  *      *countp has been incremented by the number of RRs added to
 332  *      target.
 333  *
 334  * Returns:
 335  *      ISC_R_SUCCESS           - all ok
 336  *      ISC_R_NOSPACE           - 'target' doesn't have enough room
 337  *
 338  *      Any error returned by dns_rdata_towire(), dns_rdataset_next(),
 339  *      dns_name_towire().
 340  */
 341
 342 isc_result_t
 343 dns_rdataset_towiresorted(dns_rdataset_t *rdataset,
 344                           dns_name_t *owner_name,
 345                           dns_compress_t *cctx,
 346                           isc_buffer_t *target,
 347                           dns_rdatasetorderfunc_t order,
 348                           void *order_arg,
 349                           unsigned int *countp);
 350 /*
 351  * Like dns_rdataset_towire(), but sorting the rdatasets according to
 352  * the integer value returned by 'order' when called witih the rdataset
 353  * and 'order_arg' as arguments.
 354  *
 355  * Requires:
 356  *      All the requirements of dns_rdataset_towire(), and
 357  *      that order_arg is NULL if and only if order is NULL.
 358  */
 359
 360 isc_result_t
 361 dns_rdataset_towirepartial(dns_rdataset_t *rdataset,
 362                            dns_name_t *owner_name,
 363                            dns_compress_t *cctx,
 364                            isc_buffer_t *target,
 365                            dns_rdatasetorderfunc_t order,
 366                            void *order_arg,
 367                            unsigned int *countp,
 368                            void **state);
 369 /*
 370  * Like dns_rdataset_towiresorted() except that a partial rdataset
 371  * may be written.
 372  *
 373  * Requires:
 374  *      All the requirements of dns_rdataset_towiresorted().
 375  *      If 'state' is non NULL then the current position in the
 376  *      rdataset will be remembered if the rdataset in not
 377  *      completely written and should be passed on on subsequent
 378  *      calls (NOT CURRENTLY IMPLEMENTED).
 379  *
 380  * Returns:
 381  *      ISC_R_SUCCESS if all of the records were written.
 382  *      ISC_R_NOSPACE if unable to fit in all of the records. *countp
 383  *                    will be updated to reflect the number of records
 384  *                    written.
 385  */
 386
 387
 388 isc_result_t
 389 dns_rdataset_additionaldata(dns_rdataset_t *rdataset,
 390                             dns_additionaldatafunc_t add, void *arg);
 391 /*
 392  * For each rdata in rdataset, call 'add' for each name and type in the
 393  * rdata which is subject to additional section processing.
 394  *
 395  * Requires:
 396  *
 397  *      'rdataset' is a valid, non-question rdataset.
 398  *
 399  *      'add' is a valid dns_additionaldatafunc_t
 400  *
 401  * Ensures:
 402  *
 403  *      If successful, dns_rdata_additionaldata() will have been called for
 404  *      each rdata in 'rdataset'.
 405  *
 406  *      If a call to dns_rdata_additionaldata() is not successful, the
 407  *      result returned will be the result of dns_rdataset_additionaldata().
 408  *
 409  * Returns:
 410  *
 411  *      ISC_R_SUCCESS
 412  *
 413  *      Any error that dns_rdata_additionaldata() can return.
 414  */
 415
 416 ISC_LANG_ENDDECLS
 417
 418 #endif /* DNS_RDATASET_H */