/contrib/bind9/lib/dns/include/dns/ncache.h

  1/*
  2 * Copyright (C) 2004-2010  Internet Systems Consortium, Inc. ("ISC")
  3 * Copyright (C) 1999-2002  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: ncache.h,v 1.29 2010/05/14 23:50:40 tbox Exp $ */
 19
 20#ifndef DNS_NCACHE_H
 21#define DNS_NCACHE_H 1
 22
 23/*****
 24 ***** Module Info
 25 *****/
 26
 27/*! \file dns/ncache.h
 28 *\brief
 29 * DNS Ncache
 30 *
 31 * XXX TBS XXX
 32 *
 33 * MP:
 34 *\li	The caller must ensure any required synchronization.
 35 *
 36 * Reliability:
 37 *\li	No anticipated impact.
 38 *
 39 * Resources:
 40 *\li	TBS
 41 *
 42 * Security:
 43 *\li	No anticipated impact.
 44 *
 45 * Standards:
 46 *\li	RFC2308
 47 */
 48
 49#include <isc/lang.h>
 50#include <isc/stdtime.h>
 51
 52#include <dns/types.h>
 53
 54ISC_LANG_BEGINDECLS
 55
 56/*%
 57 * _OMITDNSSEC:
 58 *      Omit DNSSEC records when rendering.
 59 */
 60#define DNS_NCACHETOWIRE_OMITDNSSEC   0x0001
 61
 62isc_result_t
 63dns_ncache_add(dns_message_t *message, dns_db_t *cache, dns_dbnode_t *node,
 64	       dns_rdatatype_t covers, isc_stdtime_t now, dns_ttl_t maxttl,
 65	       dns_rdataset_t *addedrdataset);
 66isc_result_t
 67dns_ncache_addoptout(dns_message_t *message, dns_db_t *cache,
 68		     dns_dbnode_t *node, dns_rdatatype_t covers,
 69		     isc_stdtime_t now, dns_ttl_t maxttl,
 70		     isc_boolean_t optout, dns_rdataset_t *addedrdataset);
 71/*%<
 72 * Convert the authority data from 'message' into a negative cache
 73 * rdataset, and store it in 'cache' at 'node' with a TTL limited to
 74 * 'maxttl'.
 75 *
 76 * The 'covers' argument is the RR type whose nonexistence we are caching,
 77 * or dns_rdatatype_any when caching a NXDOMAIN response.
 78 *
 79 * 'optout' indicates a DNS_RDATASETATTR_OPTOUT should be set.
 80 *
 81 * Note:
 82 *\li	If 'addedrdataset' is not NULL, then it will be attached to the added
 83 *	rdataset.  See dns_db_addrdataset() for more details.
 84 *
 85 * Requires:
 86 *\li	'message' is a valid message with a properly formatting negative cache
 87 *	authority section.
 88 *
 89 *\li	The requirements of dns_db_addrdataset() apply to 'cache', 'node',
 90 *	'now', and 'addedrdataset'.
 91 *
 92 * Returns:
 93 *\li	#ISC_R_SUCCESS
 94 *\li	#ISC_R_NOSPACE
 95 *
 96 *\li	Any result code of dns_db_addrdataset() is a possible result code
 97 *	of dns_ncache_add().
 98 */
 99
100isc_result_t
101dns_ncache_towire(dns_rdataset_t *rdataset, dns_compress_t *cctx,
102		  isc_buffer_t *target, unsigned int options,
103		  unsigned int *countp);
104/*%<
105 * Convert the negative caching rdataset 'rdataset' to wire format,
106 * compressing names as specified in 'cctx', and storing the result in
107 * 'target'.  If 'omit_dnssec' is set, DNSSEC records will not
108 * be added to 'target'.
109 *
110 * Notes:
111 *\li	The number of RRs added to target will be added to *countp.
112 *
113 * Requires:
114 *\li	'rdataset' is a valid negative caching rdataset.
115 *
116 *\li	'rdataset' is not empty.
117 *
118 *\li	'countp' is a valid pointer.
119 *
120 * Ensures:
121 *\li	On a return of ISC_R_SUCCESS, 'target' contains a wire format
122 *	for the data contained in 'rdataset'.  Any error return leaves
123 *	the buffer unchanged.
124 *
125 *\li	*countp has been incremented by the number of RRs added to
126 *	target.
127 *
128 * Returns:
129 *\li	#ISC_R_SUCCESS		- all ok
130 *\li	#ISC_R_NOSPACE		- 'target' doesn't have enough room
131 *
132 *\li	Any error returned by dns_rdata_towire(), dns_rdataset_next(),
133 *	dns_name_towire().
134 */
135
136isc_result_t
137dns_ncache_getrdataset(dns_rdataset_t *ncacherdataset, dns_name_t *name,
138		       dns_rdatatype_t type, dns_rdataset_t *rdataset);
139/*%<
140 * Search the negative caching rdataset for an rdataset with the
141 * specified name and type.
142 *
143 * Requires:
144 *\li	'ncacherdataset' is a valid negative caching rdataset.
145 *
146 *\li	'ncacherdataset' is not empty.
147 *
148 *\li	'name' is a valid name.
149 *
150 *\li	'type' is not SIG, or a meta-RR type.
151 *
152 *\li	'rdataset' is a valid disassociated rdataset.
153 *
154 * Ensures:
155 *\li	On a return of ISC_R_SUCCESS, 'rdataset' is bound to the found
156 *	rdataset.
157 *
158 * Returns:
159 *\li	#ISC_R_SUCCESS		- the rdataset was found.
160 *\li	#ISC_R_NOTFOUND		- the rdataset was not found.
161 *
162 */
163
164isc_result_t
165dns_ncache_getsigrdataset(dns_rdataset_t *ncacherdataset, dns_name_t *name,
166			  dns_rdatatype_t covers, dns_rdataset_t *rdataset);
167/*%<
168 * Similar to dns_ncache_getrdataset() but get the rrsig that matches.
169 */
170
171void
172dns_ncache_current(dns_rdataset_t *ncacherdataset, dns_name_t *found,
173		   dns_rdataset_t *rdataset);
174
175/*%<
176 * Extract the current rdataset and name from a ncache entry.
177 *
178 * Requires:
179 * \li	'ncacherdataset' to be valid and to be a negative cache entry
180 * \li	'found' to be valid.
181 * \li	'rdataset' to be unassociated.
182 */
183
184ISC_LANG_ENDDECLS
185
186#endif /* DNS_NCACHE_H */