contrib/bind9/lib/dns/include/dns/zone.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: zone.h,v 1.160.50.4 2009/01/29 22:40:35 jinmei Exp $ */
  19
  20 #ifndef DNS_ZONE_H
  21 #define DNS_ZONE_H 1
  22
  23 /*! \file dns/zone.h */
  24
  25 /***
  26  ***    Imports
  27  ***/
  28
  29 #include <stdio.h>
  30
  31 #include <isc/formatcheck.h>
  32 #include <isc/lang.h>
  33 #include <isc/rwlock.h>
  34
  35 #include <dns/masterdump.h>
  36 #include <dns/rdatastruct.h>
  37 #include <dns/types.h>
  38
  39 typedef enum {
  40         dns_zone_none,
  41         dns_zone_master,
  42         dns_zone_slave,
  43         dns_zone_stub
  44 } dns_zonetype_t;
  45
  46 #define DNS_ZONEOPT_SERVERS       0x00000001U   /*%< perform server checks */
  47 #define DNS_ZONEOPT_PARENTS       0x00000002U   /*%< perform parent checks */
  48 #define DNS_ZONEOPT_CHILDREN      0x00000004U   /*%< perform child checks */
  49 #define DNS_ZONEOPT_NOTIFY        0x00000008U   /*%< perform NOTIFY */
  50 #define DNS_ZONEOPT_MANYERRORS    0x00000010U   /*%< return many errors on load */
  51 #define DNS_ZONEOPT_IXFRFROMDIFFS 0x00000020U   /*%< calculate differences */
  52 #define DNS_ZONEOPT_NOMERGE       0x00000040U   /*%< don't merge journal */
  53 #define DNS_ZONEOPT_CHECKNS       0x00000080U   /*%< check if NS's are addresses */
  54 #define DNS_ZONEOPT_FATALNS       0x00000100U   /*%< DNS_ZONEOPT_CHECKNS is fatal */
  55 #define DNS_ZONEOPT_MULTIMASTER   0x00000200U   /*%< this zone has multiple masters */
  56 #define DNS_ZONEOPT_USEALTXFRSRC  0x00000400U   /*%< use alternate transfer sources */
  57 #define DNS_ZONEOPT_CHECKNAMES    0x00000800U   /*%< check-names */
  58 #define DNS_ZONEOPT_CHECKNAMESFAIL 0x00001000U  /*%< fatal check-name failures */
  59 #define DNS_ZONEOPT_CHECKWILDCARD 0x00002000U   /*%< check for internal wildcards */
  60 #define DNS_ZONEOPT_CHECKMX       0x00004000U   /*%< check-mx */
  61 #define DNS_ZONEOPT_CHECKMXFAIL   0x00008000U   /*%< fatal check-mx failures */
  62 #define DNS_ZONEOPT_CHECKINTEGRITY 0x00010000U  /*%< perform integrity checks */
  63 #define DNS_ZONEOPT_CHECKSIBLING  0x00020000U   /*%< perform sibling glue checks */
  64 #define DNS_ZONEOPT_NOCHECKNS     0x00040000U   /*%< disable IN NS address checks */
  65 #define DNS_ZONEOPT_WARNMXCNAME   0x00080000U   /*%< warn on MX CNAME check */
  66 #define DNS_ZONEOPT_IGNOREMXCNAME 0x00100000U   /*%< ignore MX CNAME check */
  67 #define DNS_ZONEOPT_WARNSRVCNAME  0x00200000U   /*%< warn on SRV CNAME check */
  68 #define DNS_ZONEOPT_IGNORESRVCNAME 0x00400000U  /*%< ignore SRV CNAME check */
  69 #define DNS_ZONEOPT_UPDATECHECKKSK 0x00800000U  /*%< check dnskey KSK flag */
  70 #define DNS_ZONEOPT_TRYTCPREFRESH 0x01000000U   /*%< try tcp refresh on udp failure */
  71 #define DNS_ZONEOPT_NOTIFYTOSOA   0x02000000U   /*%< Notify the SOA MNAME */
  72 #define DNS_ZONEOPT_NSEC3TESTZONE 0x04000000U   /*%< nsec3-test-zone */
  73
  74 #ifndef NOMINUM_PUBLIC
  75 /*
  76  * Nominum specific options build down.
  77  */
  78 #define DNS_ZONEOPT_NOTIFYFORWARD 0x80000000U   /* forward notify to master */
  79 #endif /* NOMINUM_PUBLIC */
  80
  81 #ifndef DNS_ZONE_MINREFRESH
  82 #define DNS_ZONE_MINREFRESH                 300 /*%< 5 minutes */
  83 #endif
  84 #ifndef DNS_ZONE_MAXREFRESH
  85 #define DNS_ZONE_MAXREFRESH             2419200 /*%< 4 weeks */
  86 #endif
  87 #ifndef DNS_ZONE_DEFAULTREFRESH
  88 #define DNS_ZONE_DEFAULTREFRESH            3600 /*%< 1 hour */
  89 #endif
  90 #ifndef DNS_ZONE_MINRETRY
  91 #define DNS_ZONE_MINRETRY                   300 /*%< 5 minutes */
  92 #endif
  93 #ifndef DNS_ZONE_MAXRETRY
  94 #define DNS_ZONE_MAXRETRY               1209600 /*%< 2 weeks */
  95 #endif
  96 #ifndef DNS_ZONE_DEFAULTRETRY
  97 #define DNS_ZONE_DEFAULTRETRY                60 /*%< 1 minute, subject to
  98                                                    exponential backoff */
  99 #endif
 100
 101 #define DNS_ZONESTATE_XFERRUNNING       1
 102 #define DNS_ZONESTATE_XFERDEFERRED      2
 103 #define DNS_ZONESTATE_SOAQUERY          3
 104 #define DNS_ZONESTATE_ANY               4
 105
 106 ISC_LANG_BEGINDECLS
 107
 108 /***
 109  ***    Functions
 110  ***/
 111
 112 isc_result_t
 113 dns_zone_create(dns_zone_t **zonep, isc_mem_t *mctx);
 114 /*%<
 115  *      Creates a new empty zone and attach '*zonep' to it.
 116  *
 117  * Requires:
 118  *\li   'zonep' to point to a NULL pointer.
 119  *\li   'mctx' to be a valid memory context.
 120  *
 121  * Ensures:
 122  *\li   '*zonep' refers to a valid zone.
 123  *
 124  * Returns:
 125  *\li   #ISC_R_SUCCESS
 126  *\li   #ISC_R_NOMEMORY
 127  *\li   #ISC_R_UNEXPECTED
 128  */
 129
 130 void
 131 dns_zone_setclass(dns_zone_t *zone, dns_rdataclass_t rdclass);
 132 /*%<
 133  *      Sets the class of a zone.  This operation can only be performed
 134  *      once on a zone.
 135  *
 136  * Require:
 137  *\li   'zone' to be a valid zone.
 138  *\li   dns_zone_setclass() not to have been called since the zone was
 139  *      created.
 140  *\li   'rdclass' != dns_rdataclass_none.
 141  */
 142
 143 dns_rdataclass_t
 144 dns_zone_getclass(dns_zone_t *zone);
 145 /*%<
 146  *      Returns the current zone class.
 147  *
 148  * Requires:
 149  *\li   'zone' to be a valid zone.
 150  */
 151
 152 isc_uint32_t
 153 dns_zone_getserial(dns_zone_t *zone);
 154 /*%<
 155  *      Returns the current serial number of the zone.
 156  *
 157  * Requires:
 158  *\li   'zone' to be a valid zone.
 159  */
 160
 161 void
 162 dns_zone_settype(dns_zone_t *zone, dns_zonetype_t type);
 163 /*%<
 164  *      Sets the zone type. This operation can only be performed once on
 165  *      a zone.
 166  *
 167  * Requires:
 168  *\li   'zone' to be a valid zone.
 169  *\li   dns_zone_settype() not to have been called since the zone was
 170  *      created.
 171  *\li   'type' != dns_zone_none
 172  */
 173
 174 void
 175 dns_zone_setview(dns_zone_t *zone, dns_view_t *view);
 176 /*%<
 177  *      Associate the zone with a view.
 178  *
 179  * Require:
 180  *\li   'zone' to be a valid zone.
 181  */
 182
 183 dns_view_t *
 184 dns_zone_getview(dns_zone_t *zone);
 185 /*%<
 186  *      Returns the zone's associated view.
 187  *
 188  * Requires:
 189  *\li   'zone' to be a valid zone.
 190  */
 191
 192 isc_result_t
 193 dns_zone_setorigin(dns_zone_t *zone, const dns_name_t *origin);
 194 /*%<
 195  *      Sets the zones origin to 'origin'.
 196  *
 197  * Require:
 198  *\li   'zone' to be a valid zone.
 199  *\li   'origin' to be non NULL.
 200  *
 201  * Returns:
 202  *\li   #ISC_R_SUCCESS
 203  *\li   #ISC_R_NOMEMORY
 204  */
 205
 206 dns_name_t *
 207 dns_zone_getorigin(dns_zone_t *zone);
 208 /*%<
 209  *      Returns the value of the origin.
 210  *
 211  * Require:
 212  *\li   'zone' to be a valid zone.
 213  */
 214
 215 isc_result_t
 216 dns_zone_setfile(dns_zone_t *zone, const char *file);
 217
 218 isc_result_t
 219 dns_zone_setfile2(dns_zone_t *zone, const char *file,
 220                   dns_masterformat_t format);
 221 /*%<
 222  *    Sets the name of the master file in the format of 'format' from which
 223  *    the zone loads its database to 'file'.
 224  *
 225  *    For zones that have no associated master file, 'file' will be NULL.
 226  *
 227  *      For zones with persistent databases, the file name
 228  *      setting is ignored.
 229  *
 230  *    dns_zone_setfile() is a backward-compatible form of
 231  *    dns_zone_setfile2(), which always specifies the
 232  *    dns_masterformat_text (RFC1035) format.
 233  *
 234  * Require:
 235  *\li   'zone' to be a valid zone.
 236  *
 237  * Returns:
 238  *\li   #ISC_R_NOMEMORY
 239  *\li   #ISC_R_SUCCESS
 240  */
 241
 242 const char *
 243 dns_zone_getfile(dns_zone_t *zone);
 244 /*%<
 245  *      Gets the name of the zone's master file, if any.
 246  *
 247  * Requires:
 248  *\li   'zone' to be valid initialised zone.
 249  *
 250  * Returns:
 251  *\li   Pointer to null-terminated file name, or NULL.
 252  */
 253
 254 isc_result_t
 255 dns_zone_load(dns_zone_t *zone);
 256
 257 isc_result_t
 258 dns_zone_loadnew(dns_zone_t *zone);
 259 /*%<
 260  *      Cause the database to be loaded from its backing store.
 261  *      Confirm that the minimum requirements for the zone type are
 262  *      met, otherwise DNS_R_BADZONE is returned.
 263  *
 264  *      dns_zone_loadnew() only loads zones that are not yet loaded.
 265  *      dns_zone_load() also loads zones that are already loaded and
 266  *      and whose master file has changed since the last load.
 267  *
 268  * Require:
 269  *\li   'zone' to be a valid zone.
 270  *
 271  * Returns:
 272  *\li   #ISC_R_UNEXPECTED
 273  *\li   #ISC_R_SUCCESS
 274  *\li   DNS_R_CONTINUE    Incremental load has been queued.
 275  *\li   DNS_R_UPTODATE    The zone has already been loaded based on
 276  *                        file system timestamps.
 277  *\li   DNS_R_BADZONE
 278  *\li   Any result value from dns_db_load().
 279  */
 280
 281 void
 282 dns_zone_attach(dns_zone_t *source, dns_zone_t **target);
 283 /*%<
 284  *      Attach '*target' to 'source' incrementing its external
 285  *      reference count.
 286  *
 287  * Require:
 288  *\li   'zone' to be a valid zone.
 289  *\li   'target' to be non NULL and '*target' to be NULL.
 290  */
 291
 292 void
 293 dns_zone_detach(dns_zone_t **zonep);
 294 /*%<
 295  *      Detach from a zone decrementing its external reference count.
 296  *      If this was the last external reference to the zone it will be
 297  *      shut down and eventually freed.
 298  *
 299  * Require:
 300  *\li   'zonep' to point to a valid zone.
 301  */
 302
 303 void
 304 dns_zone_iattach(dns_zone_t *source, dns_zone_t **target);
 305 /*%<
 306  *      Attach '*target' to 'source' incrementing its internal
 307  *      reference count.  This is intended for use by operations
 308  *      such as zone transfers that need to prevent the zone
 309  *      object from being freed but not from shutting down.
 310  *
 311  * Require:
 312  *\li   The caller is running in the context of the zone's task.
 313  *\li   'zone' to be a valid zone.
 314  *\li   'target' to be non NULL and '*target' to be NULL.
 315  */
 316
 317 void
 318 dns_zone_idetach(dns_zone_t **zonep);
 319 /*%<
 320  *      Detach from a zone decrementing its internal reference count.
 321  *      If there are no more internal or external references to the
 322  *      zone, it will be freed.
 323  *
 324  * Require:
 325  *\li   The caller is running in the context of the zone's task.
 326  *\li   'zonep' to point to a valid zone.
 327  */
 328
 329 void
 330 dns_zone_setflag(dns_zone_t *zone, unsigned int flags, isc_boolean_t value);
 331 /*%<
 332  *      Sets ('value' == 'ISC_TRUE') / clears ('value' == 'IS_FALSE')
 333  *      zone flags.  Valid flag bits are DNS_ZONE_F_*.
 334  *
 335  * Requires
 336  *\li   'zone' to be a valid zone.
 337  */
 338
 339 isc_result_t
 340 dns_zone_getdb(dns_zone_t *zone, dns_db_t **dbp);
 341 /*%<
 342  *      Attach '*dbp' to the database to if it exists otherwise
 343  *      return DNS_R_NOTLOADED.
 344  *
 345  * Require:
 346  *\li   'zone' to be a valid zone.
 347  *\li   'dbp' to be != NULL && '*dbp' == NULL.
 348  *
 349  * Returns:
 350  *\li   #ISC_R_SUCCESS
 351  *\li   DNS_R_NOTLOADED
 352  */
 353
 354 isc_result_t
 355 dns_zone_setdbtype(dns_zone_t *zone,
 356                    unsigned int dbargc, const char * const *dbargv);
 357 /*%<
 358  *      Sets the database type to dbargv[0] and database arguments
 359  *      to subsequent dbargv elements.
 360  *      'db_type' is not checked to see if it is a valid database type.
 361  *
 362  * Require:
 363  *\li   'zone' to be a valid zone.
 364  *\li   'database' to be non NULL.
 365  *\li   'dbargc' to be >= 1
 366  *\li   'dbargv' to point to dbargc NULL-terminated strings
 367  *
 368  * Returns:
 369  *\li   #ISC_R_NOMEMORY
 370  *\li   #ISC_R_SUCCESS
 371  */
 372
 373 isc_result_t
 374 dns_zone_getdbtype(dns_zone_t *zone, char ***argv, isc_mem_t *mctx);
 375 /*%<
 376  *      Returns the current dbtype.  isc_mem_free() should be used
 377  *      to free 'argv' after use.
 378  *
 379  * Require:
 380  *\li   'zone' to be a valid zone.
 381  *\li   'argv' to be non NULL and *argv to be NULL.
 382  *\li   'mctx' to be valid.
 383  *
 384  * Returns:
 385  *\li   #ISC_R_NOMEMORY
 386  *\li   #ISC_R_SUCCESS
 387  */
 388
 389 void
 390 dns_zone_markdirty(dns_zone_t *zone);
 391 /*%<
 392  *      Mark a zone as 'dirty'.
 393  *
 394  * Require:
 395  *\li   'zone' to be a valid zone.
 396  */
 397
 398 void
 399 dns_zone_expire(dns_zone_t *zone);
 400 /*%<
 401  *      Mark the zone as expired.  If the zone requires dumping cause it to
 402  *      be initiated.  Set the refresh and retry intervals to there default
 403  *      values and unload the zone.
 404  *
 405  * Require
 406  *\li   'zone' to be a valid zone.
 407  */
 408
 409 void
 410 dns_zone_refresh(dns_zone_t *zone);
 411 /*%<
 412  *      Initiate zone up to date checks.  The zone must already be being
 413  *      managed.
 414  *
 415  * Require
 416  *\li   'zone' to be a valid zone.
 417  */
 418
 419 isc_result_t
 420 dns_zone_flush(dns_zone_t *zone);
 421 /*%<
 422  *      Write the zone to database if there are uncommitted changes.
 423  *
 424  * Require:
 425  *\li   'zone' to be a valid zone.
 426  */
 427
 428 isc_result_t
 429 dns_zone_dump(dns_zone_t *zone);
 430 /*%<
 431  *      Write the zone to database.
 432  *
 433  * Require:
 434  *\li   'zone' to be a valid zone.
 435  */
 436
 437 isc_result_t
 438 dns_zone_dumptostream(dns_zone_t *zone, FILE *fd);
 439
 440 isc_result_t
 441 dns_zone_dumptostream2(dns_zone_t *zone, FILE *fd, dns_masterformat_t format,
 442                        const dns_master_style_t *style);
 443 /*%<
 444  *    Write the zone to stream 'fd' in the specified 'format'.
 445  *    If the 'format' is dns_masterformat_text (RFC1035), 'style' also
 446  *    specifies the file style (e.g., &dns_master_style_default).
 447  *
 448  *    dns_zone_dumptostream() is a backward-compatible form of
 449  *    dns_zone_dumptostream2(), which always uses the dns_masterformat_text
 450  *    format and the dns_master_style_default style.
 451  *
 452  *    Note that dns_zone_dumptostream2() is the most flexible form.  It
 453  *    can also provide the functionality of dns_zone_fulldumptostream().
 454  *
 455  * Require:
 456  *\li   'zone' to be a valid zone.
 457  *\li   'fd' to be a stream open for writing.
 458  */
 459
 460 isc_result_t
 461 dns_zone_fulldumptostream(dns_zone_t *zone, FILE *fd);
 462 /*%<
 463  *      The same as dns_zone_dumptostream, but dumps the zone with
 464  *      different dump settings (dns_master_style_full).
 465  *
 466  * Require:
 467  *\li   'zone' to be a valid zone.
 468  *\li   'fd' to be a stream open for writing.
 469  */
 470
 471 void
 472 dns_zone_maintenance(dns_zone_t *zone);
 473 /*%<
 474  *      Perform regular maintenance on the zone.  This is called as a
 475  *      result of a zone being managed.
 476  *
 477  * Require
 478  *\li   'zone' to be a valid zone.
 479  */
 480
 481 isc_result_t
 482 dns_zone_setmasters(dns_zone_t *zone, const isc_sockaddr_t *masters,
 483                     isc_uint32_t count);
 484 isc_result_t
 485 dns_zone_setmasterswithkeys(dns_zone_t *zone,
 486                             const isc_sockaddr_t *masters,
 487                             dns_name_t **keynames,
 488                             isc_uint32_t count);
 489 /*%<
 490  *      Set the list of master servers for the zone.
 491  *
 492  * Require:
 493  *\li   'zone' to be a valid zone.
 494  *\li   'masters' array of isc_sockaddr_t with port set or NULL.
 495  *\li   'count' the number of masters.
 496  *\li      'keynames' array of dns_name_t's for tsig keys or NULL.
 497  *
 498  *  \li    dns_zone_setmasters() is just a wrapper to setmasterswithkeys(),
 499  *      passing NULL in the keynames field.
 500  *
 501  * \li  If 'masters' is NULL then 'count' must be zero.
 502  *
 503  * Returns:
 504  *\li   #ISC_R_SUCCESS
 505  *\li   #ISC_R_NOMEMORY
 506  *\li      Any result dns_name_dup() can return, if keynames!=NULL
 507  */
 508
 509 isc_result_t
 510 dns_zone_setalsonotify(dns_zone_t *zone, const isc_sockaddr_t *notify,
 511                        isc_uint32_t count);
 512 /*%<
 513  *      Set the list of additional servers to be notified when
 514  *      a zone changes.  To clear the list use 'count = 0'.
 515  *
 516  * Require:
 517  *\li   'zone' to be a valid zone.
 518  *\li   'notify' to be non-NULL if count != 0.
 519  *\li   'count' to be the number of notifiees.
 520  *
 521  * Returns:
 522  *\li   #ISC_R_SUCCESS
 523  *\li   #ISC_R_NOMEMORY
 524  */
 525
 526 void
 527 dns_zone_unload(dns_zone_t *zone);
 528 /*%<
 529  *      detach the database from the zone structure.
 530  *
 531  * Require:
 532  *\li   'zone' to be a valid zone.
 533  */
 534
 535 void
 536 dns_zone_setoption(dns_zone_t *zone, unsigned int option, isc_boolean_t value);
 537 /*%<
 538  *      Set given options on ('value' == ISC_TRUE) or off ('value' ==
 539  *      #ISC_FALSE).
 540  *
 541  * Require:
 542  *\li   'zone' to be a valid zone.
 543  */
 544
 545 unsigned int
 546 dns_zone_getoptions(dns_zone_t *zone);
 547 /*%<
 548  *      Returns the current zone options.
 549  *
 550  * Require:
 551  *\li   'zone' to be a valid zone.
 552  */
 553
 554 void
 555 dns_zone_setminrefreshtime(dns_zone_t *zone, isc_uint32_t val);
 556 /*%<
 557  *      Set the minimum refresh time.
 558  *
 559  * Requires:
 560  *\li   'zone' is valid.
 561  *\li   val > 0.
 562  */
 563
 564 void
 565 dns_zone_setmaxrefreshtime(dns_zone_t *zone, isc_uint32_t val);
 566 /*%<
 567  *      Set the maximum refresh time.
 568  *
 569  * Requires:
 570  *\li   'zone' is valid.
 571  *\li   val > 0.
 572  */
 573
 574 void
 575 dns_zone_setminretrytime(dns_zone_t *zone, isc_uint32_t val);
 576 /*%<
 577  *      Set the minimum retry time.
 578  *
 579  * Requires:
 580  *\li   'zone' is valid.
 581  *\li   val > 0.
 582  */
 583
 584 void
 585 dns_zone_setmaxretrytime(dns_zone_t *zone, isc_uint32_t val);
 586 /*%<
 587  *      Set the maximum retry time.
 588  *
 589  * Requires:
 590  *\li   'zone' is valid.
 591  *      val > 0.
 592  */
 593
 594 isc_result_t
 595 dns_zone_setxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 596 isc_result_t
 597 dns_zone_setaltxfrsource4(dns_zone_t *zone,
 598                           const isc_sockaddr_t *xfrsource);
 599 /*%<
 600  *      Set the source address to be used in IPv4 zone transfers.
 601  *
 602  * Require:
 603  *\li   'zone' to be a valid zone.
 604  *\li   'xfrsource' to contain the address.
 605  *
 606  * Returns:
 607  *\li   #ISC_R_SUCCESS
 608  */
 609
 610 isc_sockaddr_t *
 611 dns_zone_getxfrsource4(dns_zone_t *zone);
 612 isc_sockaddr_t *
 613 dns_zone_getaltxfrsource4(dns_zone_t *zone);
 614 /*%<
 615  *      Returns the source address set by a previous dns_zone_setxfrsource4
 616  *      call, or the default of inaddr_any, port 0.
 617  *
 618  * Require:
 619  *\li   'zone' to be a valid zone.
 620  */
 621
 622 isc_result_t
 623 dns_zone_setxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 624 isc_result_t
 625 dns_zone_setaltxfrsource6(dns_zone_t *zone,
 626                           const isc_sockaddr_t *xfrsource);
 627 /*%<
 628  *      Set the source address to be used in IPv6 zone transfers.
 629  *
 630  * Require:
 631  *\li   'zone' to be a valid zone.
 632  *\li   'xfrsource' to contain the address.
 633  *
 634  * Returns:
 635  *\li   #ISC_R_SUCCESS
 636  */
 637
 638 isc_sockaddr_t *
 639 dns_zone_getxfrsource6(dns_zone_t *zone);
 640 isc_sockaddr_t *
 641 dns_zone_getaltxfrsource6(dns_zone_t *zone);
 642 /*%<
 643  *      Returns the source address set by a previous dns_zone_setxfrsource6
 644  *      call, or the default of in6addr_any, port 0.
 645  *
 646  * Require:
 647  *\li   'zone' to be a valid zone.
 648  */
 649
 650 isc_result_t
 651 dns_zone_setnotifysrc4(dns_zone_t *zone, const isc_sockaddr_t *notifysrc);
 652 /*%<
 653  *      Set the source address to be used with IPv4 NOTIFY messages.
 654  *
 655  * Require:
 656  *\li   'zone' to be a valid zone.
 657  *\li   'notifysrc' to contain the address.
 658  *
 659  * Returns:
 660  *\li   #ISC_R_SUCCESS
 661  */
 662
 663 isc_sockaddr_t *
 664 dns_zone_getnotifysrc4(dns_zone_t *zone);
 665 /*%<
 666  *      Returns the source address set by a previous dns_zone_setnotifysrc4
 667  *      call, or the default of inaddr_any, port 0.
 668  *
 669  * Require:
 670  *\li   'zone' to be a valid zone.
 671  */
 672
 673 isc_result_t
 674 dns_zone_setnotifysrc6(dns_zone_t *zone, const isc_sockaddr_t *notifysrc);
 675 /*%<
 676  *      Set the source address to be used with IPv6 NOTIFY messages.
 677  *
 678  * Require:
 679  *\li   'zone' to be a valid zone.
 680  *\li   'notifysrc' to contain the address.
 681  *
 682  * Returns:
 683  *\li   #ISC_R_SUCCESS
 684  */
 685
 686 isc_sockaddr_t *
 687 dns_zone_getnotifysrc6(dns_zone_t *zone);
 688 /*%<
 689  *      Returns the source address set by a previous dns_zone_setnotifysrc6
 690  *      call, or the default of in6addr_any, port 0.
 691  *
 692  * Require:
 693  *\li   'zone' to be a valid zone.
 694  */
 695
 696 void
 697 dns_zone_setnotifyacl(dns_zone_t *zone, dns_acl_t *acl);
 698 /*%<
 699  *      Sets the notify acl list for the zone.
 700  *
 701  * Require:
 702  *\li   'zone' to be a valid zone.
 703  *\li   'acl' to be a valid acl.
 704  */
 705
 706 void
 707 dns_zone_setqueryacl(dns_zone_t *zone, dns_acl_t *acl);
 708 /*%<
 709  *      Sets the query acl list for the zone.
 710  *
 711  * Require:
 712  *\li   'zone' to be a valid zone.
 713  *\li   'acl' to be a valid acl.
 714  */
 715
 716 void
 717 dns_zone_setqueryonacl(dns_zone_t *zone, dns_acl_t *acl);
 718 /*%<
 719  *      Sets the query-on acl list for the zone.
 720  *
 721  * Require:
 722  *\li   'zone' to be a valid zone.
 723  *\li   'acl' to be a valid acl.
 724  */
 725
 726 void
 727 dns_zone_setupdateacl(dns_zone_t *zone, dns_acl_t *acl);
 728 /*%<
 729  *      Sets the update acl list for the zone.
 730  *
 731  * Require:
 732  *\li   'zone' to be a valid zone.
 733  *\li   'acl' to be valid acl.
 734  */
 735
 736 void
 737 dns_zone_setforwardacl(dns_zone_t *zone, dns_acl_t *acl);
 738 /*%<
 739  *      Sets the forward unsigned updates acl list for the zone.
 740  *
 741  * Require:
 742  *\li   'zone' to be a valid zone.
 743  *\li   'acl' to be valid acl.
 744  */
 745
 746 void
 747 dns_zone_setxfracl(dns_zone_t *zone, dns_acl_t *acl);
 748 /*%<
 749  *      Sets the transfer acl list for the zone.
 750  *
 751  * Require:
 752  *\li   'zone' to be a valid zone.
 753  *\li   'acl' to be valid acl.
 754  */
 755
 756 dns_acl_t *
 757 dns_zone_getnotifyacl(dns_zone_t *zone);
 758 /*%<
 759  *      Returns the current notify acl or NULL.
 760  *
 761  * Require:
 762  *\li   'zone' to be a valid zone.
 763  *
 764  * Returns:
 765  *\li   acl a pointer to the acl.
 766  *\li   NULL
 767  */
 768
 769 dns_acl_t *
 770 dns_zone_getqueryacl(dns_zone_t *zone);
 771 /*%<
 772  *      Returns the current query acl or NULL.
 773  *
 774  * Require:
 775  *\li   'zone' to be a valid zone.
 776  *
 777  * Returns:
 778  *\li   acl a pointer to the acl.
 779  *\li   NULL
 780  */
 781
 782 dns_acl_t *
 783 dns_zone_getqueryonacl(dns_zone_t *zone);
 784 /*%<
 785  *      Returns the current query-on acl or NULL.
 786  *
 787  * Require:
 788  *\li   'zone' to be a valid zone.
 789  *
 790  * Returns:
 791  *\li   acl a pointer to the acl.
 792  *\li   NULL
 793  */
 794
 795 dns_acl_t *
 796 dns_zone_getupdateacl(dns_zone_t *zone);
 797 /*%<
 798  *      Returns the current update acl or NULL.
 799  *
 800  * Require:
 801  *\li   'zone' to be a valid zone.
 802  *
 803  * Returns:
 804  *\li   acl a pointer to the acl.
 805  *\li   NULL
 806  */
 807
 808 dns_acl_t *
 809 dns_zone_getforwardacl(dns_zone_t *zone);
 810 /*%<
 811  *      Returns the current forward unsigned updates acl or NULL.
 812  *
 813  * Require:
 814  *\li   'zone' to be a valid zone.
 815  *
 816  * Returns:
 817  *\li   acl a pointer to the acl.
 818  *\li   NULL
 819  */
 820
 821 dns_acl_t *
 822 dns_zone_getxfracl(dns_zone_t *zone);
 823 /*%<
 824  *      Returns the current transfer acl or NULL.
 825  *
 826  * Require:
 827  *\li   'zone' to be a valid zone.
 828  *
 829  * Returns:
 830  *\li   acl a pointer to the acl.
 831  *\li   NULL
 832  */
 833
 834 void
 835 dns_zone_clearupdateacl(dns_zone_t *zone);
 836 /*%<
 837  *      Clear the current update acl.
 838  *
 839  * Require:
 840  *\li   'zone' to be a valid zone.
 841  */
 842
 843 void
 844 dns_zone_clearforwardacl(dns_zone_t *zone);
 845 /*%<
 846  *      Clear the current forward unsigned updates acl.
 847  *
 848  * Require:
 849  *\li   'zone' to be a valid zone.
 850  */
 851
 852 void
 853 dns_zone_clearnotifyacl(dns_zone_t *zone);
 854 /*%<
 855  *      Clear the current notify acl.
 856  *
 857  * Require:
 858  *\li   'zone' to be a valid zone.
 859  */
 860
 861 void
 862 dns_zone_clearqueryacl(dns_zone_t *zone);
 863 /*%<
 864  *      Clear the current query acl.
 865  *
 866  * Require:
 867  *\li   'zone' to be a valid zone.
 868  */
 869
 870 void
 871 dns_zone_clearqueryonacl(dns_zone_t *zone);
 872 /*%<
 873  *      Clear the current query-on acl.
 874  *
 875  * Require:
 876  *\li   'zone' to be a valid zone.
 877  */
 878
 879 void
 880 dns_zone_clearxfracl(dns_zone_t *zone);
 881 /*%<
 882  *      Clear the current transfer acl.
 883  *
 884  * Require:
 885  *\li   'zone' to be a valid zone.
 886  */
 887
 888 isc_boolean_t
 889 dns_zone_getupdatedisabled(dns_zone_t *zone);
 890 /*%<
 891  * Return update disabled.
 892  * Transient unless called when running in isc_task_exclusive() mode.
 893  */
 894
 895 void
 896 dns_zone_setupdatedisabled(dns_zone_t *zone, isc_boolean_t state);
 897 /*%<
 898  * Set update disabled.
 899  * Should only be called only when running in isc_task_exclusive() mode.
 900  * Failure to do so may result in updates being committed after the
 901  * call has been made.
 902  */
 903
 904 isc_boolean_t
 905 dns_zone_getzeronosoattl(dns_zone_t *zone);
 906 /*%<
 907  * Return zero-no-soa-ttl status.
 908  */
 909
 910 void
 911 dns_zone_setzeronosoattl(dns_zone_t *zone, isc_boolean_t state);
 912 /*%<
 913  * Set zero-no-soa-ttl status.
 914  */
 915
 916 void
 917 dns_zone_setchecknames(dns_zone_t *zone, dns_severity_t severity);
 918 /*%<
 919  *      Set the severity of name checking when loading a zone.
 920  *
 921  * Require:
 922  * \li     'zone' to be a valid zone.
 923  */
 924
 925 dns_severity_t
 926 dns_zone_getchecknames(dns_zone_t *zone);
 927 /*%<
 928  *      Return the current severity of name checking.
 929  *
 930  * Require:
 931  *\li   'zone' to be a valid zone.
 932  */
 933
 934 void
 935 dns_zone_setjournalsize(dns_zone_t *zone, isc_int32_t size);
 936 /*%<
 937  *      Sets the journal size for the zone.
 938  *
 939  * Requires:
 940  *\li   'zone' to be a valid zone.
 941  */
 942
 943 isc_int32_t
 944 dns_zone_getjournalsize(dns_zone_t *zone);
 945 /*%<
 946  *      Return the journal size as set with a previous call to
 947  *      dns_zone_setjournalsize().
 948  *
 949  * Requires:
 950  *\li   'zone' to be a valid zone.
 951  */
 952
 953 isc_result_t
 954 dns_zone_notifyreceive(dns_zone_t *zone, isc_sockaddr_t *from,
 955                        dns_message_t *msg);
 956 /*%<
 957  *      Tell the zone that it has received a NOTIFY message from another
 958  *      server.  This may cause some zone maintenance activity to occur.
 959  *
 960  * Requires:
 961  *\li   'zone' to be a valid zone.
 962  *\li   '*from' to contain the address of the server from which 'msg'
 963  *              was received.
 964  *\li   'msg' a message with opcode NOTIFY and qr clear.
 965  *
 966  * Returns:
 967  *\li   DNS_R_REFUSED
 968  *\li   DNS_R_NOTIMP
 969  *\li   DNS_R_FORMERR
 970  *\li   DNS_R_SUCCESS
 971  */
 972
 973 void
 974 dns_zone_setmaxxfrin(dns_zone_t *zone, isc_uint32_t maxxfrin);
 975 /*%<
 976  * Set the maximum time (in seconds) that a zone transfer in (AXFR/IXFR)
 977  * of this zone will use before being aborted.
 978  *
 979  * Requires:
 980  * \li  'zone' to be valid initialised zone.
 981  */
 982
 983 isc_uint32_t
 984 dns_zone_getmaxxfrin(dns_zone_t *zone);
 985 /*%<
 986  * Returns the maximum transfer time for this zone.  This will be
 987  * either the value set by the last call to dns_zone_setmaxxfrin() or
 988  * the default value of 1 hour.
 989  *
 990  * Requires:
 991  *\li   'zone' to be valid initialised zone.
 992  */
 993
 994 void
 995 dns_zone_setmaxxfrout(dns_zone_t *zone, isc_uint32_t maxxfrout);
 996 /*%<
 997  * Set the maximum time (in seconds) that a zone transfer out (AXFR/IXFR)
 998  * of this zone will use before being aborted.
 999  *
1000  * Requires:
1001  * \li  'zone' to be valid initialised zone.
1002  */
1003
1004 isc_uint32_t
1005 dns_zone_getmaxxfrout(dns_zone_t *zone);
1006 /*%<
1007  * Returns the maximum transfer time for this zone.  This will be
1008  * either the value set by the last call to dns_zone_setmaxxfrout() or
1009  * the default value of 1 hour.
1010  *
1011  * Requires:
1012  *\li   'zone' to be valid initialised zone.
1013  */
1014
1015 isc_result_t
1016 dns_zone_setjournal(dns_zone_t *zone, const char *journal);
1017 /*%<
1018  * Sets the filename used for journaling updates / IXFR transfers.
1019  * The default journal name is set by dns_zone_setfile() to be
1020  * "file.jnl".  If 'journal' is NULL, the zone will have no
1021  * journal name.
1022  *
1023  * Requires:
1024  *\li   'zone' to be a valid zone.
1025  *
1026  * Returns:
1027  *\li   #ISC_R_SUCCESS
1028  *\li   #ISC_R_NOMEMORY
1029  */
1030
1031 char *
1032 dns_zone_getjournal(dns_zone_t *zone);
1033 /*%<
1034  * Returns the journal name associated with this zone.
1035  * If no journal has been set this will be NULL.
1036  *
1037  * Requires:
1038  *\li   'zone' to be valid initialised zone.
1039  */
1040
1041 dns_zonetype_t
1042 dns_zone_gettype(dns_zone_t *zone);
1043 /*%<
1044  * Returns the type of the zone (master/slave/etc.)
1045  *
1046  * Requires:
1047  *\li   'zone' to be valid initialised zone.
1048  */
1049
1050 void
1051 dns_zone_settask(dns_zone_t *zone, isc_task_t *task);
1052 /*%<
1053  * Give a zone a task to work with.  Any current task will be detached.
1054  *
1055  * Requires:
1056  *\li   'zone' to be valid.
1057  *\li   'task' to be valid.
1058  */
1059
1060 void
1061 dns_zone_gettask(dns_zone_t *zone, isc_task_t **target);
1062 /*%<
1063  * Attach '*target' to the zone's task.
1064  *
1065  * Requires:
1066  *\li   'zone' to be valid initialised zone.
1067  *\li   'zone' to have a task.
1068  *\li   'target' to be != NULL && '*target' == NULL.
1069  */
1070
1071 void
1072 dns_zone_notify(dns_zone_t *zone);
1073 /*%<
1074  * Generate notify events for this zone.
1075  *
1076  * Requires:
1077  *\li   'zone' to be a valid zone.
1078  */
1079
1080 isc_result_t
1081 dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, isc_boolean_t dump);
1082 /*%<
1083  * Replace the database of "zone" with a new database "db".
1084  *
1085  * If "dump" is ISC_TRUE, then the new zone contents are dumped
1086  * into to the zone's master file for persistence.  When replacing
1087  * a zone database by one just loaded from a master file, set
1088  * "dump" to ISC_FALSE to avoid a redundant redump of the data just
1089  * loaded.  Otherwise, it should be set to ISC_TRUE.
1090  *
1091  * If the "diff-on-reload" option is enabled in the configuration file,
1092  * the differences between the old and the new database are added to the
1093  * journal file, and the master file dump is postponed.
1094  *
1095  * Requires:
1096  * \li  'zone' to be a valid zone.
1097  *
1098  * Returns:
1099  * \li  DNS_R_SUCCESS
1100  * \li  DNS_R_BADZONE   zone failed basic consistency checks:
1101  *                      * a single SOA must exist
1102  *                      * some NS records must exist.
1103  *      Others
1104  */
1105
1106 isc_uint32_t
1107 dns_zone_getidlein(dns_zone_t *zone);
1108 /*%<
1109  * Requires:
1110  * \li  'zone' to be a valid zone.
1111  *
1112  * Returns:
1113  * \li  number of seconds of idle time before we abort the transfer in.
1114  */
1115
1116 void
1117 dns_zone_setidlein(dns_zone_t *zone, isc_uint32_t idlein);
1118 /*%<
1119  * \li  Set the idle timeout for transfer the.
1120  * \li  Zero set the default value, 1 hour.
1121  *
1122  * Requires:
1123  * \li  'zone' to be a valid zone.
1124  */
1125
1126 isc_uint32_t
1127 dns_zone_getidleout(dns_zone_t *zone);
1128 /*%<
1129  *
1130  * Requires:
1131  * \li  'zone' to be a valid zone.
1132  *
1133  * Returns:
1134  * \li  number of seconds of idle time before we abort a transfer out.
1135  */
1136
1137 void
1138 dns_zone_setidleout(dns_zone_t *zone, isc_uint32_t idleout);
1139 /*%<
1140  * \li  Set the idle timeout for transfers out.
1141  * \li  Zero set the default value, 1 hour.
1142  *
1143  * Requires:
1144  * \li  'zone' to be a valid zone.
1145  */
1146
1147 void
1148 dns_zone_getssutable(dns_zone_t *zone, dns_ssutable_t **table);
1149 /*%<
1150  * Get the simple-secure-update policy table.
1151  *
1152  * Requires:
1153  * \li  'zone' to be a valid zone.
1154  */
1155
1156 void
1157 dns_zone_setssutable(dns_zone_t *zone, dns_ssutable_t *table);
1158 /*%<
1159  * Set / clear the simple-secure-update policy table.
1160  *
1161  * Requires:
1162  * \li  'zone' to be a valid zone.
1163  */
1164
1165 isc_mem_t *
1166 dns_zone_getmctx(dns_zone_t *zone);
1167 /*%<
1168  * Get the memory context of a zone.
1169  *
1170  * Requires:
1171  * \li  'zone' to be a valid zone.
1172  */
1173
1174 dns_zonemgr_t *
1175 dns_zone_getmgr(dns_zone_t *zone);
1176 /*%<
1177  *      If 'zone' is managed return the zone manager otherwise NULL.
1178  *
1179  * Requires:
1180  * \li  'zone' to be a valid zone.
1181  */
1182
1183 void
1184 dns_zone_setsigvalidityinterval(dns_zone_t *zone, isc_uint32_t interval);
1185 /*%<
1186  * Set the zone's RRSIG validity interval.  This is the length of time
1187  * for which DNSSEC signatures created as a result of dynamic updates
1188  * to secure zones will remain valid, in seconds.
1189  *
1190  * Requires:
1191  * \li  'zone' to be a valid zone.
1192  */
1193
1194 isc_uint32_t
1195 dns_zone_getsigvalidityinterval(dns_zone_t *zone);
1196 /*%<
1197  * Get the zone's RRSIG validity interval.
1198  *
1199  * Requires:
1200  * \li  'zone' to be a valid zone.
1201  */
1202
1203 void
1204 dns_zone_setsigresigninginterval(dns_zone_t *zone, isc_uint32_t interval);
1205 /*%<
1206  * Set the zone's RRSIG re-signing interval.  A dynamic zone's RRSIG's
1207  * will be re-signed 'interval' amount of time before they expire.
1208  *
1209  * Requires:
1210  * \li  'zone' to be a valid zone.
1211  */
1212
1213 isc_uint32_t
1214 dns_zone_getsigresigninginterval(dns_zone_t *zone);
1215 /*%<
1216  * Get the zone's RRSIG re-signing interval.
1217  *
1218  * Requires:
1219  * \li  'zone' to be a valid zone.
1220  */
1221
1222 void
1223 dns_zone_setnotifytype(dns_zone_t *zone, dns_notifytype_t notifytype);
1224 /*%<
1225  * Sets zone notify method to "notifytype"
1226  */
1227
1228 isc_result_t
1229 dns_zone_forwardupdate(dns_zone_t *zone, dns_message_t *msg,
1230                        dns_updatecallback_t callback, void *callback_arg);
1231 /*%<
1232  * Forward 'msg' to each master in turn until we get an answer or we
1233  * have exhausted the list of masters. 'callback' will be called with
1234  * ISC_R_SUCCESS if we get an answer and the returned message will be
1235  * passed as 'answer_message', otherwise a non ISC_R_SUCCESS result code
1236  * will be passed and answer_message will be NULL.  The callback function
1237  * is responsible for destroying 'answer_message'.
1238  *              (callback)(callback_arg, result, answer_message);
1239  *
1240  * Require:
1241  *\li   'zone' to be valid
1242  *\li   'msg' to be valid.
1243  *\li   'callback' to be non NULL.
1244  * Returns:
1245  *\li   #ISC_R_SUCCESS if the message has been forwarded,
1246  *\li   #ISC_R_NOMEMORY
1247  *\li   Others
1248  */
1249
1250 isc_result_t
1251 dns_zone_next(dns_zone_t *zone, dns_zone_t **next);
1252 /*%<
1253  * Find the next zone in the list of managed zones.
1254  *
1255  * Requires:
1256  *\li   'zone' to be valid
1257  *\li   The zone manager for the indicated zone MUST be locked
1258  *      by the caller.  This is not checked.
1259  *\li   'next' be non-NULL, and '*next' be NULL.
1260  *
1261  * Ensures:
1262  *\li   'next' points to a valid zone (result ISC_R_SUCCESS) or to NULL
1263  *      (result ISC_R_NOMORE).
1264  */
1265
1266
1267
1268 isc_result_t
1269 dns_zone_first(dns_zonemgr_t *zmgr, dns_zone_t **first);
1270 /*%<
1271  * Find the first zone in the list of managed zones.
1272  *
1273  * Requires:
1274  *\li   'zonemgr' to be valid
1275  *\li   The zone manager for the indicated zone MUST be locked
1276  *      by the caller.  This is not checked.
1277  *\li   'first' be non-NULL, and '*first' be NULL
1278  *
1279  * Ensures:
1280  *\li   'first' points to a valid zone (result ISC_R_SUCCESS) or to NULL
1281  *      (result ISC_R_NOMORE).
1282  */
1283
1284 isc_result_t
1285 dns_zone_setkeydirectory(dns_zone_t *zone, const char *directory);
1286 /*%<
1287  *      Sets the name of the directory where private keys used for
1288  *      online signing of dynamic zones are found.
1289  *
1290  * Require:
1291  *\li   'zone' to be a valid zone.
1292  *
1293  * Returns:
1294  *\li   #ISC_R_NOMEMORY
1295  *\li   #ISC_R_SUCCESS
1296  */
1297
1298 const char *
1299 dns_zone_getkeydirectory(dns_zone_t *zone);
1300 /*%<
1301  *      Gets the name of the directory where private keys used for
1302  *      online signing of dynamic zones are found.
1303  *
1304  * Requires:
1305  *\li   'zone' to be valid initialised zone.
1306  *
1307  * Returns:
1308  *      Pointer to null-terminated file name, or NULL.
1309  */
1310
1311
1312 isc_result_t
1313 dns_zonemgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr,
1314                    isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr,
1315                    dns_zonemgr_t **zmgrp);
1316 /*%<
1317  * Create a zone manager.
1318  *
1319  * Requires:
1320  *\li   'mctx' to be a valid memory context.
1321  *\li   'taskmgr' to be a valid task manager.
1322  *\li   'timermgr' to be a valid timer manager.
1323  *\li   'zmgrp' to point to a NULL pointer.
1324  */
1325
1326 isc_result_t
1327 dns_zonemgr_managezone(dns_zonemgr_t *zmgr, dns_zone_t *zone);
1328 /*%<
1329  *      Bring the zone under control of a zone manager.
1330  *
1331  * Require:
1332  *\li   'zmgr' to be a valid zone manager.
1333  *\li   'zone' to be a valid zone.
1334  */
1335
1336 isc_result_t
1337 dns_zonemgr_forcemaint(dns_zonemgr_t *zmgr);
1338 /*%<
1339  * Force zone maintenance of all zones managed by 'zmgr' at its
1340  * earliest convenience.
1341  */
1342
1343 void
1344 dns_zonemgr_resumexfrs(dns_zonemgr_t *zmgr);
1345 /*%<
1346  * Attempt to start any stalled zone transfers.
1347  */
1348
1349 void
1350 dns_zonemgr_shutdown(dns_zonemgr_t *zmgr);
1351 /*%<
1352  *      Shut down the zone manager.
1353  *
1354  * Requires:
1355  *\li   'zmgr' to be a valid zone manager.
1356  */
1357
1358 void
1359 dns_zonemgr_attach(dns_zonemgr_t *source, dns_zonemgr_t **target);
1360 /*%<
1361  *      Attach '*target' to 'source' incrementing its external
1362  *      reference count.
1363  *
1364  * Require:
1365  *\li   'zone' to be a valid zone.
1366  *\li   'target' to be non NULL and '*target' to be NULL.
1367  */
1368
1369 void
1370 dns_zonemgr_detach(dns_zonemgr_t **zmgrp);
1371 /*%<
1372  *       Detach from a zone manager.
1373  *
1374  * Requires:
1375  *\li   '*zmgrp' is a valid, non-NULL zone manager pointer.
1376  *
1377  * Ensures:
1378  *\li   '*zmgrp' is NULL.
1379  */
1380
1381 void
1382 dns_zonemgr_releasezone(dns_zonemgr_t *zmgr, dns_zone_t *zone);
1383 /*%<
1384  *      Release 'zone' from the managed by 'zmgr'.  'zmgr' is implicitly
1385  *      detached from 'zone'.
1386  *
1387  * Requires:
1388  *\li   'zmgr' to be a valid zone manager.
1389  *\li   'zone' to be a valid zone.
1390  *\li   'zmgr' == 'zone->zmgr'
1391  *
1392  * Ensures:
1393  *\li   'zone->zmgr' == NULL;
1394  */
1395
1396 void
1397 dns_zonemgr_settransfersin(dns_zonemgr_t *zmgr, isc_uint32_t value);
1398 /*%<
1399  *      Set the maximum number of simultaneous transfers in allowed by
1400  *      the zone manager.
1401  *
1402  * Requires:
1403  *\li   'zmgr' to be a valid zone manager.
1404  */
1405
1406 isc_uint32_t
1407 dns_zonemgr_getttransfersin(dns_zonemgr_t *zmgr);
1408 /*%<
1409  *      Return the maximum number of simultaneous transfers in allowed.
1410  *
1411  * Requires:
1412  *\li   'zmgr' to be a valid zone manager.
1413  */
1414
1415 void
1416 dns_zonemgr_settransfersperns(dns_zonemgr_t *zmgr, isc_uint32_t value);
1417 /*%<
1418  *      Set the number of zone transfers allowed per nameserver.
1419  *
1420  * Requires:
1421  *\li   'zmgr' to be a valid zone manager
1422  */
1423
1424 isc_uint32_t
1425 dns_zonemgr_getttransfersperns(dns_zonemgr_t *zmgr);
1426 /*%<
1427  *      Return the number of transfers allowed per nameserver.
1428  *
1429  * Requires:
1430  *\li   'zmgr' to be a valid zone manager.
1431  */
1432
1433 void
1434 dns_zonemgr_setiolimit(dns_zonemgr_t *zmgr, isc_uint32_t iolimit);
1435 /*%<
1436  *      Set the number of simultaneous file descriptors available for
1437  *      reading and writing masterfiles.
1438  *
1439  * Requires:
1440  *\li   'zmgr' to be a valid zone manager.
1441  *\li   'iolimit' to be positive.
1442  */
1443
1444 isc_uint32_t
1445 dns_zonemgr_getiolimit(dns_zonemgr_t *zmgr);
1446 /*%<
1447  *      Get the number of simultaneous file descriptors available for
1448  *      reading and writing masterfiles.
1449  *
1450  * Requires:
1451  *\li   'zmgr' to be a valid zone manager.
1452  */
1453
1454 void
1455 dns_zonemgr_setserialqueryrate(dns_zonemgr_t *zmgr, unsigned int value);
1456 /*%<
1457  *      Set the number of SOA queries sent per second.
1458  *
1459  * Requires:
1460  *\li   'zmgr' to be a valid zone manager
1461  */
1462
1463 unsigned int
1464 dns_zonemgr_getserialqueryrate(dns_zonemgr_t *zmgr);
1465 /*%<
1466  *      Return the number of SOA queries sent per second.
1467  *
1468  * Requires:
1469  *\li   'zmgr' to be a valid zone manager.
1470  */
1471
1472 unsigned int
1473 dns_zonemgr_getcount(dns_zonemgr_t *zmgr, int state);
1474 /*%<
1475  *      Returns the number of zones in the specified state.
1476  *
1477  * Requires:
1478  *\li   'zmgr' to be a valid zone manager.
1479  *\li   'state' to be a valid DNS_ZONESTATE_ constant.
1480  */
1481
1482 void
1483 dns_zonemgr_unreachableadd(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote,
1484                            isc_sockaddr_t *local, isc_time_t *now);
1485 /*%<
1486  *      Add the pair of addresses to the unreachable cache.
1487  *
1488  * Requires:
1489  *\li   'zmgr' to be a valid zone manager.
1490  *\li   'remote' to be a valid sockaddr.
1491  *\li   'local' to be a valid sockaddr.
1492  */
1493
1494 void
1495 dns_zone_forcereload(dns_zone_t *zone);
1496 /*%<
1497  *      Force a reload of specified zone.
1498  *
1499  * Requires:
1500  *\li      'zone' to be a valid zone.
1501  */
1502
1503 isc_boolean_t
1504 dns_zone_isforced(dns_zone_t *zone);
1505 /*%<
1506  *      Check if the zone is waiting a forced reload.
1507  *
1508  * Requires:
1509  * \li     'zone' to be a valid zone.
1510  */
1511
1512 isc_result_t
1513 dns_zone_setstatistics(dns_zone_t *zone, isc_boolean_t on);
1514 /*%<
1515  * This function is obsoleted by dns_zone_setrequeststats().
1516  */
1517
1518 isc_uint64_t *
1519 dns_zone_getstatscounters(dns_zone_t *zone);
1520 /*%<
1521  * This function is obsoleted by dns_zone_getrequeststats().
1522  */
1523
1524 void
1525 dns_zone_setstats(dns_zone_t *zone, isc_stats_t *stats);
1526 /*%<
1527  * Set a general zone-maintenance statistics set 'stats' for 'zone'.  This
1528  * function is expected to be called only on zone creation (when necessary).
1529  * Once installed, it cannot be removed or replaced.  Also, there is no
1530  * interface to get the installed stats from the zone; the caller must keep the
1531  * stats to reference (e.g. dump) it later.
1532  *
1533  * Requires:
1534  * \li  'zone' to be a valid zone and does not have a statistics set already
1535  *      installed.
1536  *
1537  *\li   stats is a valid statistics supporting zone statistics counters
1538  *      (see dns/stats.h).
1539  */
1540
1541 void
1542 dns_zone_setrequeststats(dns_zone_t *zone, isc_stats_t *stats);
1543 /*%<
1544  * Set an additional statistics set to zone.  It is attached in the zone
1545  * but is not counted in the zone module; only the caller updates the counters.
1546  *
1547  * Requires:
1548  * \li  'zone' to be a valid zone.
1549  *
1550  *\li   stats is a valid statistics.
1551  */
1552
1553 isc_stats_t *
1554 dns_zone_getrequeststats(dns_zone_t *zone);
1555 /*%<
1556  * Get the additional statistics for zone, if one is installed.
1557  *
1558  * Requires:
1559  * \li  'zone' to be a valid zone.
1560  *
1561  * Returns:
1562  * \li  when available, a pointer to the statistics set installed in zone;
1563  *      otherwise NULL.
1564  */
1565
1566 void
1567 dns_zone_dialup(dns_zone_t *zone);
1568 /*%<
1569  * Perform dialup-time maintenance on 'zone'.
1570  */
1571
1572 void
1573 dns_zone_setdialup(dns_zone_t *zone, dns_dialuptype_t dialup);
1574 /*%<
1575  * Set the dialup type of 'zone' to 'dialup'.
1576  *
1577  * Requires:
1578  * \li  'zone' to be valid initialised zone.
1579  *\li   'dialup' to be a valid dialup type.
1580  */
1581
1582 void
1583 dns_zone_log(dns_zone_t *zone, int level, const char *msg, ...)
1584         ISC_FORMAT_PRINTF(3, 4);
1585 /*%<
1586  * Log the message 'msg...' at 'level', including text that identifies
1587  * the message as applying to 'zone'.
1588  */
1589
1590 void
1591 dns_zone_logc(dns_zone_t *zone, isc_logcategory_t *category, int level,
1592               const char *msg, ...) ISC_FORMAT_PRINTF(4, 5);
1593 /*%<
1594  * Log the message 'msg...' at 'level', including text that identifies
1595  * the message as applying to 'zone'.
1596  */
1597
1598 void
1599 dns_zone_name(dns_zone_t *zone, char *buf, size_t len);
1600 /*%<
1601  * Return the name of the zone with class and view.
1602  *
1603  * Requires:
1604  *\li   'zone' to be valid.
1605  *\li   'buf' to be non NULL.
1606  */
1607
1608 isc_result_t
1609 dns_zone_checknames(dns_zone_t *zone, dns_name_t *name, dns_rdata_t *rdata);
1610 /*%<
1611  * Check if this record meets the check-names policy.
1612  *
1613  * Requires:
1614  *      'zone' to be valid.
1615  *      'name' to be valid.
1616  *      'rdata' to be valid.
1617  *
1618  * Returns:
1619  *      DNS_R_SUCCESS           passed checks.
1620  *      DNS_R_BADOWNERNAME      failed ownername checks.
1621  *      DNS_R_BADNAME           failed rdata checks.
1622  */
1623
1624 void
1625 dns_zone_setacache(dns_zone_t *zone, dns_acache_t *acache);
1626 /*%<
1627  *      Associate the zone with an additional cache.
1628  *
1629  * Require:
1630  *      'zone' to be a valid zone.
1631  *      'acache' to be a non NULL pointer.
1632  *
1633  * Ensures:
1634  *      'zone' will have a reference to 'acache'
1635  */
1636
1637 void
1638 dns_zone_setcheckmx(dns_zone_t *zone, dns_checkmxfunc_t checkmx);
1639 /*%<
1640  *      Set the post load integrity callback function 'checkmx'.
1641  *      'checkmx' will be called if the MX is not within the zone.
1642  *
1643  * Require:
1644  *      'zone' to be a valid zone.
1645  */
1646
1647 void
1648 dns_zone_setchecksrv(dns_zone_t *zone, dns_checkmxfunc_t checksrv);
1649 /*%<
1650  *      Set the post load integrity callback function 'checksrv'.
1651  *      'checksrv' will be called if the SRV TARGET is not within the zone.
1652  *
1653  * Require:
1654  *      'zone' to be a valid zone.
1655  */
1656
1657 void
1658 dns_zone_setcheckns(dns_zone_t *zone, dns_checknsfunc_t checkns);
1659 /*%<
1660  *      Set the post load integrity callback function 'checkmx'.
1661  *      'checkmx' will be called if the MX is not within the zone.
1662  *
1663  * Require:
1664  *      'zone' to be a valid zone.
1665  */
1666
1667 void
1668 dns_zone_setnotifydelay(dns_zone_t *zone, isc_uint32_t delay);
1669 /*%<
1670  * Set the minimum delay between sets of notify messages.
1671  *
1672  * Requires:
1673  *      'zone' to be valid.
1674  */
1675
1676 isc_uint32_t
1677 dns_zone_getnotifydelay(dns_zone_t *zone);
1678 /*%<
1679  * Get the minimum delay between sets of notify messages.
1680  *
1681  * Requires:
1682  *      'zone' to be valid.
1683  */
1684
1685 void
1686 dns_zone_setisself(dns_zone_t *zone, dns_isselffunc_t isself, void *arg);
1687 /*%<
1688  * Set the isself callback function and argument.
1689  *
1690  * isc_boolean_t
1691  * isself(dns_view_t *myview, dns_tsigkey_t *mykey, isc_netaddr_t *srcaddr,
1692  *        isc_netaddr_t *destaddr, dns_rdataclass_t rdclass, void *arg);
1693  *
1694  * 'isself' returns ISC_TRUE if a non-recursive query from 'srcaddr' to
1695  * 'destaddr' with optional key 'mykey' for class 'rdclass' would be
1696  * delivered to 'myview'.
1697  */
1698
1699 void
1700 dns_zone_setnodes(dns_zone_t *zone, isc_uint32_t nodes);
1701 /*%<
1702  * Set the number of nodes that will be checked per quantum.
1703  */
1704
1705 void
1706 dns_zone_setsignatures(dns_zone_t *zone, isc_uint32_t signatures);
1707 /*%<
1708  * Set the number of signatures that will be generated per quantum.
1709  */
1710
1711 isc_result_t
1712 dns_zone_signwithkey(dns_zone_t *zone, dns_secalg_t algorithm,
1713                      isc_uint16_t keyid, isc_boolean_t delete);
1714 /*%<
1715  * Initiate/resume signing of the entire zone with the zone DNSKEY(s)
1716  * that match the given algorithm and keyid.
1717  */
1718
1719 isc_result_t
1720 dns_zone_addnsec3chain(dns_zone_t *zone, dns_rdata_nsec3param_t *nsec3param);
1721 /*%<
1722  * Incrementally add a NSEC3 chain that corresponds to 'nsec3param'.
1723  */
1724
1725 void
1726 dns_zone_setprivatetype(dns_zone_t *zone, dns_rdatatype_t type);
1727 dns_rdatatype_t
1728 dns_zone_getprivatetype(dns_zone_t *zone);
1729 /*
1730  * Get/Set the private record type.  It is expected that these interfaces
1731  * will not be permanent.
1732  */
1733
1734 ISC_LANG_ENDDECLS
1735
1736 #endif /* DNS_ZONE_H */