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

   1 /*
   2  * Copyright (C) 2004-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: db.h,v 1.93.50.5 2009/11/25 23:48:42 tbox Exp $ */
  19
  20 #ifndef DNS_DB_H
  21 #define DNS_DB_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file dns/db.h
  28  * \brief
  29  * The DNS DB interface allows named rdatasets to be stored and retrieved.
  30  *
  31  * The dns_db_t type is like a "virtual class".  To actually use
  32  * DBs, an implementation of the class is required.
  33  *
  34  * XXX more XXX
  35  *
  36  * MP:
  37  * \li  The module ensures appropriate synchronization of data structures it
  38  *      creates and manipulates.
  39  *
  40  * Reliability:
  41  * \li  No anticipated impact.
  42  *
  43  * Resources:
  44  * \li  TBS
  45  *
  46  * Security:
  47  * \li  No anticipated impact.
  48  *
  49  * Standards:
  50  * \li  None.
  51  */
  52
  53 /*****
  54  ***** Imports
  55  *****/
  56
  57 #include <isc/lang.h>
  58 #include <isc/magic.h>
  59 #include <isc/ondestroy.h>
  60 #include <isc/stdtime.h>
  61
  62 #include <dns/name.h>
  63 #include <dns/types.h>
  64
  65 ISC_LANG_BEGINDECLS
  66
  67 /*****
  68  ***** Types
  69  *****/
  70
  71 typedef struct dns_dbmethods {
  72         void            (*attach)(dns_db_t *source, dns_db_t **targetp);
  73         void            (*detach)(dns_db_t **dbp);
  74         isc_result_t    (*beginload)(dns_db_t *db, dns_addrdatasetfunc_t *addp,
  75                                      dns_dbload_t **dbloadp);
  76         isc_result_t    (*endload)(dns_db_t *db, dns_dbload_t **dbloadp);
  77         isc_result_t    (*dump)(dns_db_t *db, dns_dbversion_t *version,
  78                                 const char *filename,
  79                                 dns_masterformat_t masterformat);
  80         void            (*currentversion)(dns_db_t *db,
  81                                           dns_dbversion_t **versionp);
  82         isc_result_t    (*newversion)(dns_db_t *db,
  83                                       dns_dbversion_t **versionp);
  84         void            (*attachversion)(dns_db_t *db, dns_dbversion_t *source,
  85                                          dns_dbversion_t **targetp);
  86         void            (*closeversion)(dns_db_t *db,
  87                                         dns_dbversion_t **versionp,
  88                                         isc_boolean_t commit);
  89         isc_result_t    (*findnode)(dns_db_t *db, dns_name_t *name,
  90                                     isc_boolean_t create,
  91                                     dns_dbnode_t **nodep);
  92         isc_result_t    (*find)(dns_db_t *db, dns_name_t *name,
  93                                 dns_dbversion_t *version,
  94                                 dns_rdatatype_t type, unsigned int options,
  95                                 isc_stdtime_t now,
  96                                 dns_dbnode_t **nodep, dns_name_t *foundname,
  97                                 dns_rdataset_t *rdataset,
  98                                 dns_rdataset_t *sigrdataset);
  99         isc_result_t    (*findzonecut)(dns_db_t *db, dns_name_t *name,
 100                                        unsigned int options, isc_stdtime_t now,
 101                                        dns_dbnode_t **nodep,
 102                                        dns_name_t *foundname,
 103                                        dns_rdataset_t *rdataset,
 104                                        dns_rdataset_t *sigrdataset);
 105         void            (*attachnode)(dns_db_t *db,
 106                                       dns_dbnode_t *source,
 107                                       dns_dbnode_t **targetp);
 108         void            (*detachnode)(dns_db_t *db,
 109                                       dns_dbnode_t **targetp);
 110         isc_result_t    (*expirenode)(dns_db_t *db, dns_dbnode_t *node,
 111                                       isc_stdtime_t now);
 112         void            (*printnode)(dns_db_t *db, dns_dbnode_t *node,
 113                                      FILE *out);
 114         isc_result_t    (*createiterator)(dns_db_t *db, unsigned int options,
 115                                           dns_dbiterator_t **iteratorp);
 116         isc_result_t    (*findrdataset)(dns_db_t *db, dns_dbnode_t *node,
 117                                         dns_dbversion_t *version,
 118                                         dns_rdatatype_t type,
 119                                         dns_rdatatype_t covers,
 120                                         isc_stdtime_t now,
 121                                         dns_rdataset_t *rdataset,
 122                                         dns_rdataset_t *sigrdataset);
 123         isc_result_t    (*allrdatasets)(dns_db_t *db, dns_dbnode_t *node,
 124                                         dns_dbversion_t *version,
 125                                         isc_stdtime_t now,
 126                                         dns_rdatasetiter_t **iteratorp);
 127         isc_result_t    (*addrdataset)(dns_db_t *db, dns_dbnode_t *node,
 128                                        dns_dbversion_t *version,
 129                                        isc_stdtime_t now,
 130                                        dns_rdataset_t *rdataset,
 131                                        unsigned int options,
 132                                        dns_rdataset_t *addedrdataset);
 133         isc_result_t    (*subtractrdataset)(dns_db_t *db, dns_dbnode_t *node,
 134                                             dns_dbversion_t *version,
 135                                             dns_rdataset_t *rdataset,
 136                                             unsigned int options,
 137                                             dns_rdataset_t *newrdataset);
 138         isc_result_t    (*deleterdataset)(dns_db_t *db, dns_dbnode_t *node,
 139                                           dns_dbversion_t *version,
 140                                           dns_rdatatype_t type,
 141                                           dns_rdatatype_t covers);
 142         isc_boolean_t   (*issecure)(dns_db_t *db);
 143         unsigned int    (*nodecount)(dns_db_t *db);
 144         isc_boolean_t   (*ispersistent)(dns_db_t *db);
 145         void            (*overmem)(dns_db_t *db, isc_boolean_t overmem);
 146         void            (*settask)(dns_db_t *db, isc_task_t *);
 147         isc_result_t    (*getoriginnode)(dns_db_t *db, dns_dbnode_t **nodep);
 148         void            (*transfernode)(dns_db_t *db, dns_dbnode_t **sourcep,
 149                                         dns_dbnode_t **targetp);
 150         isc_result_t    (*getnsec3parameters)(dns_db_t *db,
 151                                               dns_dbversion_t *version,
 152                                               dns_hash_t *hash,
 153                                               isc_uint8_t *flags,
 154                                               isc_uint16_t *iterations,
 155                                               unsigned char *salt,
 156                                               size_t *salt_len);
 157         isc_result_t    (*findnsec3node)(dns_db_t *db, dns_name_t *name,
 158                                          isc_boolean_t create,
 159                                          dns_dbnode_t **nodep);
 160         isc_result_t    (*setsigningtime)(dns_db_t *db,
 161                                           dns_rdataset_t *rdataset,
 162                                           isc_stdtime_t resign);
 163         isc_result_t    (*getsigningtime)(dns_db_t *db,
 164                                           dns_rdataset_t *rdataset,
 165                                           dns_name_t *name);
 166         void            (*resigned)(dns_db_t *db, dns_rdataset_t *rdataset,
 167                                            dns_dbversion_t *version);
 168         isc_boolean_t   (*isdnssec)(dns_db_t *db);
 169         dns_stats_t     *(*getrrsetstats)(dns_db_t *db);
 170 } dns_dbmethods_t;
 171
 172 typedef isc_result_t
 173 (*dns_dbcreatefunc_t)(isc_mem_t *mctx, dns_name_t *name,
 174                       dns_dbtype_t type, dns_rdataclass_t rdclass,
 175                       unsigned int argc, char *argv[], void *driverarg,
 176                       dns_db_t **dbp);
 177
 178 #define DNS_DB_MAGIC            ISC_MAGIC('D','N','S','D')
 179 #define DNS_DB_VALID(db)        ISC_MAGIC_VALID(db, DNS_DB_MAGIC)
 180
 181 /*%
 182  * This structure is actually just the common prefix of a DNS db
 183  * implementation's version of a dns_db_t.
 184  * \brief
 185  * Direct use of this structure by clients is forbidden.  DB implementations
 186  * may change the structure.  'magic' must be DNS_DB_MAGIC for any of the
 187  * dns_db_ routines to work.  DB implementations must maintain all DB
 188  * invariants.
 189  */
 190 struct dns_db {
 191         unsigned int                    magic;
 192         unsigned int                    impmagic;
 193         dns_dbmethods_t *               methods;
 194         isc_uint16_t                    attributes;
 195         dns_rdataclass_t                rdclass;
 196         dns_name_t                      origin;
 197         isc_ondestroy_t                 ondest;
 198         isc_mem_t *                     mctx;
 199 };
 200
 201 #define DNS_DBATTR_CACHE                0x01
 202 #define DNS_DBATTR_STUB                 0x02
 203
 204 /*@{*/
 205 /*%
 206  * Options that can be specified for dns_db_find().
 207  */
 208 #define DNS_DBFIND_GLUEOK               0x0001
 209 #define DNS_DBFIND_VALIDATEGLUE         0x0002
 210 #define DNS_DBFIND_NOWILD               0x0004
 211 #define DNS_DBFIND_PENDINGOK            0x0008
 212 #define DNS_DBFIND_NOEXACT              0x0010
 213 #define DNS_DBFIND_FORCENSEC            0x0020
 214 #define DNS_DBFIND_COVERINGNSEC         0x0040
 215 #define DNS_DBFIND_FORCENSEC3           0x0080
 216 #define DNS_DBFIND_ADDITIONALOK         0x0100
 217 /*@}*/
 218
 219 /*@{*/
 220 /*%
 221  * Options that can be specified for dns_db_addrdataset().
 222  */
 223 #define DNS_DBADD_MERGE                 0x01
 224 #define DNS_DBADD_FORCE                 0x02
 225 #define DNS_DBADD_EXACT                 0x04
 226 #define DNS_DBADD_EXACTTTL              0x08
 227 /*@}*/
 228
 229 /*%
 230  * Options that can be specified for dns_db_subtractrdataset().
 231  */
 232 #define DNS_DBSUB_EXACT                 0x01
 233
 234 /*@{*/
 235 /*%
 236  * Iterator options
 237  */
 238 #define DNS_DB_RELATIVENAMES    0x1
 239 #define DNS_DB_NSEC3ONLY        0x2
 240 #define DNS_DB_NONSEC3          0x4
 241 /*@}*/
 242
 243 /*****
 244  ***** Methods
 245  *****/
 246
 247 /***
 248  *** Basic DB Methods
 249  ***/
 250
 251 isc_result_t
 252 dns_db_create(isc_mem_t *mctx, const char *db_type, dns_name_t *origin,
 253               dns_dbtype_t type, dns_rdataclass_t rdclass,
 254               unsigned int argc, char *argv[], dns_db_t **dbp);
 255 /*%<
 256  * Create a new database using implementation 'db_type'.
 257  *
 258  * Notes:
 259  * \li  All names in the database must be subdomains of 'origin' and in class
 260  *      'rdclass'.  The database makes its own copy of the origin, so the
 261  *      caller may do whatever they like with 'origin' and its storage once the
 262  *      call returns.
 263  *
 264  * \li  DB implementation-specific parameters are passed using argc and argv.
 265  *
 266  * Requires:
 267  *
 268  * \li  dbp != NULL and *dbp == NULL
 269  *
 270  * \li  'origin' is a valid absolute domain name.
 271  *
 272  * \li  mctx is a valid memory context
 273  *
 274  * Ensures:
 275  *
 276  * \li  A copy of 'origin' has been made for the databases use, and the
 277  *      caller is free to do whatever they want with the name and storage
 278  *      associated with 'origin'.
 279  *
 280  * Returns:
 281  *
 282  * \li  #ISC_R_SUCCESS
 283  * \li  #ISC_R_NOMEMORY
 284  * \li  #ISC_R_NOTFOUND                         db_type not found
 285  *
 286  * \li  Many other errors are possible, depending on what db_type was
 287  *      specified.
 288  */
 289
 290 void
 291 dns_db_attach(dns_db_t *source, dns_db_t **targetp);
 292 /*%<
 293  * Attach *targetp to source.
 294  *
 295  * Requires:
 296  *
 297  * \li  'source' is a valid database.
 298  *
 299  * \li  'targetp' points to a NULL dns_db_t *.
 300  *
 301  * Ensures:
 302  *
 303  * \li  *targetp is attached to source.
 304  */
 305
 306 void
 307 dns_db_detach(dns_db_t **dbp);
 308 /*%<
 309  * Detach *dbp from its database.
 310  *
 311  * Requires:
 312  *
 313  * \li  'dbp' points to a valid database.
 314  *
 315  * Ensures:
 316  *
 317  * \li  *dbp is NULL.
 318  *
 319  * \li  If '*dbp' is the last reference to the database,
 320  *              all resources used by the database will be freed
 321  */
 322
 323 isc_result_t
 324 dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp);
 325 /*%<
 326  * Causes 'eventp' to be sent to be sent to 'task' when the database is
 327  * destroyed.
 328  *
 329  * Note; ownership of the eventp is taken from the caller (and *eventp is
 330  * set to NULL). The sender field of the event is set to 'db' before it is
 331  * sent to the task.
 332  */
 333
 334 isc_boolean_t
 335 dns_db_iscache(dns_db_t *db);
 336 /*%<
 337  * Does 'db' have cache semantics?
 338  *
 339  * Requires:
 340  *
 341  * \li  'db' is a valid database.
 342  *
 343  * Returns:
 344  * \li  #ISC_TRUE       'db' has cache semantics
 345  * \li  #ISC_FALSE      otherwise
 346  */
 347
 348 isc_boolean_t
 349 dns_db_iszone(dns_db_t *db);
 350 /*%<
 351  * Does 'db' have zone semantics?
 352  *
 353  * Requires:
 354  *
 355  * \li  'db' is a valid database.
 356  *
 357  * Returns:
 358  * \li  #ISC_TRUE       'db' has zone semantics
 359  * \li  #ISC_FALSE      otherwise
 360  */
 361
 362 isc_boolean_t
 363 dns_db_isstub(dns_db_t *db);
 364 /*%<
 365  * Does 'db' have stub semantics?
 366  *
 367  * Requires:
 368  *
 369  * \li  'db' is a valid database.
 370  *
 371  * Returns:
 372  * \li  #ISC_TRUE       'db' has zone semantics
 373  * \li  #ISC_FALSE      otherwise
 374  */
 375
 376 isc_boolean_t
 377 dns_db_issecure(dns_db_t *db);
 378 /*%<
 379  * Is 'db' secure?
 380  *
 381  * Requires:
 382  *
 383  * \li  'db' is a valid database with zone semantics.
 384  *
 385  * Returns:
 386  * \li  #ISC_TRUE       'db' is secure.
 387  * \li  #ISC_FALSE      'db' is not secure.
 388  */
 389
 390 isc_boolean_t
 391 dns_db_isdnssec(dns_db_t *db);
 392 /*%<
 393  * Is 'db' secure or partially secure?
 394  *
 395  * Requires:
 396  *
 397  * \li  'db' is a valid database with zone semantics.
 398  *
 399  * Returns:
 400  * \li  #ISC_TRUE       'db' is secure or is partially.
 401  * \li  #ISC_FALSE      'db' is not secure.
 402  */
 403
 404 dns_name_t *
 405 dns_db_origin(dns_db_t *db);
 406 /*%<
 407  * The origin of the database.
 408  *
 409  * Note: caller must not try to change this name.
 410  *
 411  * Requires:
 412  *
 413  * \li  'db' is a valid database.
 414  *
 415  * Returns:
 416  *
 417  * \li  The origin of the database.
 418  */
 419
 420 dns_rdataclass_t
 421 dns_db_class(dns_db_t *db);
 422 /*%<
 423  * The class of the database.
 424  *
 425  * Requires:
 426  *
 427  * \li  'db' is a valid database.
 428  *
 429  * Returns:
 430  *
 431  * \li  The class of the database.
 432  */
 433
 434 isc_result_t
 435 dns_db_beginload(dns_db_t *db, dns_addrdatasetfunc_t *addp,
 436                  dns_dbload_t **dbloadp);
 437 /*%<
 438  * Begin loading 'db'.
 439  *
 440  * Requires:
 441  *
 442  * \li  'db' is a valid database.
 443  *
 444  * \li  This is the first attempt to load 'db'.
 445  *
 446  * \li  addp != NULL && *addp == NULL
 447  *
 448  * \li  dbloadp != NULL && *dbloadp == NULL
 449  *
 450  * Ensures:
 451  *
 452  * \li  On success, *addp will be a valid dns_addrdatasetfunc_t suitable
 453  *      for loading 'db'.  *dbloadp will be a valid DB load context which
 454  *      should be used as 'arg' when *addp is called.
 455  *
 456  * Returns:
 457  *
 458  * \li  #ISC_R_SUCCESS
 459  * \li  #ISC_R_NOMEMORY
 460  *
 461  * \li  Other results are possible, depending upon the database
 462  *      implementation used, syntax errors in the master file, etc.
 463  */
 464
 465 isc_result_t
 466 dns_db_endload(dns_db_t *db, dns_dbload_t **dbloadp);
 467 /*%<
 468  * Finish loading 'db'.
 469  *
 470  * Requires:
 471  *
 472  * \li  'db' is a valid database that is being loaded.
 473  *
 474  * \li  dbloadp != NULL and *dbloadp is a valid database load context.
 475  *
 476  * Ensures:
 477  *
 478  * \li  *dbloadp == NULL
 479  *
 480  * Returns:
 481  *
 482  * \li  #ISC_R_SUCCESS
 483  * \li  #ISC_R_NOMEMORY
 484  *
 485  * \li  Other results are possible, depending upon the database
 486  *      implementation used, syntax errors in the master file, etc.
 487  */
 488
 489 isc_result_t
 490 dns_db_load(dns_db_t *db, const char *filename);
 491
 492 isc_result_t
 493 dns_db_load2(dns_db_t *db, const char *filename, dns_masterformat_t format);
 494 /*%<
 495  * Load master file 'filename' into 'db'.
 496  *
 497  * Notes:
 498  * \li  This routine is equivalent to calling
 499  *
 500  *\code
 501  *              dns_db_beginload();
 502  *              dns_master_loadfile();
 503  *              dns_db_endload();
 504  *\endcode
 505  *
 506  * Requires:
 507  *
 508  * \li  'db' is a valid database.
 509  *
 510  * \li  This is the first attempt to load 'db'.
 511  *
 512  * Returns:
 513  *
 514  * \li  #ISC_R_SUCCESS
 515  * \li  #ISC_R_NOMEMORY
 516  *
 517  * \li  Other results are possible, depending upon the database
 518  *      implementation used, syntax errors in the master file, etc.
 519  */
 520
 521 isc_result_t
 522 dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
 523
 524 isc_result_t
 525 dns_db_dump2(dns_db_t *db, dns_dbversion_t *version, const char *filename,
 526              dns_masterformat_t masterformat);
 527 /*%<
 528  * Dump version 'version' of 'db' to master file 'filename'.
 529  *
 530  * Requires:
 531  *
 532  * \li  'db' is a valid database.
 533  *
 534  * \li  'version' is a valid version.
 535  *
 536  * Returns:
 537  *
 538  * \li  #ISC_R_SUCCESS
 539  * \li  #ISC_R_NOMEMORY
 540  *
 541  * \li  Other results are possible, depending upon the database
 542  *      implementation used, OS file errors, etc.
 543  */
 544
 545 /***
 546  *** Version Methods
 547  ***/
 548
 549 void
 550 dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
 551 /*%<
 552  * Open the current version for reading.
 553  *
 554  * Requires:
 555  *
 556  * \li  'db' is a valid database with zone semantics.
 557  *
 558  * \li  versionp != NULL && *verisonp == NULL
 559  *
 560  * Ensures:
 561  *
 562  * \li  On success, '*versionp' is attached to the current version.
 563  *
 564  */
 565
 566 isc_result_t
 567 dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
 568 /*%<
 569  * Open a new version for reading and writing.
 570  *
 571  * Requires:
 572  *
 573  * \li  'db' is a valid database with zone semantics.
 574  *
 575  * \li  versionp != NULL && *verisonp == NULL
 576  *
 577  * Ensures:
 578  *
 579  * \li  On success, '*versionp' is attached to the current version.
 580  *
 581  * Returns:
 582  *
 583  * \li  #ISC_R_SUCCESS
 584  * \li  #ISC_R_NOMEMORY
 585  *
 586  * \li  Other results are possible, depending upon the database
 587  *      implementation used.
 588  */
 589
 590 void
 591 dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
 592                      dns_dbversion_t **targetp);
 593 /*%<
 594  * Attach '*targetp' to 'source'.
 595  *
 596  * Requires:
 597  *
 598  * \li  'db' is a valid database with zone semantics.
 599  *
 600  * \li  source is a valid open version
 601  *
 602  * \li  targetp != NULL && *targetp == NULL
 603  *
 604  * Ensures:
 605  *
 606  * \li  '*targetp' is attached to source.
 607  */
 608
 609 void
 610 dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp,
 611                     isc_boolean_t commit);
 612 /*%<
 613  * Close version '*versionp'.
 614  *
 615  * Note: if '*versionp' is a read-write version and 'commit' is ISC_TRUE,
 616  * then all changes made in the version will take effect, otherwise they
 617  * will be rolled back.  The value if 'commit' is ignored for read-only
 618  * versions.
 619  *
 620  * Requires:
 621  *
 622  * \li  'db' is a valid database with zone semantics.
 623  *
 624  * \li  '*versionp' refers to a valid version.
 625  *
 626  * \li  If committing a writable version, then there must be no other
 627  *      outstanding references to the version (e.g. an active rdataset
 628  *      iterator).
 629  *
 630  * Ensures:
 631  *
 632  * \li  *versionp == NULL
 633  *
 634  * \li  If *versionp is a read-write version, and commit is ISC_TRUE, then
 635  *      the version will become the current version.  If !commit, then all
 636  *      changes made in the version will be undone, and the version will
 637  *      not become the current version.
 638  */
 639
 640 /***
 641  *** Node Methods
 642  ***/
 643
 644 isc_result_t
 645 dns_db_findnode(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
 646                 dns_dbnode_t **nodep);
 647 /*%<
 648  * Find the node with name 'name'.
 649  *
 650  * Notes:
 651  * \li  If 'create' is ISC_TRUE and no node with name 'name' exists, then
 652  *      such a node will be created.
 653  *
 654  * \li  This routine is for finding or creating a node with the specified
 655  *      name.  There are no partial matches.  It is not suitable for use
 656  *      in building responses to ordinary DNS queries; clients which wish
 657  *      to do that should use dns_db_find() instead.
 658  *
 659  * Requires:
 660  *
 661  * \li  'db' is a valid database.
 662  *
 663  * \li  'name' is a valid, non-empty, absolute name.
 664  *
 665  * \li  nodep != NULL && *nodep == NULL
 666  *
 667  * Ensures:
 668  *
 669  * \li  On success, *nodep is attached to the node with name 'name'.
 670  *
 671  * Returns:
 672  *
 673  * \li  #ISC_R_SUCCESS
 674  * \li  #ISC_R_NOTFOUND                 If !create and name not found.
 675  * \li  #ISC_R_NOMEMORY                 Can only happen if create is ISC_TRUE.
 676  *
 677  * \li  Other results are possible, depending upon the database
 678  *      implementation used.
 679  */
 680
 681 isc_result_t
 682 dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version,
 683             dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
 684             dns_dbnode_t **nodep, dns_name_t *foundname,
 685             dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 686 /*%<
 687  * Find the best match for 'name' and 'type' in version 'version' of 'db'.
 688  *
 689  * Notes:
 690  *
 691  * \li  If type == dns_rdataset_any, then rdataset will not be bound.
 692  *
 693  * \li  If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will
 694  *      be returned.  For zone databases, glue is as defined in RFC2181.
 695  *      For cache databases, glue is any rdataset with a trust of
 696  *      dns_trust_glue.
 697  *
 698  * \li  If 'options' does not have #DNS_DBFIND_ADDITIONALOK set, then no
 699  *      additional records will be returned.  Only caches can have
 700  *      rdataset with trust dns_trust_additional.
 701  *
 702  * \li  If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no
 703  *      pending data will be returned.  This option is only meaningful for
 704  *      cache databases.
 705  *
 706  * \li  If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will
 707  *      be disabled.  This option is only meaningful for zone databases.
 708  *
 709  * \li  If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to
 710  *      have NSEC records, and these will be returned when appropriate.  This
 711  *      is only necessary when querying a database that was not secure
 712  *      when created.
 713  *
 714  * \li  If the DNS_DBFIND_COVERINGNSEC option is set, then look for a
 715  *      NSEC record that potentially covers 'name' if a answer cannot
 716  *      be found.  Note the returned NSEC needs to be checked to ensure
 717  *      that it is correct.  This only affects answers returned from the
 718  *      cache.
 719  *
 720  * \li  To respond to a query for SIG records, the caller should create a
 721  *      rdataset iterator and extract the signatures from each rdataset.
 722  *
 723  * \li  Making queries of type ANY with #DNS_DBFIND_GLUEOK is not recommended,
 724  *      because the burden of determining whether a given rdataset is valid
 725  *      glue or not falls upon the caller.
 726  *
 727  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
 728  *      cache database, an rdataset will not be found unless it expires after
 729  *      'now'.  Any ANY query will not match unless at least one rdataset at
 730  *      the node expires after 'now'.  If 'now' is zero, then the current time
 731  *      will be used.
 732  *
 733  * Requires:
 734  *
 735  * \li  'db' is a valid database.
 736  *
 737  * \li  'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT').
 738  *
 739  * \li  'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
 740  *
 741  * \li  'foundname' is a valid name with a dedicated buffer.
 742  *
 743  * \li  'rdataset' is NULL, or is a valid unassociated rdataset.
 744  *
 745  * Ensures,
 746  *      on a non-error completion:
 747  *
 748  *      \li     If nodep != NULL, then it is bound to the found node.
 749  *
 750  *      \li     If foundname != NULL, then it contains the full name of the
 751  *              found node.
 752  *
 753  *      \li     If rdataset != NULL and type != dns_rdatatype_any, then
 754  *              rdataset is bound to the found rdataset.
 755  *
 756  *      Non-error results are:
 757  *
 758  *      \li     #ISC_R_SUCCESS                  The desired node and type were
 759  *                                              found.
 760  *
 761  *      \li     #DNS_R_WILDCARD                 The desired node and type were
 762  *                                              found after performing
 763  *                                              wildcard matching.  This is
 764  *                                              only returned if the
 765  *                                              #DNS_DBFIND_INDICATEWILD
 766  *                                              option is set; otherwise
 767  *                                              #ISC_R_SUCCESS is returned.
 768  *
 769  *      \li     #DNS_R_GLUE                     The desired node and type were
 770  *                                              found, but are glue.  This
 771  *                                              result can only occur if
 772  *                                              the DNS_DBFIND_GLUEOK option
 773  *                                              is set.  This result can only
 774  *                                              occur if 'db' is a zone
 775  *                                              database.  If type ==
 776  *                                              dns_rdatatype_any, then the
 777  *                                              node returned may contain, or
 778  *                                              consist entirely of invalid
 779  *                                              glue (i.e. data occluded by a
 780  *                                              zone cut).  The caller must
 781  *                                              take care not to return invalid
 782  *                                              glue to a client.
 783  *
 784  *      \li     #DNS_R_DELEGATION               The data requested is beneath
 785  *                                              a zone cut.  node, foundname,
 786  *                                              and rdataset reference the
 787  *                                              NS RRset of the zone cut.
 788  *                                              If 'db' is a cache database,
 789  *                                              then this is the deepest known
 790  *                                              delegation.
 791  *
 792  *      \li     #DNS_R_ZONECUT                  type == dns_rdatatype_any, and
 793  *                                              the desired node is a zonecut.
 794  *                                              The caller must take care not
 795  *                                              to return inappropriate glue
 796  *                                              to a client.  This result can
 797  *                                              only occur if 'db' is a zone
 798  *                                              database and DNS_DBFIND_GLUEOK
 799  *                                              is set.
 800  *
 801  *      \li     #DNS_R_DNAME                    The data requested is beneath
 802  *                                              a DNAME.  node, foundname,
 803  *                                              and rdataset reference the
 804  *                                              DNAME RRset.
 805  *
 806  *      \li     #DNS_R_CNAME                    The rdataset requested was not
 807  *                                              found, but there is a CNAME
 808  *                                              at the desired name.  node,
 809  *                                              foundname, and rdataset
 810  *                                              reference the CNAME RRset.
 811  *
 812  *      \li     #DNS_R_NXDOMAIN                 The desired name does not
 813  *                                              exist.
 814  *
 815  *      \li     #DNS_R_NXRRSET                  The desired name exists, but
 816  *                                              the desired type does not.
 817  *
 818  *      \li     #ISC_R_NOTFOUND                 The desired name does not
 819  *                                              exist, and no delegation could
 820  *                                              be found.  This result can only
 821  *                                              occur if 'db' is a cache
 822  *                                              database.  The caller should
 823  *                                              use its nameserver(s) of last
 824  *                                              resort (e.g. root hints).
 825  *
 826  *      \li     #DNS_R_NCACHENXDOMAIN           The desired name does not
 827  *                                              exist.  'node' is bound to the
 828  *                                              cache node with the desired
 829  *                                              name, and 'rdataset' contains
 830  *                                              the negative caching proof.
 831  *
 832  *      \li     #DNS_R_NCACHENXRRSET            The desired type does not
 833  *                                              exist.  'node' is bound to the
 834  *                                              cache node with the desired
 835  *                                              name, and 'rdataset' contains
 836  *                                              the negative caching proof.
 837  *
 838  *      \li     #DNS_R_EMPTYNAME                The name exists but there is
 839  *                                              no data at the name.
 840  *
 841  *      \li     #DNS_R_COVERINGNSEC             The returned data is a NSEC
 842  *                                              that potentially covers 'name'.
 843  *
 844  *      Error results:
 845  *
 846  *      \li     #ISC_R_NOMEMORY
 847  *
 848  *      \li     #DNS_R_BADDB                    Data that is required to be
 849  *                                              present in the DB, e.g. an NSEC
 850  *                                              record in a secure zone, is not
 851  *                                              present.
 852  *
 853  *      \li     Other results are possible, and should all be treated as
 854  *              errors.
 855  */
 856
 857 isc_result_t
 858 dns_db_findzonecut(dns_db_t *db, dns_name_t *name,
 859                    unsigned int options, isc_stdtime_t now,
 860                    dns_dbnode_t **nodep, dns_name_t *foundname,
 861                    dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 862 /*%<
 863  * Find the deepest known zonecut which encloses 'name' in 'db'.
 864  *
 865  * Notes:
 866  *
 867  * \li  If the #DNS_DBFIND_NOEXACT option is set, then the zonecut returned
 868  *      (if any) will be the deepest known ancestor of 'name'.
 869  *
 870  * \li  If 'now' is zero, then the current time will be used.
 871  *
 872  * Requires:
 873  *
 874  * \li  'db' is a valid database with cache semantics.
 875  *
 876  * \li  'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
 877  *
 878  * \li  'foundname' is a valid name with a dedicated buffer.
 879  *
 880  * \li  'rdataset' is NULL, or is a valid unassociated rdataset.
 881  *
 882  * Ensures, on a non-error completion:
 883  *
 884  * \li  If nodep != NULL, then it is bound to the found node.
 885  *
 886  * \li  If foundname != NULL, then it contains the full name of the
 887  *      found node.
 888  *
 889  * \li  If rdataset != NULL and type != dns_rdatatype_any, then
 890  *      rdataset is bound to the found rdataset.
 891  *
 892  * Non-error results are:
 893  *
 894  * \li  #ISC_R_SUCCESS
 895  *
 896  * \li  #ISC_R_NOTFOUND
 897  *
 898  * \li  Other results are possible, and should all be treated as
 899  *      errors.
 900  */
 901
 902 void
 903 dns_db_attachnode(dns_db_t *db, dns_dbnode_t *source, dns_dbnode_t **targetp);
 904 /*%<
 905  * Attach *targetp to source.
 906  *
 907  * Requires:
 908  *
 909  * \li  'db' is a valid database.
 910  *
 911  * \li  'source' is a valid node.
 912  *
 913  * \li  'targetp' points to a NULL dns_dbnode_t *.
 914  *
 915  * Ensures:
 916  *
 917  * \li  *targetp is attached to source.
 918  */
 919
 920 void
 921 dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep);
 922 /*%<
 923  * Detach *nodep from its node.
 924  *
 925  * Requires:
 926  *
 927  * \li  'db' is a valid database.
 928  *
 929  * \li  'nodep' points to a valid node.
 930  *
 931  * Ensures:
 932  *
 933  * \li  *nodep is NULL.
 934  */
 935
 936 void
 937 dns_db_transfernode(dns_db_t *db, dns_dbnode_t **sourcep,
 938                     dns_dbnode_t **targetp);
 939 /*%<
 940  * Transfer a node between pointer.
 941  *
 942  * This is equivalent to calling dns_db_attachnode() then dns_db_detachnode().
 943  *
 944  * Requires:
 945  *
 946  * \li  'db' is a valid database.
 947  *
 948  * \li  '*sourcep' is a valid node.
 949  *
 950  * \li  'targetp' points to a NULL dns_dbnode_t *.
 951  *
 952  * Ensures:
 953  *
 954  * \li  '*sourcep' is NULL.
 955  */
 956
 957 isc_result_t
 958 dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now);
 959 /*%<
 960  * Mark as stale all records at 'node' which expire at or before 'now'.
 961  *
 962  * Note: if 'now' is zero, then the current time will be used.
 963  *
 964  * Requires:
 965  *
 966  * \li  'db' is a valid cache database.
 967  *
 968  * \li  'node' is a valid node.
 969  */
 970
 971 void
 972 dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out);
 973 /*%<
 974  * Print a textual representation of the contents of the node to
 975  * 'out'.
 976  *
 977  * Note: this function is intended for debugging, not general use.
 978  *
 979  * Requires:
 980  *
 981  * \li  'db' is a valid database.
 982  *
 983  * \li  'node' is a valid node.
 984  */
 985
 986 /***
 987  *** DB Iterator Creation
 988  ***/
 989
 990 isc_result_t
 991 dns_db_createiterator(dns_db_t *db, unsigned int options,
 992                       dns_dbiterator_t **iteratorp);
 993 /*%<
 994  * Create an iterator for version 'version' of 'db'.
 995  *
 996  * Notes:
 997  *
 998  * \li  One or more of the following options can be set.
 999  *      #DNS_DB_RELATIVENAMES
1000  *      #DNS_DB_NSEC3ONLY
1001  *      #DNS_DB_NONSEC3
1002  *
1003  * Requires:
1004  *
1005  * \li  'db' is a valid database.
1006  *
1007  * \li  iteratorp != NULL && *iteratorp == NULL
1008  *
1009  * Ensures:
1010  *
1011  * \li  On success, *iteratorp will be a valid database iterator.
1012  *
1013  * Returns:
1014  *
1015  * \li  #ISC_R_SUCCESS
1016  * \li  #ISC_R_NOMEMORY
1017  */
1018
1019 /***
1020  *** Rdataset Methods
1021  ***/
1022
1023 /*
1024  * XXXRTH  Should we check for glue and pending data in dns_db_findrdataset()?
1025  */
1026
1027 isc_result_t
1028 dns_db_findrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1029                     dns_rdatatype_t type, dns_rdatatype_t covers,
1030                     isc_stdtime_t now, dns_rdataset_t *rdataset,
1031                     dns_rdataset_t *sigrdataset);
1032 /*%<
1033  * Search for an rdataset of type 'type' at 'node' that are in version
1034  * 'version' of 'db'.  If found, make 'rdataset' refer to it.
1035  *
1036  * Notes:
1037  *
1038  * \li  If 'version' is NULL, then the current version will be used.
1039  *
1040  * \li  Care must be used when using this routine to build a DNS response:
1041  *      'node' should have been found with dns_db_find(), not
1042  *      dns_db_findnode().  No glue checking is done.  No checking for
1043  *      pending data is done.
1044  *
1045  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
1046  *      cache database, an rdataset will not be found unless it expires after
1047  *      'now'.  If 'now' is zero, then the current time will be used.
1048  *
1049  * Requires:
1050  *
1051  * \li  'db' is a valid database.
1052  *
1053  * \li  'node' is a valid node.
1054  *
1055  * \li  'rdataset' is a valid, disassociated rdataset.
1056  *
1057  * \li  'sigrdataset' is a valid, disassociated rdataset, or it is NULL.
1058  *
1059  * \li  If 'covers' != 0, 'type' must be SIG.
1060  *
1061  * \li  'type' is not a meta-RR type such as 'ANY' or 'OPT'.
1062  *
1063  * Ensures:
1064  *
1065  * \li  On success, 'rdataset' is associated with the found rdataset.
1066  *
1067  * Returns:
1068  *
1069  * \li  #ISC_R_SUCCESS
1070  * \li  #ISC_R_NOTFOUND
1071  *
1072  * \li  Other results are possible, depending upon the database
1073  *      implementation used.
1074  */
1075
1076 isc_result_t
1077 dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1078                     isc_stdtime_t now, dns_rdatasetiter_t **iteratorp);
1079 /*%<
1080  * Make '*iteratorp' an rdataset iterator for all rdatasets at 'node' in
1081  * version 'version' of 'db'.
1082  *
1083  * Notes:
1084  *
1085  * \li  If 'version' is NULL, then the current version will be used.
1086  *
1087  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
1088  *      cache database, an rdataset will not be found unless it expires after
1089  *      'now'.  Any ANY query will not match unless at least one rdataset at
1090  *      the node expires after 'now'.  If 'now' is zero, then the current time
1091  *      will be used.
1092  *
1093  * Requires:
1094  *
1095  * \li  'db' is a valid database.
1096  *
1097  * \li  'node' is a valid node.
1098  *
1099  * \li  iteratorp != NULL && *iteratorp == NULL
1100  *
1101  * Ensures:
1102  *
1103  * \li  On success, '*iteratorp' is a valid rdataset iterator.
1104  *
1105  * Returns:
1106  *
1107  * \li  #ISC_R_SUCCESS
1108  * \li  #ISC_R_NOTFOUND
1109  *
1110  * \li  Other results are possible, depending upon the database
1111  *      implementation used.
1112  */
1113
1114 isc_result_t
1115 dns_db_addrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1116                    isc_stdtime_t now, dns_rdataset_t *rdataset,
1117                    unsigned int options, dns_rdataset_t *addedrdataset);
1118 /*%<
1119  * Add 'rdataset' to 'node' in version 'version' of 'db'.
1120  *
1121  * Notes:
1122  *
1123  * \li  If the database has zone semantics, the #DNS_DBADD_MERGE option is set,
1124  *      and an rdataset of the same type as 'rdataset' already exists at
1125  *      'node' then the contents of 'rdataset' will be merged with the existing
1126  *      rdataset.  If the option is not set, then rdataset will replace any
1127  *      existing rdataset of the same type.  If not merging and the
1128  *      #DNS_DBADD_FORCE option is set, then the data will update the database
1129  *      without regard to trust levels.  If not forcing the data, then the
1130  *      rdataset will only be added if its trust level is >= the trust level of
1131  *      any existing rdataset.  Forcing is only meaningful for cache databases.
1132  *      If #DNS_DBADD_EXACT is set then there must be no rdata in common between
1133  *      the old and new rdata sets.  If #DNS_DBADD_EXACTTTL is set then both
1134  *      the old and new rdata sets must have the same ttl.
1135  *
1136  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is
1137  *      a cache database, then the added rdataset will expire no later than
1138  *      now + rdataset->ttl.
1139  *
1140  * \li  If 'addedrdataset' is not NULL, then it will be attached to the
1141  *      resulting new rdataset in the database, or to the existing data if
1142  *      the existing data was better.
1143  *
1144  * Requires:
1145  *
1146  * \li  'db' is a valid database.
1147  *
1148  * \li  'node' is a valid node.
1149  *
1150  * \li  'rdataset' is a valid, associated rdataset with the same class
1151  *      as 'db'.
1152  *
1153  * \li  'addedrdataset' is NULL, or a valid, unassociated rdataset.
1154  *
1155  * \li  The database has zone semantics and 'version' is a valid
1156  *      read-write version, or the database has cache semantics
1157  *      and version is NULL.
1158  *
1159  * \li  If the database has cache semantics, the #DNS_DBADD_MERGE option must
1160  *      not be set.
1161  *
1162  * Returns:
1163  *
1164  * \li  #ISC_R_SUCCESS
1165  * \li  #DNS_R_UNCHANGED                        The operation did not change anything.
1166  * \li  #ISC_R_NOMEMORY
1167  * \li  #DNS_R_NOTEXACT
1168  *
1169  * \li  Other results are possible, depending upon the database
1170  *      implementation used.
1171  */
1172
1173 isc_result_t
1174 dns_db_subtractrdataset(dns_db_t *db, dns_dbnode_t *node,
1175                         dns_dbversion_t *version, dns_rdataset_t *rdataset,
1176                         unsigned int options, dns_rdataset_t *newrdataset);
1177 /*%<
1178  * Remove any rdata in 'rdataset' from 'node' in version 'version' of
1179  * 'db'.
1180  *
1181  * Notes:
1182  *
1183  * \li  If 'newrdataset' is not NULL, then it will be attached to the
1184  *      resulting new rdataset in the database, unless the rdataset has
1185  *      become nonexistent.  If DNS_DBSUB_EXACT is set then all elements
1186  *      of 'rdataset' must exist at 'node'.
1187  *
1188  * Requires:
1189  *
1190  * \li  'db' is a valid database.
1191  *
1192  * \li  'node' is a valid node.
1193  *
1194  * \li  'rdataset' is a valid, associated rdataset with the same class
1195  *      as 'db'.
1196  *
1197  * \li  'newrdataset' is NULL, or a valid, unassociated rdataset.
1198  *
1199  * \li  The database has zone semantics and 'version' is a valid
1200  *      read-write version.
1201  *
1202  * Returns:
1203  *
1204  * \li  #ISC_R_SUCCESS
1205  * \li  #DNS_R_UNCHANGED                        The operation did not change anything.
1206  * \li  #DNS_R_NXRRSET                  All rdata of the same type as those
1207  *                                      in 'rdataset' have been deleted.
1208  * \li  #DNS_R_NOTEXACT                 Some part of 'rdataset' did not
1209  *                                      exist and DNS_DBSUB_EXACT was set.
1210  *
1211  * \li  Other results are possible, depending upon the database
1212  *      implementation used.
1213  */
1214
1215 isc_result_t
1216 dns_db_deleterdataset(dns_db_t *db, dns_dbnode_t *node,
1217                       dns_dbversion_t *version, dns_rdatatype_t type,
1218                       dns_rdatatype_t covers);
1219 /*%<
1220  * Make it so that no rdataset of type 'type' exists at 'node' in version
1221  * version 'version' of 'db'.
1222  *
1223  * Notes:
1224  *
1225  * \li  If 'type' is dns_rdatatype_any, then no rdatasets will exist in
1226  *      'version' (provided that the dns_db_deleterdataset() isn't followed
1227  *      by one or more dns_db_addrdataset() calls).
1228  *
1229  * Requires:
1230  *
1231  * \li  'db' is a valid database.
1232  *
1233  * \li  'node' is a valid node.
1234  *
1235  * \li  The database has zone semantics and 'version' is a valid
1236  *      read-write version, or the database has cache semantics
1237  *      and version is NULL.
1238  *
1239  * \li  'type' is not a meta-RR type, except for dns_rdatatype_any, which is
1240  *      allowed.
1241  *
1242  * \li  If 'covers' != 0, 'type' must be SIG.
1243  *
1244  * Returns:
1245  *
1246  * \li  #ISC_R_SUCCESS
1247  * \li  #DNS_R_UNCHANGED                        No rdatasets of 'type' existed before
1248  *                                      the operation was attempted.
1249  *
1250  * \li  Other results are possible, depending upon the database
1251  *      implementation used.
1252  */
1253
1254 isc_result_t
1255 dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, isc_uint32_t *serialp);
1256 /*%<
1257  * Get the current SOA serial number from a zone database.
1258  *
1259  * Requires:
1260  * \li  'db' is a valid database with zone semantics.
1261  * \li  'ver' is a valid version.
1262  */
1263
1264 void
1265 dns_db_overmem(dns_db_t *db, isc_boolean_t overmem);
1266 /*%<
1267  * Enable / disable aggressive cache cleaning.
1268  */
1269
1270 unsigned int
1271 dns_db_nodecount(dns_db_t *db);
1272 /*%<
1273  * Count the number of nodes in 'db'.
1274  *
1275  * Requires:
1276  *
1277  * \li  'db' is a valid database.
1278  *
1279  * Returns:
1280  * \li  The number of nodes in the database
1281  */
1282
1283 void
1284 dns_db_settask(dns_db_t *db, isc_task_t *task);
1285 /*%<
1286  * If task is set then the final detach maybe performed asynchronously.
1287  *
1288  * Requires:
1289  * \li  'db' is a valid database.
1290  * \li  'task' to be valid or NULL.
1291  */
1292
1293 isc_boolean_t
1294 dns_db_ispersistent(dns_db_t *db);
1295 /*%<
1296  * Is 'db' persistent?  A persistent database does not need to be loaded
1297  * from disk or written to disk.
1298  *
1299  * Requires:
1300  *
1301  * \li  'db' is a valid database.
1302  *
1303  * Returns:
1304  * \li  #ISC_TRUE       'db' is persistent.
1305  * \li  #ISC_FALSE      'db' is not persistent.
1306  */
1307
1308 isc_result_t
1309 dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg,
1310                 isc_mem_t *mctx, dns_dbimplementation_t **dbimp);
1311
1312 /*%<
1313  * Register a new database implementation and add it to the list of
1314  * supported implementations.
1315  *
1316  * Requires:
1317  *
1318  * \li  'name' is not NULL
1319  * \li  'order' is a valid function pointer
1320  * \li  'mctx' is a valid memory context
1321  * \li  dbimp != NULL && *dbimp == NULL
1322  *
1323  * Returns:
1324  * \li  #ISC_R_SUCCESS  The registration succeeded
1325  * \li  #ISC_R_NOMEMORY Out of memory
1326  * \li  #ISC_R_EXISTS   A database implementation with the same name exists
1327  *
1328  * Ensures:
1329  *
1330  * \li  *dbimp points to an opaque structure which must be passed to
1331  *      dns_db_unregister().
1332  */
1333
1334 void
1335 dns_db_unregister(dns_dbimplementation_t **dbimp);
1336 /*%<
1337  * Remove a database implementation from the list of supported
1338  * implementations.  No databases of this type can be active when this
1339  * is called.
1340  *
1341  * Requires:
1342  * \li  dbimp != NULL && *dbimp == NULL
1343  *
1344  * Ensures:
1345  *
1346  * \li  Any memory allocated in *dbimp will be freed.
1347  */
1348
1349 isc_result_t
1350 dns_db_getoriginnode(dns_db_t *db, dns_dbnode_t **nodep);
1351 /*%<
1352  * Get the origin DB node corresponding to the DB's zone.  This function
1353  * should typically succeed unless the underlying DB implementation doesn't
1354  * support the feature.
1355  *
1356  * Requires:
1357  *
1358  * \li  'db' is a valid zone database.
1359  * \li  'nodep' != NULL && '*nodep' == NULL
1360  *
1361  * Ensures:
1362  * \li  On success, '*nodep' will point to the DB node of the zone's origin.
1363  *
1364  * Returns:
1365  * \li  #ISC_R_SUCCESS
1366  * \li  #ISC_R_NOTFOUND - the DB implementation does not support this feature.
1367  */
1368
1369 isc_result_t
1370 dns_db_getnsec3parameters(dns_db_t *db, dns_dbversion_t *version,
1371                           dns_hash_t *hash, isc_uint8_t *flags,
1372                           isc_uint16_t *interations,
1373                           unsigned char *salt, size_t *salt_length);
1374 /*%<
1375  * Get the NSEC3 parameters that are associated with this zone.
1376  *
1377  * Requires:
1378  * \li  'db' is a valid zone database.
1379  *
1380  * Returns:
1381  * \li  #ISC_R_SUCCESS
1382  * \li  #ISC_R_NOTFOUND - the DB implementation does not support this feature
1383  *                        or this zone does not have NSEC3 records.
1384  */
1385
1386 isc_result_t
1387 dns_db_findnsec3node(dns_db_t *db, dns_name_t *name,
1388                      isc_boolean_t create, dns_dbnode_t **nodep);
1389 /*%<
1390  * Find the NSEC3 node with name 'name'.
1391  *
1392  * Notes:
1393  * \li  If 'create' is ISC_TRUE and no node with name 'name' exists, then
1394  *      such a node will be created.
1395  *
1396  * Requires:
1397  *
1398  * \li  'db' is a valid database.
1399  *
1400  * \li  'name' is a valid, non-empty, absolute name.
1401  *
1402  * \li  nodep != NULL && *nodep == NULL
1403  *
1404  * Ensures:
1405  *
1406  * \li  On success, *nodep is attached to the node with name 'name'.
1407  *
1408  * Returns:
1409  *
1410  * \li  #ISC_R_SUCCESS
1411  * \li  #ISC_R_NOTFOUND                 If !create and name not found.
1412  * \li  #ISC_R_NOMEMORY                 Can only happen if create is ISC_TRUE.
1413  *
1414  * \li  Other results are possible, depending upon the database
1415  *      implementation used.
1416  */
1417
1418 isc_result_t
1419 dns_db_setsigningtime(dns_db_t *db, dns_rdataset_t *rdataset,
1420                       isc_stdtime_t resign);
1421 /*%<
1422  * Sets the re-signing time associated with 'rdataset' to 'resign'.
1423  *
1424  * Requires:
1425  * \li  'db' is a valid zone database.
1426  * \li  'rdataset' to be associated with 'db'.
1427  *
1428  * Returns:
1429  * \li  #ISC_R_SUCCESS
1430  * \li  #ISC_R_NOMEMORY
1431  * \li  #ISC_R_NOTIMPLEMENTED - Not supported by this DB implementation.
1432  */
1433
1434 isc_result_t
1435 dns_db_getsigningtime(dns_db_t *db, dns_rdataset_t *rdataset, dns_name_t *name);
1436 /*%<
1437  * Return the rdataset with the earliest signing time in the zone.
1438  * Note: the rdataset is version agnostic.
1439  *
1440  * Requires:
1441  * \li  'db' is a valid zone database.
1442  * \li  'rdataset' to be initialized but not associated.
1443  * \li  'name' to be NULL or have a buffer associated with it.
1444  *
1445  * Returns:
1446  * \li  #ISC_R_SUCCESS
1447  * \li  #ISC_R_NOTFOUND - No dataset exists.
1448  */
1449
1450 void
1451 dns_db_resigned(dns_db_t *db, dns_rdataset_t *rdataset,
1452                 dns_dbversion_t *version);
1453 /*%<
1454  * Mark 'rdataset' as not being available to be returned by
1455  * dns_db_getsigningtime().  If the changes associated with 'version'
1456  * are committed this will be permanent.  If the version is not committed
1457  * this change will be rolled back when the version is closed.
1458  *
1459  * Requires:
1460  * \li  'db' is a valid zone database.
1461  * \li  'rdataset' to be associated with 'db'.
1462  * \li  'version' to be open for writing.
1463  */
1464
1465 dns_stats_t *
1466 dns_db_getrrsetstats(dns_db_t *db);
1467 /*%<
1468  * Get statistics information counting RRsets stored in the DB, when available.
1469  * The statistics may not be available depending on the DB implementation.
1470  *
1471  * Requires:
1472  *
1473  * \li  'db' is a valid database (zone or cache).
1474  *
1475  * Returns:
1476  * \li  when available, a pointer to a statistics object created by
1477  *      dns_rdatasetstats_create(); otherwise NULL.
1478  */
1479
1480 ISC_LANG_ENDDECLS
1481
1482 #endif /* DNS_DB_H */