db.h 44.9 KB
Newer Older
Bob Halley's avatar
Bob Halley committed
1
/*
2
 * Copyright (C) 1999-2009, 2011-2017  Internet Systems Consortium, Inc. ("ISC")
3 4 5 6
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
Bob Halley's avatar
Bob Halley committed
7 8
 */

9
/* $Id$ */
David Lawrence's avatar
David Lawrence committed
10

Bob Halley's avatar
Bob Halley committed
11 12 13 14 15 16 17
#ifndef DNS_DB_H
#define DNS_DB_H 1

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

18
/*! \file dns/db.h
19
 * \brief
Bob Halley's avatar
Bob Halley committed
20
 * The DNS DB interface allows named rdatasets to be stored and retrieved.
Bob Halley's avatar
Bob Halley committed
21 22 23 24
 *
 * The dns_db_t type is like a "virtual class".  To actually use
 * DBs, an implementation of the class is required.
 *
25
 * XXX more XXX
Bob Halley's avatar
Bob Halley committed
26 27
 *
 * MP:
Mark Andrews's avatar
Mark Andrews committed
28
 * \li	The module ensures appropriate synchronization of data structures it
Bob Halley's avatar
Bob Halley committed
29
 *	creates and manipulates.
Bob Halley's avatar
Bob Halley committed
30 31
 *
 * Reliability:
Mark Andrews's avatar
Mark Andrews committed
32
 * \li	No anticipated impact.
Bob Halley's avatar
Bob Halley committed
33 34
 *
 * Resources:
Mark Andrews's avatar
Mark Andrews committed
35
 * \li	TBS
Bob Halley's avatar
Bob Halley committed
36 37
 *
 * Security:
Mark Andrews's avatar
Mark Andrews committed
38
 * \li	No anticipated impact.
Bob Halley's avatar
Bob Halley committed
39 40
 *
 * Standards:
Mark Andrews's avatar
Mark Andrews committed
41
 * \li	None.
Bob Halley's avatar
Bob Halley committed
42 43
 */

Bob Halley's avatar
Bob Halley committed
44 45 46 47
/*****
 ***** Imports
 *****/

48
#include <isc/lang.h>
49
#include <isc/magic.h>
50
#include <isc/ondestroy.h>
51
#include <isc/stats.h>
52
#include <isc/stdtime.h>
Bob Halley's avatar
Bob Halley committed
53

54
#include <dns/clientinfo.h>
55
#include <dns/fixedname.h>
Bob Halley's avatar
Bob Halley committed
56
#include <dns/name.h>
57 58
#include <dns/rdata.h>
#include <dns/rdataset.h>
59
#include <dns/types.h>
Bob Halley's avatar
Bob Halley committed
60

61 62
ISC_LANG_BEGINDECLS

Bob Halley's avatar
Bob Halley committed
63 64 65 66
/*****
 ***** Types
 *****/

Bob Halley's avatar
Bob Halley committed
67 68 69
typedef struct dns_dbmethods {
	void		(*attach)(dns_db_t *source, dns_db_t **targetp);
	void		(*detach)(dns_db_t **dbp);
70 71
	isc_result_t	(*beginload)(dns_db_t *db,
				     dns_rdatacallbacks_t *callbacks);
Tinderbox User's avatar
Tinderbox User committed
72
	isc_result_t	(*endload)(dns_db_t *db,
73 74 75
				     dns_rdatacallbacks_t *callbacks);
	isc_result_t	(*serialize)(dns_db_t *db,
				     dns_dbversion_t *version, FILE *file);
76
	isc_result_t	(*dump)(dns_db_t *db, dns_dbversion_t *version,
77 78
				const char *filename,
				dns_masterformat_t masterformat);
Bob Halley's avatar
Bob Halley committed
79 80
	void		(*currentversion)(dns_db_t *db,
					  dns_dbversion_t **versionp);
81
	isc_result_t	(*newversion)(dns_db_t *db,
Bob Halley's avatar
Bob Halley committed
82
				      dns_dbversion_t **versionp);
Bob Halley's avatar
Bob Halley committed
83 84
	void		(*attachversion)(dns_db_t *db, dns_dbversion_t *source,
					 dns_dbversion_t **targetp);
Bob Halley's avatar
Bob Halley committed
85
	void		(*closeversion)(dns_db_t *db,
Bob Halley's avatar
Bob Halley committed
86 87
					dns_dbversion_t **versionp,
					isc_boolean_t commit);
88
	isc_result_t	(*findnode)(dns_db_t *db, const dns_name_t *name,
Bob Halley's avatar
Bob Halley committed
89 90
				    isc_boolean_t create,
				    dns_dbnode_t **nodep);
91
	isc_result_t	(*find)(dns_db_t *db, const dns_name_t *name,
Bob Halley's avatar
Bob Halley committed
92 93
				dns_dbversion_t *version,
				dns_rdatatype_t type, unsigned int options,
94
				isc_stdtime_t now,
Bob Halley's avatar
Bob Halley committed
95
				dns_dbnode_t **nodep, dns_name_t *foundname,
Bob Halley's avatar
Bob Halley committed
96 97
				dns_rdataset_t *rdataset,
				dns_rdataset_t *sigrdataset);
98
	isc_result_t	(*findzonecut)(dns_db_t *db, const dns_name_t *name,
Bob Halley's avatar
Bob Halley committed
99 100 101 102 103
				       unsigned int options, isc_stdtime_t now,
				       dns_dbnode_t **nodep,
				       dns_name_t *foundname,
				       dns_rdataset_t *rdataset,
				       dns_rdataset_t *sigrdataset);
Bob Halley's avatar
Bob Halley committed
104 105 106 107 108
	void		(*attachnode)(dns_db_t *db,
				      dns_dbnode_t *source,
				      dns_dbnode_t **targetp);
	void		(*detachnode)(dns_db_t *db,
				      dns_dbnode_t **targetp);
109
	isc_result_t	(*expirenode)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
110
				      isc_stdtime_t now);
Bob Halley's avatar
Bob Halley committed
111 112
	void		(*printnode)(dns_db_t *db, dns_dbnode_t *node,
				     FILE *out);
113
	isc_result_t 	(*createiterator)(dns_db_t *db, unsigned int options,
Bob Halley's avatar
Bob Halley committed
114
					  dns_dbiterator_t **iteratorp);
115
	isc_result_t	(*findrdataset)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
116 117
					dns_dbversion_t *version,
					dns_rdatatype_t type,
Bob Halley's avatar
Bob Halley committed
118
					dns_rdatatype_t covers,
119
					isc_stdtime_t now,
Bob Halley's avatar
Bob Halley committed
120 121
					dns_rdataset_t *rdataset,
					dns_rdataset_t *sigrdataset);
122
	isc_result_t	(*allrdatasets)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
123
					dns_dbversion_t *version,
124
					isc_stdtime_t now,
Bob Halley's avatar
Bob Halley committed
125
					dns_rdatasetiter_t **iteratorp);
126
	isc_result_t	(*addrdataset)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
127
				       dns_dbversion_t *version,
128
				       isc_stdtime_t now,
129
				       dns_rdataset_t *rdataset,
Bob Halley's avatar
Bob Halley committed
130
				       unsigned int options,
131
				       dns_rdataset_t *addedrdataset);
132
	isc_result_t	(*subtractrdataset)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
133 134
					    dns_dbversion_t *version,
					    dns_rdataset_t *rdataset,
135
					    unsigned int options,
Bob Halley's avatar
Bob Halley committed
136
					    dns_rdataset_t *newrdataset);
137
	isc_result_t	(*deleterdataset)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
138
					  dns_dbversion_t *version,
139 140
					  dns_rdatatype_t type,
					  dns_rdatatype_t covers);
Bob Halley's avatar
Bob Halley committed
141
	isc_boolean_t	(*issecure)(dns_db_t *db);
142
	unsigned int	(*nodecount)(dns_db_t *db);
143
	isc_boolean_t	(*ispersistent)(dns_db_t *db);
Mark Andrews's avatar
Mark Andrews committed
144
	void		(*overmem)(dns_db_t *db, isc_boolean_t overmem);
145
	void		(*settask)(dns_db_t *db, isc_task_t *);
146
	isc_result_t	(*getoriginnode)(dns_db_t *db, dns_dbnode_t **nodep);
147
	void		(*transfernode)(dns_db_t *db, dns_dbnode_t **sourcep,
148
					dns_dbnode_t **targetp);
149 150 151 152 153 154 155
	isc_result_t    (*getnsec3parameters)(dns_db_t *db,
					      dns_dbversion_t *version,
					      dns_hash_t *hash,
					      isc_uint8_t *flags,
					      isc_uint16_t *iterations,
					      unsigned char *salt,
					      size_t *salt_len);
156
	isc_result_t    (*findnsec3node)(dns_db_t *db, const dns_name_t *name,
157 158
					 isc_boolean_t create,
					 dns_dbnode_t **nodep);
159 160 161 162 163 164 165 166 167
	isc_result_t	(*setsigningtime)(dns_db_t *db,
					  dns_rdataset_t *rdataset,
					  isc_stdtime_t resign);
	isc_result_t	(*getsigningtime)(dns_db_t *db,
					  dns_rdataset_t *rdataset,
					  dns_name_t *name);
	void		(*resigned)(dns_db_t *db, dns_rdataset_t *rdataset,
					   dns_dbversion_t *version);
	isc_boolean_t	(*isdnssec)(dns_db_t *db);
168
	dns_stats_t	*(*getrrsetstats)(dns_db_t *db);
169 170
	void		(*rpz_attach)(dns_db_t *db, void *rpzs,
				      isc_uint8_t rpz_num);
171
	isc_result_t	(*rpz_ready)(dns_db_t *db);
172
	isc_result_t	(*findnodeext)(dns_db_t *db, const dns_name_t *name,
173 174 175 176
				     isc_boolean_t create,
				     dns_clientinfomethods_t *methods,
				     dns_clientinfo_t *clientinfo,
				     dns_dbnode_t **nodep);
177
	isc_result_t	(*findext)(dns_db_t *db, const dns_name_t *name,
178 179 180 181 182 183 184 185
				   dns_dbversion_t *version,
				   dns_rdatatype_t type, unsigned int options,
				   isc_stdtime_t now,
				   dns_dbnode_t **nodep, dns_name_t *foundname,
				   dns_clientinfomethods_t *methods,
				   dns_clientinfo_t *clientinfo,
				   dns_rdataset_t *rdataset,
				   dns_rdataset_t *sigrdataset);
186
	isc_result_t	(*setcachestats)(dns_db_t *db, isc_stats_t *stats);
187
	size_t		(*hashsize)(dns_db_t *db);
188 189
	isc_result_t	(*nodefullname)(dns_db_t *db, dns_dbnode_t *node,
					dns_name_t *name);
190 191
	isc_result_t	(*getsize)(dns_db_t *db, dns_dbversion_t *version,
				   isc_uint64_t *records, isc_uint64_t *bytes);
Bob Halley's avatar
Bob Halley committed
192 193
} dns_dbmethods_t;

194
typedef isc_result_t
195
(*dns_dbcreatefunc_t)(isc_mem_t *mctx, const dns_name_t *name,
196 197 198
		      dns_dbtype_t type, dns_rdataclass_t rdclass,
		      unsigned int argc, char *argv[], void *driverarg,
		      dns_db_t **dbp);
Automatic Updater's avatar
Automatic Updater committed
199

200 201 202
typedef isc_result_t
(*dns_dbupdate_callback_t)(dns_db_t *db, void *fn_arg);

203
#define DNS_DB_MAGIC		ISC_MAGIC('D','N','S','D')
204
#define DNS_DB_VALID(db)	ISC_MAGIC_VALID(db, DNS_DB_MAGIC)
Bob Halley's avatar
Bob Halley committed
205

206
/*%
Bob Halley's avatar
Bob Halley committed
207
 * This structure is actually just the common prefix of a DNS db
Bob Halley's avatar
Bob Halley committed
208
 * implementation's version of a dns_db_t.
209
 * \brief
Bob Halley's avatar
Bob Halley committed
210 211
 * Direct use of this structure by clients is forbidden.  DB implementations
 * may change the structure.  'magic' must be DNS_DB_MAGIC for any of the
Bob Halley's avatar
Bob Halley committed
212 213
 * dns_db_ routines to work.  DB implementations must maintain all DB
 * invariants.
Bob Halley's avatar
Bob Halley committed
214 215
 */
struct dns_db {
216 217 218 219 220 221 222 223 224
	unsigned int				magic;
	unsigned int				impmagic;
	dns_dbmethods_t *			methods;
	isc_uint16_t				attributes;
	dns_rdataclass_t			rdclass;
	dns_name_t				origin;
	isc_ondestroy_t				ondest;
	isc_mem_t *				mctx;
	ISC_LIST(dns_dbonupdatelistener_t)	update_listeners;
Bob Halley's avatar
Bob Halley committed
225 226
};

Bob Halley's avatar
Bob Halley committed
227
#define DNS_DBATTR_CACHE		0x01
228
#define DNS_DBATTR_STUB			0x02
Bob Halley's avatar
Bob Halley committed
229

230 231 232 233 234 235
struct dns_dbonupdatelistener {
	dns_dbupdate_callback_t			onupdate;
	void *					onupdate_arg;
	ISC_LINK(dns_dbonupdatelistener_t)	link;
};

236 237
/*@{*/
/*%
Bob Halley's avatar
Bob Halley committed
238 239
 * Options that can be specified for dns_db_find().
 */
240 241 242 243 244 245 246 247 248
#define DNS_DBFIND_GLUEOK		0x0001
#define DNS_DBFIND_VALIDATEGLUE		0x0002
#define DNS_DBFIND_NOWILD		0x0004
#define DNS_DBFIND_PENDINGOK		0x0008
#define DNS_DBFIND_NOEXACT		0x0010
#define DNS_DBFIND_FORCENSEC		0x0020
#define DNS_DBFIND_COVERINGNSEC		0x0040
#define DNS_DBFIND_FORCENSEC3		0x0080
#define DNS_DBFIND_ADDITIONALOK		0x0100
249
#define DNS_DBFIND_NOZONECUT		0x0200
250
/*@}*/
Bob Halley's avatar
Bob Halley committed
251

252 253
/*@{*/
/*%
Bob Halley's avatar
Bob Halley committed
254
 * Options that can be specified for dns_db_addrdataset().
Bob Halley's avatar
Bob Halley committed
255
 */
Bob Halley's avatar
Bob Halley committed
256 257
#define DNS_DBADD_MERGE			0x01
#define DNS_DBADD_FORCE			0x02
258
#define DNS_DBADD_EXACT			0x04
259
#define DNS_DBADD_EXACTTTL		0x08
260
#define DNS_DBADD_PREFETCH		0x10
261
/*@}*/
Bob Halley's avatar
Bob Halley committed
262

263
/*%
264 265 266
 * Options that can be specified for dns_db_subtractrdataset().
 */
#define DNS_DBSUB_EXACT			0x01
267
#define DNS_DBSUB_WANTOLD		0x02
268

269 270 271 272 273 274 275 276 277
/*@{*/
/*%
 * Iterator options
 */
#define DNS_DB_RELATIVENAMES	0x1
#define DNS_DB_NSEC3ONLY	0x2
#define DNS_DB_NONSEC3		0x4
/*@}*/

Bob Halley's avatar
Bob Halley committed
278 279 280 281 282 283 284 285
/*****
 ***** Methods
 *****/

/***
 *** Basic DB Methods
 ***/

286
isc_result_t
287
dns_db_create(isc_mem_t *mctx, const char *db_type, const dns_name_t *origin,
288
	      dns_dbtype_t type, dns_rdataclass_t rdclass,
Bob Halley's avatar
Bob Halley committed
289
	      unsigned int argc, char *argv[], dns_db_t **dbp);
290
/*%<
Bob Halley's avatar
Bob Halley committed
291 292 293
 * Create a new database using implementation 'db_type'.
 *
 * Notes:
Mark Andrews's avatar
Mark Andrews committed
294
 * \li	All names in the database must be subdomains of 'origin' and in class
David Lawrence's avatar
David Lawrence committed
295 296
 *	'rdclass'.  The database makes its own copy of the origin, so the
 *	caller may do whatever they like with 'origin' and its storage once the
Bob Halley's avatar
Bob Halley committed
297 298
 *	call returns.
 *
Mark Andrews's avatar
Mark Andrews committed
299
 * \li	DB implementation-specific parameters are passed using argc and argv.
Bob Halley's avatar
Bob Halley committed
300 301 302
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
303
 * \li	dbp != NULL and *dbp == NULL
Bob Halley's avatar
Bob Halley committed
304
 *
Mark Andrews's avatar
Mark Andrews committed
305
 * \li	'origin' is a valid absolute domain name.
Bob Halley's avatar
Bob Halley committed
306
 *
Mark Andrews's avatar
Mark Andrews committed
307
 * \li	mctx is a valid memory context
Bob Halley's avatar
Bob Halley committed
308 309 310
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
311
 * \li	A copy of 'origin' has been made for the databases use, and the
Bob Halley's avatar
Bob Halley committed
312 313 314 315 316
 *	caller is free to do whatever they want with the name and storage
 *	associated with 'origin'.
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
317 318 319
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
 * \li	#ISC_R_NOTFOUND				db_type not found
Bob Halley's avatar
Bob Halley committed
320
 *
Mark Andrews's avatar
Mark Andrews committed
321
 * \li	Many other errors are possible, depending on what db_type was
Bob Halley's avatar
Bob Halley committed
322 323
 *	specified.
 */
Bob Halley's avatar
Bob Halley committed
324 325 326

void
dns_db_attach(dns_db_t *source, dns_db_t **targetp);
327
/*%<
Bob Halley's avatar
Bob Halley committed
328 329 330 331
 * Attach *targetp to source.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
332
 * \li	'source' is a valid database.
Bob Halley's avatar
Bob Halley committed
333
 *
Mark Andrews's avatar
Mark Andrews committed
334
 * \li	'targetp' points to a NULL dns_db_t *.
Bob Halley's avatar
Bob Halley committed
335 336 337
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
338
 * \li	*targetp is attached to source.
Bob Halley's avatar
Bob Halley committed
339
 */
Bob Halley's avatar
Bob Halley committed
340 341 342

void
dns_db_detach(dns_db_t **dbp);
343
/*%<
Bob Halley's avatar
Bob Halley committed
344 345 346 347
 * Detach *dbp from its database.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
348
 * \li	'dbp' points to a valid database.
Bob Halley's avatar
Bob Halley committed
349 350 351
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
352
 * \li	*dbp is NULL.
Bob Halley's avatar
Bob Halley committed
353
 *
Mark Andrews's avatar
Mark Andrews committed
354
 * \li	If '*dbp' is the last reference to the database,
355
 *		all resources used by the database will be freed
Bob Halley's avatar
Bob Halley committed
356
 */
Bob Halley's avatar
Bob Halley committed
357

358 359
isc_result_t
dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp);
360
/*%<
361 362 363
 * Causes 'eventp' to be sent to be sent to 'task' when the database is
 * destroyed.
 *
Mark Andrews's avatar
Mark Andrews committed
364
 * Note; ownership of the eventp is taken from the caller (and *eventp is
365 366 367 368
 * set to NULL). The sender field of the event is set to 'db' before it is
 * sent to the task.
 */

Bob Halley's avatar
Bob Halley committed
369 370
isc_boolean_t
dns_db_iscache(dns_db_t *db);
371
/*%<
Bob Halley's avatar
Bob Halley committed
372 373 374 375
 * Does 'db' have cache semantics?
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
376
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
377 378
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
379 380
 * \li	#ISC_TRUE	'db' has cache semantics
 * \li	#ISC_FALSE	otherwise
Bob Halley's avatar
Bob Halley committed
381
 */
Bob Halley's avatar
Bob Halley committed
382 383 384

isc_boolean_t
dns_db_iszone(dns_db_t *db);
385
/*%<
Bob Halley's avatar
Bob Halley committed
386 387
 * Does 'db' have zone semantics?
 *
388 389
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
390
 * \li	'db' is a valid database.
391 392
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
393 394
 * \li	#ISC_TRUE	'db' has zone semantics
 * \li	#ISC_FALSE	otherwise
395 396 397 398
 */

isc_boolean_t
dns_db_isstub(dns_db_t *db);
399
/*%<
400
 * Does 'db' have stub semantics?
Bob Halley's avatar
Bob Halley committed
401 402 403
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
404
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
405 406
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
407 408
 * \li	#ISC_TRUE	'db' has zone semantics
 * \li	#ISC_FALSE	otherwise
Bob Halley's avatar
Bob Halley committed
409
 */
Bob Halley's avatar
Bob Halley committed
410

Bob Halley's avatar
Bob Halley committed
411 412
isc_boolean_t
dns_db_issecure(dns_db_t *db);
413
/*%<
Bob Halley's avatar
Bob Halley committed
414 415 416 417
 * Is 'db' secure?
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
418
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
419 420
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
421 422
 * \li	#ISC_TRUE	'db' is secure.
 * \li	#ISC_FALSE	'db' is not secure.
Bob Halley's avatar
Bob Halley committed
423 424
 */

425 426 427 428 429 430 431 432 433 434 435 436 437 438
isc_boolean_t
dns_db_isdnssec(dns_db_t *db);
/*%<
 * Is 'db' secure or partially secure?
 *
 * Requires:
 *
 * \li	'db' is a valid database with zone semantics.
 *
 * Returns:
 * \li	#ISC_TRUE	'db' is secure or is partially.
 * \li	#ISC_FALSE	'db' is not secure.
 */

Bob Halley's avatar
Bob Halley committed
439 440
dns_name_t *
dns_db_origin(dns_db_t *db);
441
/*%<
Bob Halley's avatar
Bob Halley committed
442 443 444 445 446 447
 * The origin of the database.
 *
 * Note: caller must not try to change this name.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
448
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
449 450 451
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
452
 * \li	The origin of the database.
Bob Halley's avatar
Bob Halley committed
453
 */
Bob Halley's avatar
Bob Halley committed
454 455 456

dns_rdataclass_t
dns_db_class(dns_db_t *db);
457
/*%<
Bob Halley's avatar
Bob Halley committed
458 459 460 461
 * The class of the database.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
462
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
463 464 465
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
466
 * \li	The class of the database.
Bob Halley's avatar
Bob Halley committed
467
 */
Bob Halley's avatar
Bob Halley committed
468

469
isc_result_t
470
dns_db_beginload(dns_db_t *db, dns_rdatacallbacks_t *callbacks);
471
/*%<
Bob Halley's avatar
Bob Halley committed
472 473 474 475
 * Begin loading 'db'.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
476
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
477
 *
Mark Andrews's avatar
Mark Andrews committed
478
 * \li	This is the first attempt to load 'db'.
Bob Halley's avatar
Bob Halley committed
479
 *
480 481
 * \li  'callbacks' is a pointer to an initialized dns_rdatacallbacks_t
 *       structure.
Bob Halley's avatar
Bob Halley committed
482 483 484
 *
 * Ensures:
 *
485 486 487
 * \li	On success, callbacks->add will be a valid dns_addrdatasetfunc_t
 *      suitable for loading records into 'db' from a raw or text zone
 *      file. callbacks->add_private will be a valid DB load context
Tinderbox User's avatar
Tinderbox User committed
488
 *      which should be used as 'arg' when callbacks->add is called.
489
 *      callbacks->deserialize will be a valid dns_deserialize_func_t
Evan Hunt's avatar
Evan Hunt committed
490
 *      suitable for loading 'db' from a map format zone file.
Bob Halley's avatar
Bob Halley committed
491 492 493
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
494 495
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
496
 *
Mark Andrews's avatar
Mark Andrews committed
497
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
498 499 500
 *	implementation used, syntax errors in the master file, etc.
 */

501
isc_result_t
502
dns_db_endload(dns_db_t *db, dns_rdatacallbacks_t *callbacks);
503
/*%<
Bob Halley's avatar
Bob Halley committed
504 505 506 507
 * Finish loading 'db'.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
508
 * \li	'db' is a valid database that is being loaded.
Bob Halley's avatar
Bob Halley committed
509
 *
510 511 512
 * \li	'callbacks' is a valid dns_rdatacallbacks_t structure.
 *
 * \li	callbacks->add_private is not NULL and is a valid database load context.
Bob Halley's avatar
Bob Halley committed
513 514 515
 *
 * Ensures:
 *
516
 * \li	'callbacks' is returned to its state prior to calling dns_db_beginload()
Bob Halley's avatar
Bob Halley committed
517 518 519
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
520 521
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
522
 *
Mark Andrews's avatar
Mark Andrews committed
523
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
524 525 526
 *	implementation used, syntax errors in the master file, etc.
 */

527
isc_result_t
Bob Halley's avatar
Bob Halley committed
528
dns_db_load(dns_db_t *db, const char *filename);
529 530 531

isc_result_t
dns_db_load2(dns_db_t *db, const char *filename, dns_masterformat_t format);
532 533 534

isc_result_t
dns_db_load3(dns_db_t *db, const char *filename, dns_masterformat_t format,
Automatic Updater's avatar
Automatic Updater committed
535
	     unsigned int options);
536
/*%<
Bob Halley's avatar
Bob Halley committed
537 538
 * Load master file 'filename' into 'db'.
 *
Bob Halley's avatar
Bob Halley committed
539
 * Notes:
Mark Andrews's avatar
Mark Andrews committed
540
 * \li	This routine is equivalent to calling
Bob Halley's avatar
Bob Halley committed
541
 *
542
 *\code
Bob Halley's avatar
Bob Halley committed
543
 *		dns_db_beginload();
Bob Halley's avatar
Bob Halley committed
544
 *		dns_master_loadfile();
Bob Halley's avatar
Bob Halley committed
545
 *		dns_db_endload();
546
 *\endcode
Bob Halley's avatar
Bob Halley committed
547
 *
Bob Halley's avatar
Bob Halley committed
548 549
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
550
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
551
 *
Mark Andrews's avatar
Mark Andrews committed
552
 * \li	This is the first attempt to load 'db'.
Bob Halley's avatar
Bob Halley committed
553 554 555
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
556 557
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
558
 *
Mark Andrews's avatar
Mark Andrews committed
559
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
560 561 562
 *	implementation used, syntax errors in the master file, etc.
 */

Tinderbox User's avatar
Tinderbox User committed
563
isc_result_t
564 565
dns_db_serialize(dns_db_t *db, dns_dbversion_t *version, FILE *rbtfile);
/*%<
Evan Hunt's avatar
Evan Hunt committed
566
 * Dump version 'version' of 'db' to map-format file 'filename'.
567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582
 *
 * Requires:
 *
 * \li	'db' is a valid database.
 *
 * \li	'version' is a valid version.
 *
 * Returns:
 *
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
 *
 * \li	Other results are possible, depending upon the database
 *	implementation used, OS file errors, etc.
 */

583
isc_result_t
Bob Halley's avatar
Bob Halley committed
584
dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
585 586 587 588

isc_result_t
dns_db_dump2(dns_db_t *db, dns_dbversion_t *version, const char *filename,
	     dns_masterformat_t masterformat);
589
/*%<
590 591 592 593
 * Dump version 'version' of 'db' to master file 'filename'.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
594
 * \li	'db' is a valid database.
595
 *
Mark Andrews's avatar
Mark Andrews committed
596
 * \li	'version' is a valid version.
597 598 599
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
600 601
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
602
 *
Mark Andrews's avatar
Mark Andrews committed
603
 * \li	Other results are possible, depending upon the database
604 605 606
 *	implementation used, OS file errors, etc.
 */

Bob Halley's avatar
Bob Halley committed
607 608 609
/***
 *** Version Methods
 ***/
Bob Halley's avatar
Bob Halley committed
610

Bob Halley's avatar
Bob Halley committed
611 612
void
dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
613
/*%<
Bob Halley's avatar
Bob Halley committed
614 615 616 617
 * Open the current version for reading.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
618
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
619
 *
Mark Andrews's avatar
Mark Andrews committed
620
 * \li	versionp != NULL && *verisonp == NULL
Bob Halley's avatar
Bob Halley committed
621 622 623
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
624
 * \li	On success, '*versionp' is attached to the current version.
Bob Halley's avatar
Bob Halley committed
625 626
 *
 */
Bob Halley's avatar
Bob Halley committed
627

628
isc_result_t
Bob Halley's avatar
Bob Halley committed
629
dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
630
/*%<
Bob Halley's avatar
Bob Halley committed
631 632 633 634
 * Open a new version for reading and writing.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
635
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
636
 *
Mark Andrews's avatar
Mark Andrews committed
637
 * \li	versionp != NULL && *verisonp == NULL
Bob Halley's avatar
Bob Halley committed
638 639 640
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
641
 * \li	On success, '*versionp' is attached to the current version.
642
 *
Bob Halley's avatar
Bob Halley committed
643 644
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
645 646
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
647
 *
Mark Andrews's avatar
Mark Andrews committed
648
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
649 650
 *	implementation used.
 */
Bob Halley's avatar
Bob Halley committed
651

Bob Halley's avatar
Bob Halley committed
652 653 654
void
dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
		     dns_dbversion_t **targetp);
655
/*%<
Bob Halley's avatar
Bob Halley committed
656 657 658 659
 * Attach '*targetp' to 'source'.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
660
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
661
 *
Mark Andrews's avatar
Mark Andrews committed
662
 * \li	source is a valid open version
Bob Halley's avatar
Bob Halley committed
663
 *
Mark Andrews's avatar
Mark Andrews committed
664
 * \li	targetp != NULL && *targetp == NULL
Bob Halley's avatar
Bob Halley committed
665 666 667
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
668
 * \li	'*targetp' is attached to source.
Bob Halley's avatar
Bob Halley committed
669 670
 */

Bob Halley's avatar
Bob Halley committed
671
void
Bob Halley's avatar
Bob Halley committed
672 673
dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp,
		    isc_boolean_t commit);
674
/*%<
Bob Halley's avatar
Bob Halley committed
675 676 677 678
 * Close version '*versionp'.
 *
 * Note: if '*versionp' is a read-write version and 'commit' is ISC_TRUE,
 * then all changes made in the version will take effect, otherwise they
679
 * will be rolled back.  The value of 'commit' is ignored for read-only
Bob Halley's avatar
Bob Halley committed
680 681 682 683
 * versions.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
684
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
685
 *
Mark Andrews's avatar
Mark Andrews committed
686
 * \li	'*versionp' refers to a valid version.
Bob Halley's avatar
Bob Halley committed
687
 *
Mark Andrews's avatar
Mark Andrews committed
688
 * \li	If committing a writable version, then there must be no other
689 690 691
 *	outstanding references to the version (e.g. an active rdataset
 *	iterator).
 *
Bob Halley's avatar
Bob Halley committed
692 693
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
694
 * \li	*versionp == NULL
Bob Halley's avatar
Bob Halley committed
695
 *
Mark Andrews's avatar
Mark Andrews committed
696
 * \li	If *versionp is a read-write version, and commit is ISC_TRUE, then
697 698 699
 *	the version will become the current version.  If !commit, then all
 *	changes made in the version will be undone, and the version will
 *	not become the current version.
Bob Halley's avatar
Bob Halley committed
700 701
 */

Mark Andrews's avatar
Mark Andrews committed
702
/***
Bob Halley's avatar
Bob Halley committed
703 704
 *** Node Methods
 ***/
Bob Halley's avatar
Bob Halley committed
705

706
isc_result_t
707
dns_db_findnode(dns_db_t *db, const dns_name_t *name, isc_boolean_t create,
Bob Halley's avatar
Bob Halley committed
708
		dns_dbnode_t **nodep);
709 710

isc_result_t
711
dns_db_findnodeext(dns_db_t *db, const dns_name_t *name, isc_boolean_t create,
712 713
		   dns_clientinfomethods_t *methods,
		   dns_clientinfo_t *clientinfo, dns_dbnode_t **nodep);
714
/*%<
Bob Halley's avatar
Bob Halley committed
715 716
 * Find the node with name 'name'.
 *
717 718 719 720 721
 * dns_db_findnodeext() (findnode extended) also accepts parameters
 * 'methods' and 'clientinfo', which, when provided, enable the database to
 * retreive information about the client from the caller, and modify its
 * response on the basis of that information.
 *
Bob Halley's avatar
Bob Halley committed
722
 * Notes:
Mark Andrews's avatar
Mark Andrews committed
723
 * \li	If 'create' is ISC_TRUE and no node with name 'name' exists, then
Bob Halley's avatar
Bob Halley committed
724
 *	such a node will be created.
Bob Halley's avatar
Bob Halley committed
725
 *
Mark Andrews's avatar
Mark Andrews committed
726
 * \li	This routine is for finding or creating a node with the specified
Bob Halley's avatar
Bob Halley committed
727 728 729
 *	name.  There are no partial matches.  It is not suitable for use
 *	in building responses to ordinary DNS queries; clients which wish
 *	to do that should use dns_db_find() instead.
Bob Halley's avatar
Bob Halley committed
730 731 732
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
733
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
734
 *
Mark Andrews's avatar
Mark Andrews committed
735
 * \li	'name' is a valid, non-empty, absolute name.
Bob Halley's avatar
Bob Halley committed
736
 *
Mark Andrews's avatar
Mark Andrews committed
737
 * \li	nodep != NULL && *nodep == NULL
Bob Halley's avatar
Bob Halley committed
738 739 740
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
741
 * \li	On success, *nodep is attached to the node with name 'name'.
Bob Halley's avatar
Bob Halley committed
742 743 744
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
745 746
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOTFOUND			If !create and name not found.
747
 * \li	#ISC_R_NOMEMORY			Can only happen if create is ISC_TRUE.
Bob Halley's avatar
Bob Halley committed
748
 *
Mark Andrews's avatar
Mark Andrews committed
749
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
750 751
 *	implementation used.
 */
Bob Halley's avatar
Bob Halley committed
752

753
isc_result_t
754
dns_db_find(dns_db_t *db, const dns_name_t *name, dns_dbversion_t *version,
755
	    dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
Bob Halley's avatar
Bob Halley committed
756
	    dns_dbnode_t **nodep, dns_name_t *foundname,
Bob Halley's avatar
Bob Halley committed
757
	    dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
758 759

isc_result_t
760
dns_db_findext(dns_db_t *db, const dns_name_t *name, dns_dbversion_t *version,
761 762 763 764
	       dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
	       dns_dbnode_t **nodep, dns_name_t *foundname,
	       dns_clientinfomethods_t *methods, dns_clientinfo_t *clientinfo,
	       dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
765
/*%<
766 767
 * Find the best match for 'name' and 'type' in version 'version' of 'db'.
 *
768 769 770 771 772
 * dns_db_findext() (find extended) also accepts parameters 'methods'
 * and 'clientinfo', which when provided enable the database to retreive
 * information about the client from the caller, and modify its response
 * on the basis of this information.
 *
773 774
 * Notes:
 *
Mark Andrews's avatar
Mark Andrews committed
775
 * \li	If type == dns_rdataset_any, then rdataset will not be bound.
776
 *
Mark Andrews's avatar
Mark Andrews committed
777
 * \li	If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will
778
 *	be returned.  For zone databases, glue is as defined in RFC2181.
779 780
 *	For cache databases, glue is any rdataset with a trust of
 *	dns_trust_glue.
781
 *
782
 * \li	If 'options' does not have #DNS_DBFIND_ADDITIONALOK set, then no
Automatic Updater's avatar
Automatic Updater committed
783
 *	additional records will be returned.  Only caches can have
784 785
 *	rdataset with trust dns_trust_additional.
 *
Mark Andrews's avatar
Mark Andrews committed
786
 * \li	If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no
Bob Halley's avatar
Bob Halley committed
787 788 789
 *	pending data will be returned.  This option is only meaningful for
 *	cache databases.
 *
Mark Andrews's avatar
Mark Andrews committed
790
 * \li	If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will
791 792
 *	be disabled.  This option is only meaningful for zone databases.
 *
793 794 795 796 797 798 799 800 801
 * \li  If the #DNS_DBFIND_NOZONECUT option is set, the database is
 *	assumed to contain no zone cuts above 'name'.  An implementation
 *	may therefore choose to search for a match beginning at 'name'
 *	rather than walking down the tree to check check for delegations.
 *	If #DNS_DBFIND_NOWILD is not set, wildcard matching will be
 *	attempted at each node starting at the direct ancestor of 'name'
 *	and working up to the zone origin.  This option is only meaningful
 *	when querying redirect zones.
 *
Mark Andrews's avatar
Mark Andrews committed
802
 * \li	If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to
803
 *	have NSEC records, and these will be returned when appropriate.  This
804 805 806
 *	is only necessary when querying a database that was not secure
 *	when created.
 *