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