2 * Copyright (C) 2004-2006 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2003 Internet Software Consortium.
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.
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.
18 /* $Id: rdataset.h,v 1.41.2.5.2.10 2006/03/02 00:37:20 marka Exp $ */
20 #ifndef DNS_RDATASET_H
21 #define DNS_RDATASET_H 1
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.
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
40 * Clients of this module must impose any required synchronization.
43 * No anticipated impact.
49 * No anticipated impact.
56 #include <isc/magic.h>
58 #include <dns/types.h>
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,
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,
73 isc_result_t (*getnoqname)(dns_rdataset_t *rdataset,
76 dns_rdataset_t *nsecsig);
77 } dns_rdatasetmethods_t;
79 #define DNS_RDATASET_MAGIC ISC_MAGIC('D','N','S','R')
80 #define DNS_RDATASET_VALID(set) ISC_MAGIC_VALID(set, DNS_RDATASET_MAGIC)
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.
89 unsigned int magic; /* XXX ? */
90 dns_rdatasetmethods_t * methods;
91 ISC_LINK(dns_rdataset_t) link;
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.
97 dns_rdataclass_t rdclass;
101 dns_rdatatype_t covers;
105 unsigned int attributes;
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.
114 * These are for use by the rdataset implementation, and MUST NOT
115 * be changed by clients.
120 unsigned int privateuint4;
127 * Used by message.c to indicate that the rdataset was rendered.
130 * Used by message.c to indicate that the rdataset's rdata had differing
131 * TTL values, and the rdataset->ttl holds the smallest.
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
153 * Omit DNSSEC records when rendering ncache records.
155 #define DNS_RDATASETTOWIRE_OMITDNSSEC 0x0001
158 dns_rdataset_init(dns_rdataset_t *rdataset);
160 * Make 'rdataset' a valid, disassociated rdataset.
163 * 'rdataset' is not NULL.
166 * 'rdataset' is a valid, disassociated rdataset.
170 dns_rdataset_invalidate(dns_rdataset_t *rdataset);
172 * Invalidate 'rdataset'.
175 * 'rdataset' is a valid, disassociated rdataset.
178 * If assertion checking is enabled, future attempts to use 'rdataset'
179 * without initializing it will cause an assertion failure.
183 dns_rdataset_disassociate(dns_rdataset_t *rdataset);
185 * Disassociate 'rdataset' from its rdata, allowing it to be reused.
188 * The client must ensure it has no references to rdata in the rdataset
189 * before disassociating.
192 * 'rdataset' is a valid, associated rdataset.
195 * 'rdataset' is a valid, disassociated rdataset.
199 dns_rdataset_isassociated(dns_rdataset_t *rdataset);
201 * Is 'rdataset' associated?
204 * 'rdataset' is a valid rdataset.
207 * ISC_TRUE 'rdataset' is associated.
208 * ISC_FALSE 'rdataset' is not associated.
212 dns_rdataset_makequestion(dns_rdataset_t *rdataset, dns_rdataclass_t rdclass,
213 dns_rdatatype_t type);
215 * Make 'rdataset' a valid, associated, question rdataset, with a
216 * question class of 'rdclass' and type 'type'.
219 * Question rdatasets have a class and type, but no rdata.
222 * 'rdataset' is a valid, disassociated rdataset.
225 * 'rdataset' is a valid, associated, question rdataset.
229 dns_rdataset_clone(dns_rdataset_t *source, dns_rdataset_t *target);
231 * Make 'target' refer to the same rdataset as 'source'.
234 * 'source' is a valid, associated rdataset.
236 * 'target' is a valid, dissociated rdataset.
239 * 'target' references the same rdataset as 'source'.
243 dns_rdataset_count(dns_rdataset_t *rdataset);
245 * Return the number of records in 'rdataset'.
248 * 'rdataset' is a valid, associated rdataset.
251 * The number of records in 'rdataset'.
255 dns_rdataset_first(dns_rdataset_t *rdataset);
257 * Move the rdata cursor to the first rdata in the rdataset (if any).
260 * 'rdataset' is a valid, associated rdataset.
264 * ISC_R_NOMORE There are no rdata in the set.
268 dns_rdataset_next(dns_rdataset_t *rdataset);
270 * Move the rdata cursor to the next rdata in the rdataset (if any).
273 * 'rdataset' is a valid, associated rdataset.
277 * ISC_R_NOMORE There are no more rdata in the set.
281 dns_rdataset_current(dns_rdataset_t *rdataset, dns_rdata_t *rdata);
283 * Make 'rdata' refer to the current rdata.
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'.
292 * 'rdataset' is a valid, associated rdataset.
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).
298 * 'rdata' refers to the rdata at the rdata cursor location of
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);
309 * Convert 'rdataset' to text format, storing the result in 'target'.
312 * The rdata cursor position will be changed.
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.
318 * This interface is deprecated; use dns_master_rdatasettottext()
319 * and/or dns_master_questiontotext() instead.
322 * 'rdataset' is a valid rdataset.
324 * 'rdataset' is not empty.
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);
335 * Convert 'rdataset' to wire format, compressing names as specified
336 * in 'cctx', and storing the result in 'target'.
339 * The rdata cursor position will be changed.
341 * The number of RRs added to target will be added to *countp.
344 * 'rdataset' is a valid rdataset.
346 * 'rdataset' is not empty.
348 * 'countp' is a valid pointer.
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.
355 * *countp has been incremented by the number of RRs added to
359 * ISC_R_SUCCESS - all ok
360 * ISC_R_NOSPACE - 'target' doesn't have enough room
362 * Any error returned by dns_rdata_towire(), dns_rdataset_next(),
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);
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.
381 * All the requirements of dns_rdataset_towire(), and
382 * that order_arg is NULL if and only if order is NULL.
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,
396 * Like dns_rdataset_towiresorted() except that a partial rdataset
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).
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
415 dns_rdataset_additionaldata(dns_rdataset_t *rdataset,
416 dns_additionaldatafunc_t add, void *arg);
418 * For each rdata in rdataset, call 'add' for each name and type in the
419 * rdata which is subject to additional section processing.
423 * 'rdataset' is a valid, non-question rdataset.
425 * 'add' is a valid dns_additionaldatafunc_t
429 * If successful, dns_rdata_additionaldata() will have been called for
430 * each rdata in 'rdataset'.
432 * If a call to dns_rdata_additionaldata() is not successful, the
433 * result returned will be the result of dns_rdataset_additionaldata().
439 * Any error that dns_rdata_additionaldata() can return.
443 dns_rdataset_getnoqname(dns_rdataset_t *rdataset, dns_name_t *name,
444 dns_rdataset_t *nsec, dns_rdataset_t *nsecsig);
446 * Return the noqname proof for this record.
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.
455 dns_rdataset_addnoqname(dns_rdataset_t *rdataset, dns_name_t *name);
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.
463 * 'rdataset' to be valid and DNS_RDATASETATTR_NOQNAME to be set.
464 * 'name' to be valid and have NSEC and RRSIG(NSEC) rdatasets.
469 #endif /* DNS_RDATASET_H */