rdataset.h 18.5 KB
Newer Older
Bob Halley's avatar
Bob Halley committed
1
/*
Automatic Updater's avatar
Automatic Updater committed
2
 * Copyright (C) 2004-2009  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 1999-2003  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
Bob Halley's avatar
Bob Halley committed
6 7
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
Bob Halley's avatar
Bob Halley committed
16 17
 */

Automatic Updater's avatar
Automatic Updater committed
18
/* $Id: rdataset.h,v 1.67 2009/01/17 23:47:43 tbox Exp $ */
David Lawrence's avatar
David Lawrence committed
19

Bob Halley's avatar
Bob Halley committed
20 21 22 23 24 25 26
#ifndef DNS_RDATASET_H
#define DNS_RDATASET_H 1

/*****
 ***** Module Info
 *****/

27
/*! \file dns/rdataset.h
28
 * \brief
Bob Halley's avatar
Bob Halley committed
29 30 31 32 33 34 35
 * A DNS rdataset is a handle that can be associated with a collection of
 * rdata all having a common owner name, class, and type.
 *
 * The dns_rdataset_t type is like a "virtual class".  To actually use
 * rdatasets, an implementation of the method suite (e.g. "slabbed rdata") is
 * required.
 *
36
 * XXX <more> XXX
Bob Halley's avatar
Bob Halley committed
37 38
 *
 * MP:
39
 *\li	Clients of this module must impose any required synchronization.
Bob Halley's avatar
Bob Halley committed
40 41
 *
 * Reliability:
42
 *\li	No anticipated impact.
Bob Halley's avatar
Bob Halley committed
43 44
 *
 * Resources:
45
 *\li	TBS
Bob Halley's avatar
Bob Halley committed
46 47
 *
 * Security:
48
 *\li	No anticipated impact.
Bob Halley's avatar
Bob Halley committed
49 50
 *
 * Standards:
51
 *\li	None.
Bob Halley's avatar
Bob Halley committed
52 53
 */

Bob Halley's avatar
Bob Halley committed
54
#include <isc/lang.h>
55
#include <isc/magic.h>
56
#include <isc/stdtime.h>
Bob Halley's avatar
Bob Halley committed
57 58 59

#include <dns/types.h>

Bob Halley's avatar
Bob Halley committed
60 61
ISC_LANG_BEGINDECLS

62 63 64 65 66 67
typedef enum {
	dns_rdatasetadditional_fromauth,
	dns_rdatasetadditional_fromcache,
	dns_rdatasetadditional_fromglue
} dns_rdatasetadditional_t;

Bob Halley's avatar
Bob Halley committed
68
typedef struct dns_rdatasetmethods {
Bob Halley's avatar
Bob Halley committed
69
	void			(*disassociate)(dns_rdataset_t *rdataset);
70 71
	isc_result_t		(*first)(dns_rdataset_t *rdataset);
	isc_result_t		(*next)(dns_rdataset_t *rdataset);
Bob Halley's avatar
Bob Halley committed
72 73
	void			(*current)(dns_rdataset_t *rdataset,
					   dns_rdata_t *rdata);
Bob Halley's avatar
Bob Halley committed
74 75
	void			(*clone)(dns_rdataset_t *source,
					 dns_rdataset_t *target);
Bob Halley's avatar
Bob Halley committed
76
	unsigned int		(*count)(dns_rdataset_t *rdataset);
77 78 79 80
	isc_result_t		(*addnoqname)(dns_rdataset_t *rdataset,
					      dns_name_t *name);
	isc_result_t		(*getnoqname)(dns_rdataset_t *rdataset,
					      dns_name_t *name,
81 82 83 84 85 86 87 88
					      dns_rdataset_t *neg,
					      dns_rdataset_t *negsig);
	isc_result_t		(*addclosest)(dns_rdataset_t *rdataset,
					      dns_name_t *name);
	isc_result_t		(*getclosest)(dns_rdataset_t *rdataset,
					      dns_name_t *name,
					      dns_rdataset_t *neg,
					      dns_rdataset_t *negsig);
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
	isc_result_t		(*getadditional)(dns_rdataset_t *rdataset,
						 dns_rdatasetadditional_t type,
						 dns_rdatatype_t qtype,
						 dns_acache_t *acache,
						 dns_zone_t **zonep,
						 dns_db_t **dbp,
						 dns_dbversion_t **versionp,
						 dns_dbnode_t **nodep,
						 dns_name_t *fname,
						 dns_message_t *msg,
						 isc_stdtime_t now);
	isc_result_t		(*setadditional)(dns_rdataset_t *rdataset,
						 dns_rdatasetadditional_t type,
						 dns_rdatatype_t qtype,
						 dns_acache_t *acache,
						 dns_zone_t *zone,
						 dns_db_t *db,
						 dns_dbversion_t *version,
						 dns_dbnode_t *node,
						 dns_name_t *fname);
	isc_result_t		(*putadditional)(dns_acache_t *acache,
						 dns_rdataset_t *rdataset,
						 dns_rdatasetadditional_t type,
						 dns_rdatatype_t qtype);
Bob Halley's avatar
Bob Halley committed
113 114
} dns_rdatasetmethods_t;

115
#define DNS_RDATASET_MAGIC	       ISC_MAGIC('D','N','S','R')
116
#define DNS_RDATASET_VALID(set)	       ISC_MAGIC_VALID(set, DNS_RDATASET_MAGIC)
Bob Halley's avatar
Bob Halley committed
117

118
/*%
Bob Halley's avatar
Bob Halley committed
119 120 121 122 123 124 125 126 127 128 129 130 131 132
 * Direct use of this structure by clients is strongly discouraged, except
 * for the 'link' field which may be used however the client wishes.  The
 * 'private', 'current', and 'index' fields MUST NOT be changed by clients.
 * rdataset implementations may change any of the fields.
 */
struct dns_rdataset {
	unsigned int			magic;		/* XXX ? */
	dns_rdatasetmethods_t *		methods;
	ISC_LINK(dns_rdataset_t)	link;
	/*
	 * XXX do we need these, or should they be retrieved by methods?
	 * Leaning towards the latter, since they are not frequently required
	 * once you have the rdataset.
	 */
Bob Halley's avatar
Bob Halley committed
133
	dns_rdataclass_t		rdclass;
Bob Halley's avatar
Bob Halley committed
134 135
	dns_rdatatype_t			type;
	dns_ttl_t			ttl;
Bob Halley's avatar
Bob Halley committed
136
	dns_trust_t			trust;
Bob Halley's avatar
Bob Halley committed
137
	dns_rdatatype_t			covers;
138 139 140 141
	/*
	 * attributes
	 */
	unsigned int			attributes;
142
	/*%
143 144 145 146 147 148
	 * the counter provides the starting point in the "cyclic" order.
	 * The value ISC_UINT32_MAX has a special meaning of "picking up a
	 * random value." in order to take care of databases that do not
	 * increment the counter.
	 */
	isc_uint32_t			count;
149 150 151 152 153
	/*
	 * This RRSIG RRset should be re-generated around this time.
	 * Only valid if DNS_RDATASETATTR_RESIGN is set in attributes.
	 */
	isc_stdtime_t			resign;
154 155
	/*@{*/
	/*%
Bob Halley's avatar
Bob Halley committed
156 157 158 159 160 161
	 * These are for use by the rdataset implementation, and MUST NOT
	 * be changed by clients.
	 */
	void *				private1;
	void *				private2;
	void *				private3;
162
	unsigned int			privateuint4;
Bob Halley's avatar
Bob Halley committed
163
	void *				private5;
164
	void *				private6;
165
	void *				private7;
166
	/*@}*/
Automatic Updater's avatar
Automatic Updater committed
167

Bob Halley's avatar
Bob Halley committed
168 169
};

170 171
/*!
 * \def DNS_RDATASETATTR_RENDERED
172 173
 *	Used by message.c to indicate that the rdataset was rendered.
 *
174
 * \def DNS_RDATASETATTR_TTLADJUSTED
175 176
 *	Used by message.c to indicate that the rdataset's rdata had differing
 *	TTL values, and the rdataset->ttl holds the smallest.
177 178 179
 *
 * \def DNS_RDATASETATTR_LOADORDER
 *	Output the RRset in load order.
180
 */
Mark Andrews's avatar
Mark Andrews committed
181

182
#define DNS_RDATASETATTR_QUESTION	0x00000001
183 184 185 186 187 188 189 190 191
#define DNS_RDATASETATTR_RENDERED	0x00000002	/*%< Used by message.c */
#define DNS_RDATASETATTR_ANSWERED	0x00000004	/*%< Used by server. */
#define DNS_RDATASETATTR_CACHE		0x00000008	/*%< Used by resolver. */
#define DNS_RDATASETATTR_ANSWER		0x00000010	/*%< Used by resolver. */
#define DNS_RDATASETATTR_ANSWERSIG	0x00000020	/*%< Used by resolver. */
#define DNS_RDATASETATTR_EXTERNAL	0x00000040	/*%< Used by resolver. */
#define DNS_RDATASETATTR_NCACHE		0x00000080	/*%< Used by resolver. */
#define DNS_RDATASETATTR_CHAINING	0x00000100	/*%< Used by resolver. */
#define DNS_RDATASETATTR_TTLADJUSTED	0x00000200	/*%< Used by message.c */
192 193
#define DNS_RDATASETATTR_FIXEDORDER	0x00000400
#define DNS_RDATASETATTR_RANDOMIZE	0x00000800
194
#define DNS_RDATASETATTR_CHASE		0x00001000	/*%< Used by resolver. */
195 196
#define DNS_RDATASETATTR_NXDOMAIN	0x00002000
#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 202
#define DNS_RDATASETATTR_CLOSEST	0x00080000
#define DNS_RDATASETATTR_OPTOUT		0x00100000	/*%< OPTOUT proof */
203

204
/*%
205 206 207 208 209
 * _OMITDNSSEC:
 * 	Omit DNSSEC records when rendering ncache records.
 */
#define DNS_RDATASETTOWIRE_OMITDNSSEC	0x0001

Bob Halley's avatar
Bob Halley committed
210 211
void
dns_rdataset_init(dns_rdataset_t *rdataset);
212
/*%<
Bob Halley's avatar
Bob Halley committed
213 214 215
 * Make 'rdataset' a valid, disassociated rdataset.
 *
 * Requires:
216
 *\li	'rdataset' is not NULL.
Bob Halley's avatar
Bob Halley committed
217 218
 *
 * Ensures:
219
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
220 221 222 223
 */

void
dns_rdataset_invalidate(dns_rdataset_t *rdataset);
224
/*%<
Bob Halley's avatar
Bob Halley committed
225 226 227
 * Invalidate 'rdataset'.
 *
 * Requires:
228
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
229 230
 *
 * Ensures:
231
 *\li	If assertion checking is enabled, future attempts to use 'rdataset'
Bob Halley's avatar
Bob Halley committed
232 233 234 235 236
 *	without initializing it will cause an assertion failure.
 */

void
dns_rdataset_disassociate(dns_rdataset_t *rdataset);
237
/*%<
Bob Halley's avatar
Bob Halley committed
238
 * Disassociate 'rdataset' from its rdata, allowing it to be reused.
Bob Halley's avatar
Bob Halley committed
239 240
 *
 * Notes:
241
 *\li	The client must ensure it has no references to rdata in the rdataset
Bob Halley's avatar
Bob Halley committed
242 243 244
 *	before disassociating.
 *
 * Requires:
245
 *\li	'rdataset' is a valid, associated rdataset.
Bob Halley's avatar
Bob Halley committed
246 247
 *
 * Ensures:
248
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
249 250
 */

Bob Halley's avatar
Bob Halley committed
251 252
isc_boolean_t
dns_rdataset_isassociated(dns_rdataset_t *rdataset);
253
/*%<
Bob Halley's avatar
Bob Halley committed
254 255 256
 * Is 'rdataset' associated?
 *
 * Requires:
257
 *\li	'rdataset' is a valid rdataset.
Bob Halley's avatar
Bob Halley committed
258 259
 *
 * Returns:
260 261
 *\li	#ISC_TRUE			'rdataset' is associated.
 *\li	#ISC_FALSE			'rdataset' is not associated.
Bob Halley's avatar
Bob Halley committed
262 263
 */

Bob Halley's avatar
Bob Halley committed
264 265 266
void
dns_rdataset_makequestion(dns_rdataset_t *rdataset, dns_rdataclass_t rdclass,
			  dns_rdatatype_t type);
267
/*%<
Bob Halley's avatar
Bob Halley committed
268 269 270 271
 * Make 'rdataset' a valid, associated, question rdataset, with a
 * question class of 'rdclass' and type 'type'.
 *
 * Notes:
272
 *\li	Question rdatasets have a class and type, but no rdata.
Bob Halley's avatar
Bob Halley committed
273 274
 *
 * Requires:
275
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
276 277
 *
 * Ensures:
278
 *\li	'rdataset' is a valid, associated, question rdataset.
Bob Halley's avatar
Bob Halley committed
279 280
 */

Bob Halley's avatar
Bob Halley committed
281 282
void
dns_rdataset_clone(dns_rdataset_t *source, dns_rdataset_t *target);
283
/*%<
Bob Halley's avatar
Bob Halley committed
284 285 286
 * Make 'target' refer to the same rdataset as 'source'.
 *
 * Requires:
287
 *\li	'source' is a valid, associated rdataset.
Bob Halley's avatar
Bob Halley committed
288
 *
289
 *\li	'target' is a valid, dissociated rdataset.
Bob Halley's avatar
Bob Halley committed
290 291
 *
 * Ensures:
292
 *\li	'target' references the same rdataset as 'source'.
Bob Halley's avatar
Bob Halley committed
293 294
 */

Bob Halley's avatar
Bob Halley committed
295 296
unsigned int
dns_rdataset_count(dns_rdataset_t *rdataset);
297
/*%<
Bob Halley's avatar
Bob Halley committed
298 299 300
 * Return the number of records in 'rdataset'.
 *
 * Requires:
301
 *\li	'rdataset' is a valid, associated rdataset.
Bob Halley's avatar
Bob Halley committed
302 303
 *
 * Returns:
304
 *\li	The number of records in 'rdataset'.
Bob Halley's avatar
Bob Halley committed
305 306
 */

307
isc_result_t
Bob Halley's avatar
Bob Halley committed
308
dns_rdataset_first(dns_rdataset_t *rdataset);
309
/*%<
Bob Halley's avatar
Bob Halley committed
310 311 312
 * Move the rdata cursor to the first rdata in the rdataset (if any).
 *
 * Requires:
313
 *\li	'rdataset' is a valid, associated rdataset.
Bob Halley's avatar
Bob Halley committed
314 315
 *
 * Returns:
316 317
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMORE			There are no rdata in the set.
Bob Halley's avatar
Bob Halley committed
318 319
 */

320
isc_result_t
Bob Halley's avatar
Bob Halley committed
321
dns_rdataset_next(dns_rdataset_t *rdataset);
322
/*%<
Bob Halley's avatar
Bob Halley committed
323 324 325
 * Move the rdata cursor to the next rdata in the rdataset (if any).
 *
 * Requires:
326
 *\li	'rdataset' is a valid, associated rdataset.
Bob Halley's avatar
Bob Halley committed
327 328
 *
 * Returns:
329 330
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMORE			There are no more rdata in the set.
Bob Halley's avatar
Bob Halley committed
331 332 333 334
 */

void
dns_rdataset_current(dns_rdataset_t *rdataset, dns_rdata_t *rdata);
335
/*%<
Bob Halley's avatar
Bob Halley committed
336 337
 * Make 'rdata' refer to the current rdata.
 *
Bob Halley's avatar
Bob Halley committed
338 339
 * Notes:
 *
340
 *\li	The data returned in 'rdata' is valid for the life of the
Bob Halley's avatar
Bob Halley committed
341 342 343
 *	rdataset; in particular, subsequent changes in the cursor position
 *	do not invalidate 'rdata'.
 *
Bob Halley's avatar
Bob Halley committed
344
 * Requires:
345
 *\li	'rdataset' is a valid, associated rdataset.
Bob Halley's avatar
Bob Halley committed
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).
Bob Halley's avatar
Bob Halley committed
349 350
 *
 * Ensures:
351 352
 *\li	'rdata' refers to the rdata at the rdata cursor location of
 *\li	'rdataset'.
Bob Halley's avatar
Bob Halley committed
353 354
 */

355
isc_result_t
Bob Halley's avatar
Bob Halley committed
356 357 358
dns_rdataset_totext(dns_rdataset_t *rdataset,
		    dns_name_t *owner_name,
		    isc_boolean_t omit_final_dot,
359
		    isc_boolean_t question,
360
		    isc_buffer_t *target);
361
/*%<
Bob Halley's avatar
Bob Halley committed
362 363 364
 * Convert 'rdataset' to text format, storing the result in 'target'.
 *
 * Notes:
365
 *\li	The rdata cursor position will be changed.
Bob Halley's avatar
Bob Halley committed
366
 *
Automatic Updater's avatar
Automatic Updater committed
367 368
 *\li	The 'question' flag should normally be #ISC_FALSE.  If it is
 *	#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.
Bob Halley's avatar
Bob Halley committed
373
 *
Bob Halley's avatar
Bob Halley committed
374
 * Requires:
375
 *\li	'rdataset' is a valid rdataset.
Bob Halley's avatar
Bob Halley committed
376
 *
377
 *\li	'rdataset' is not empty.
Bob Halley's avatar
Bob Halley committed
378 379
 */

380
isc_result_t
Bob Halley's avatar
Bob Halley committed
381 382 383
dns_rdataset_towire(dns_rdataset_t *rdataset,
		    dns_name_t *owner_name,
		    dns_compress_t *cctx,
384
		    isc_buffer_t *target,
385
		    unsigned int options,
386
		    unsigned int *countp);
387
/*%<
Bob Halley's avatar
Bob Halley committed
388
 * Convert 'rdataset' to wire format, compressing names as specified
Bob Halley's avatar
Bob Halley committed
389
 * in 'cctx', and storing the result in 'target'.
Bob Halley's avatar
Bob Halley committed
390 391
 *
 * Notes:
392
 *\li	The rdata cursor position will be changed.
Bob Halley's avatar
Bob Halley committed
393
 *
394
 *\li	The number of RRs added to target will be added to *countp.
395
 *
Bob Halley's avatar
Bob Halley committed
396
 * Requires:
397
 *\li	'rdataset' is a valid rdataset.
Bob Halley's avatar
Bob Halley committed
398
 *
399
 *\li	'rdataset' is not empty.
Bob Halley's avatar
Bob Halley committed
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
Bob Halley's avatar
Bob Halley committed
406
 *	the buffer unchanged.
407
 *
408
 *\li	*countp has been incremented by the number of RRs added to
409 410
 *	target.
 *
411
 * Returns:
412 413
 *\li	#ISC_R_SUCCESS		- all ok
 *\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().
Bob Halley's avatar
Bob Halley committed
417 418
 */

419 420
isc_result_t
dns_rdataset_towiresorted(dns_rdataset_t *rdataset,
421
			  const dns_name_t *owner_name,
422 423 424
			  dns_compress_t *cctx,
			  isc_buffer_t *target,
			  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
Francis Dupont's avatar
Francis Dupont committed
430
 * the integer value returned by 'order' when called with the rdataset
431 432 433
 * and 'order_arg' as arguments.
 *
 * Requires:
434
 *\li	All the requirements of dns_rdataset_towire(), and
435 436 437
 *	that order_arg is NULL if and only if order is NULL.
 */

438 439
isc_result_t
dns_rdataset_towirepartial(dns_rdataset_t *rdataset,
440
			   const dns_name_t *owner_name,
441 442 443
			   dns_compress_t *cctx,
			   isc_buffer_t *target,
			   dns_rdatasetorderfunc_t order,
444
			   const void *order_arg,
Mark Andrews's avatar
Mark Andrews committed
445
			   unsigned int options,
446 447
			   unsigned int *countp,
			   void **state);
448
/*%<
449 450 451 452
 * Like dns_rdataset_towiresorted() except that a partial rdataset
 * may be written.
 *
 * Requires:
453
 *\li	All the requirements of dns_rdataset_towiresorted().
454 455 456 457 458 459
 *	If 'state' is non NULL then the current position in the
 *	rdataset will be remembered if the rdataset in not
 *	completely written and should be passed on on subsequent
 *	calls (NOT CURRENTLY IMPLEMENTED).
 *
 * Returns:
460 461
 *\li	#ISC_R_SUCCESS if all of the records were written.
 *\li	#ISC_R_NOSPACE if unable to fit in all of the records. *countp
462 463 464 465
 *		      will be updated to reflect the number of records
 *		      written.
 */

466
isc_result_t
Bob Halley's avatar
Bob Halley committed
467 468
dns_rdataset_additionaldata(dns_rdataset_t *rdataset,
			    dns_additionaldatafunc_t add, void *arg);
469
/*%<
Bob Halley's avatar
Bob Halley committed
470 471 472 473 474
 * For each rdata in rdataset, call 'add' for each name and type in the
 * rdata which is subject to additional section processing.
 *
 * Requires:
 *
475
 *\li	'rdataset' is a valid, non-question rdataset.
Bob Halley's avatar
Bob Halley committed
476
 *
477
 *\li	'add' is a valid dns_additionaldatafunc_t
Bob Halley's avatar
Bob Halley committed
478 479 480
 *
 * Ensures:
 *
481
 *\li	If successful, dns_rdata_additionaldata() will have been called for
Bob Halley's avatar
Bob Halley committed
482 483
 *	each rdata in 'rdataset'.
 *
484
 *\li	If a call to dns_rdata_additionaldata() is not successful, the
Bob Halley's avatar
Bob Halley committed
485 486 487 488
 *	result returned will be the result of dns_rdataset_additionaldata().
 *
 * Returns:
 *
489
 *\li	#ISC_R_SUCCESS
Bob Halley's avatar
Bob Halley committed
490
 *
491
 *\li	Any error that dns_rdata_additionaldata() can return.
Bob Halley's avatar
Bob Halley committed
492 493
 */

494 495
isc_result_t
dns_rdataset_getnoqname(dns_rdataset_t *rdataset, dns_name_t *name,
496
			dns_rdataset_t *neg, dns_rdataset_t *negsig);
497
/*%<
498 499 500
 * Return the noqname proof for this record.
 *
 * Requires:
501 502
 *\li	'rdataset' to be valid and #DNS_RDATASETATTR_NOQNAME to be set.
 *\li	'name' to be valid.
503
 *\li	'neg' and 'negsig' to be valid and not associated.
504 505 506 507
 */

isc_result_t
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 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542
 *\li	'name' to be valid and have NSEC or NSEC3 and associated RRSIG
 *	 rdatasets.
 */

isc_result_t
dns_rdataset_getclosest(dns_rdataset_t *rdataset, dns_name_t *name,
			dns_rdataset_t *nsec, dns_rdataset_t *nsecsig);
/*%<
 * Return the closest encloser for this record.
 *
 * Requires:
 *\li	'rdataset' to be valid and #DNS_RDATASETATTR_CLOSEST to be set.
 *\li	'name' to be valid.
 *\li	'nsec' and 'nsecsig' to be valid and not associated.
 */

isc_result_t
dns_rdataset_addclosest(dns_rdataset_t *rdataset, dns_name_t *name);
/*%<
 * Associate a closest encloset proof with this record.
 * Sets #DNS_RDATASETATTR_CLOSEST if successful.
 * Adjusts the 'rdataset->ttl' to minimum of the 'rdataset->ttl' and
 * the 'nsec' and 'rrsig(nsec)' ttl.
 *
 * Requires:
 *\li	'rdataset' to be valid and #DNS_RDATASETATTR_CLOSEST to be set.
 *\li	'name' to be valid and have NSEC3 and RRSIG(NSEC3) rdatasets.
543 544
 */

545 546 547 548 549 550 551 552 553 554 555 556
isc_result_t
dns_rdataset_getadditional(dns_rdataset_t *rdataset,
			   dns_rdatasetadditional_t type,
			   dns_rdatatype_t qtype,
			   dns_acache_t *acache,
			   dns_zone_t **zonep,
			   dns_db_t **dbp,
			   dns_dbversion_t **versionp,
			   dns_dbnode_t **nodep,
			   dns_name_t *fname,
			   dns_message_t *msg,
			   isc_stdtime_t now);
Mark Andrews's avatar
Mark Andrews committed
557
/*%<
558 559 560 561 562 563 564
 * Get cached additional information from the DB node for a particular
 * 'rdataset.'  'type' is one of dns_rdatasetadditional_fromauth,
 * dns_rdatasetadditional_fromcache, and dns_rdatasetadditional_fromglue,
 * which specifies the origin of the information.  'qtype' is intended to
 * be used for specifying a particular rdata type in the cached information.
 *
 * Requires:
Mark Andrews's avatar
Mark Andrews committed
565 566 567 568
 * \li	'rdataset' is a valid rdataset.
 * \li	'acache' can be NULL, in which case this function will simply return
 * 	ISC_R_FAILURE.
 * \li	For the other pointers, see dns_acache_getentry().
569 570
 *
 * Ensures:
Mark Andrews's avatar
Mark Andrews committed
571
 * \li	See dns_acache_getentry().
572 573
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
574 575 576
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_FAILURE	- additional information caching is not supported.
 * \li	#ISC_R_NOTFOUND	- the corresponding DB node has not cached additional
577
 *			  information for 'rdataset.'
Mark Andrews's avatar
Mark Andrews committed
578
 * \li	Any error that dns_acache_getentry() can return.
579 580 581 582 583 584 585 586 587 588 589 590
 */

isc_result_t
dns_rdataset_setadditional(dns_rdataset_t *rdataset,
			   dns_rdatasetadditional_t type,
			   dns_rdatatype_t qtype,
			   dns_acache_t *acache,
			   dns_zone_t *zone,
			   dns_db_t *db,
			   dns_dbversion_t *version,
			   dns_dbnode_t *node,
			   dns_name_t *fname);
Mark Andrews's avatar
Mark Andrews committed
591
/*%<
592 593 594 595 596
 * Set cached additional information to the DB node for a particular
 * 'rdataset.'  See dns_rdataset_getadditional for the semantics of 'type'
 * and 'qtype'.
 *
 * Requires:
Mark Andrews's avatar
Mark Andrews committed
597 598
 * \li	'rdataset' is a valid rdataset.
 * \li	'acache' can be NULL, in which case this function will simply return
599
 *	ISC_R_FAILURE.
Mark Andrews's avatar
Mark Andrews committed
600
 * \li	For the other pointers, see dns_acache_setentry().
601 602
 *
 * Ensures:
Mark Andrews's avatar
Mark Andrews committed
603
 * \li	See dns_acache_setentry().
604 605
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
606 607 608 609
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_FAILURE	- additional information caching is not supported.
 * \li	#ISC_R_NOMEMORY
 * \li	Any error that dns_acache_setentry() can return.
610 611 612 613 614 615 616
 */

isc_result_t
dns_rdataset_putadditional(dns_acache_t *acache,
			   dns_rdataset_t *rdataset,
			   dns_rdatasetadditional_t type,
			   dns_rdatatype_t qtype);
Mark Andrews's avatar
Mark Andrews committed
617
/*%<
618 619 620 621 622
 * Discard cached additional information stored in the DB node for a particular
 * 'rdataset.'  See dns_rdataset_getadditional for the semantics of 'type'
 * and 'qtype'.
 *
 * Requires:
Mark Andrews's avatar
Mark Andrews committed
623 624
 * \li	'rdataset' is a valid rdataset.
 * \li	'acache' can be NULL, in which case this function will simply return
625 626 627
 *	ISC_R_FAILURE.
 *
 * Ensures:
Mark Andrews's avatar
Mark Andrews committed
628
 * \li	See dns_acache_cancelentry().
629 630
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
631 632 633
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_FAILURE	- additional information caching is not supported.
 * \li	#ISC_R_NOTFOUND	- the corresponding DB node has not cached additional
634 635 636
 *			  information for 'rdataset.'
 */

Bob Halley's avatar
Bob Halley committed
637 638
ISC_LANG_ENDDECLS

Bob Halley's avatar
Bob Halley committed
639
#endif /* DNS_RDATASET_H */