Merge branch 'vendor/EXPAT'
[dragonfly.git] / contrib / bind / lib / dns / include / dns / rdataset.h
1 /*
2  * Copyright (C) 2004-2007, 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.62.128.2 2009/01/19 23:47:03 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 <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
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 *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  */
118 struct 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
194 void
195 dns_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
206 void
207 dns_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
219 void
220 dns_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
235 isc_boolean_t
236 dns_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
248 void
249 dns_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
265 void
266 dns_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
279 unsigned int
280 dns_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
291 isc_result_t
292 dns_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
304 isc_result_t
305 dns_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
317 void
318 dns_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
339 isc_result_t
340 dns_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
364 isc_result_t
365 dns_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
403 isc_result_t
404 dns_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 with 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
422 isc_result_t
423 dns_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
450 isc_result_t
451 dns_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
478 isc_result_t
479 dns_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
490 isc_result_t
491 dns_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
503 isc_result_t
504 dns_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
539 isc_result_t
540 dns_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
570 isc_result_t
571 dns_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
595 ISC_LANG_ENDDECLS
596
597 #endif /* DNS_RDATASET_H */