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

   1 /*
   2  * Copyright (C) 2004-2007, 2009, 2011, 2012  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  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: sdb.h,v 1.25 2011/10/11 23:46:45 tbox Exp $ */
  19
  20 #ifndef DNS_SDB_H
  21 #define DNS_SDB_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file dns/sdb.h
  28  * \brief
  29  * Simple database API.
  30  */
  31
  32 /***
  33  *** Imports
  34  ***/
  35
  36 #include <isc/lang.h>
  37
  38 #include <dns/clientinfo.h>
  39 #include <dns/types.h>
  40
  41 /***
  42  *** Types
  43  ***/
  44
  45 /*%
  46  * A simple database.  This is an opaque type.
  47  */
  48 typedef struct dns_sdb dns_sdb_t;
  49
  50 /*%
  51  * A simple database lookup in progress.  This is an opaque type.
  52  */
  53 typedef struct dns_sdblookup dns_sdblookup_t;
  54
  55 /*%
  56  * A simple database traversal in progress.  This is an opaque type.
  57  */
  58 typedef struct dns_sdballnodes dns_sdballnodes_t;
  59
  60 typedef isc_result_t
  61 (*dns_sdblookupfunc_t)(const char *zone, const char *name, void *dbdata,
  62                        dns_sdblookup_t *lookup,
  63                        dns_clientinfomethods_t *methods,
  64                        dns_clientinfo_t *clientinfo);
  65 typedef isc_result_t
  66 (*dns_sdblookup2func_t)(const dns_name_t *zone, const dns_name_t *name,
  67                         void *dbdata, dns_sdblookup_t *lookup,
  68                         dns_clientinfomethods_t *methods,
  69                         dns_clientinfo_t *clientinfo);
  70
  71 typedef isc_result_t
  72 (*dns_sdbauthorityfunc_t)(const char *zone, void *dbdata, dns_sdblookup_t *);
  73
  74 typedef isc_result_t
  75 (*dns_sdballnodesfunc_t)(const char *zone, void *dbdata,
  76                          dns_sdballnodes_t *allnodes);
  77
  78 typedef isc_result_t
  79 (*dns_sdbcreatefunc_t)(const char *zone, int argc, char **argv,
  80                        void *driverdata, void **dbdata);
  81
  82 typedef void
  83 (*dns_sdbdestroyfunc_t)(const char *zone, void *driverdata, void **dbdata);
  84
  85
  86 typedef struct dns_sdbmethods {
  87         dns_sdblookupfunc_t     lookup;
  88         dns_sdbauthorityfunc_t  authority;
  89         dns_sdballnodesfunc_t   allnodes;
  90         dns_sdbcreatefunc_t     create;
  91         dns_sdbdestroyfunc_t    destroy;
  92         dns_sdblookup2func_t    lookup2;
  93 } dns_sdbmethods_t;
  94
  95 /***
  96  *** Functions
  97  ***/
  98
  99 ISC_LANG_BEGINDECLS
 100
 101 #define DNS_SDBFLAG_RELATIVEOWNER 0x00000001U
 102 #define DNS_SDBFLAG_RELATIVERDATA 0x00000002U
 103 #define DNS_SDBFLAG_THREADSAFE 0x00000004U
 104 #define DNS_SDBFLAG_DNS64 0x00000008U
 105
 106 isc_result_t
 107 dns_sdb_register(const char *drivername, const dns_sdbmethods_t *methods,
 108                  void *driverdata, unsigned int flags, isc_mem_t *mctx,
 109                  dns_sdbimplementation_t **sdbimp);
 110 /*%<
 111  * Register a simple database driver for the database type 'drivername',
 112  * implemented by the functions in '*methods'.
 113  *
 114  * sdbimp must point to a NULL dns_sdbimplementation_t pointer.  That is,
 115  * sdbimp != NULL && *sdbimp == NULL.  It will be assigned a value that
 116  * will later be used to identify the driver when deregistering it.
 117  *
 118  * The name server will perform lookups in the database by calling the
 119  * function 'lookup', passing it a printable zone name 'zone', a printable
 120  * domain name 'name', and a copy of the argument 'dbdata' that
 121  * was potentially returned by the create function.  The 'dns_sdblookup_t'
 122  * argument to 'lookup' and 'authority' is an opaque pointer to be passed to
 123  * ns_sdb_putrr().
 124  *
 125  * The lookup function returns the lookup results to the name server
 126  * by calling ns_sdb_putrr() once for each record found.  On success,
 127  * the return value of the lookup function should be ISC_R_SUCCESS.
 128  * If the domain name 'name' does not exist, the lookup function should
 129  * ISC_R_NOTFOUND.  Any other return value is treated as an error.
 130  *
 131  * Lookups at the zone apex will cause the server to also call the
 132  * function 'authority' (if non-NULL), which must provide an SOA record
 133  * and NS records for the zone by calling ns_sdb_putrr() once for each of
 134  * these records.  The 'authority' function may be NULL if invoking
 135  * the 'lookup' function on the zone apex will return SOA and NS records.
 136  *
 137  * The allnodes function, if non-NULL, fills in an opaque structure to be
 138  * used by a database iterator.  This allows the zone to be transferred.
 139  * This may use a considerable amount of memory for large zones, and the
 140  * zone transfer may not be fully RFC1035 compliant if the zone is
 141  * frequently changed.
 142  *
 143  * The create function will be called for each zone configured
 144  * into the name server using this database type.  It can be used
 145  * to create a "database object" containing zone specific data,
 146  * which can make use of the database arguments specified in the
 147  * name server configuration.
 148  *
 149  * The destroy function will be called to free the database object
 150  * when its zone is destroyed.
 151  *
 152  * The create and destroy functions may be NULL.
 153  *
 154  * If flags includes DNS_SDBFLAG_RELATIVEOWNER, the lookup and authority
 155  * functions will be called with relative names rather than absolute names.
 156  * The string "@" represents the zone apex in this case.
 157  *
 158  * If flags includes DNS_SDBFLAG_RELATIVERDATA, the rdata strings may
 159  * include relative names.  Otherwise, all names in the rdata string must
 160  * be absolute.  Be aware that if relative names are allowed, any
 161  * absolute names must contain a trailing dot.
 162  *
 163  * If flags includes DNS_SDBFLAG_THREADSAFE, the driver must be able to
 164  * handle multiple lookups in parallel.  Otherwise, calls into the driver
 165  * are serialized.
 166  */
 167
 168 void
 169 dns_sdb_unregister(dns_sdbimplementation_t **sdbimp);
 170 /*%<
 171  * Removes the simple database driver from the list of registered database
 172  * types.  There must be no active databases of this type when this function
 173  * is called.
 174  */
 175
 176 /*% See dns_sdb_putradata() */
 177 isc_result_t
 178 dns_sdb_putrr(dns_sdblookup_t *lookup, const char *type, dns_ttl_t ttl,
 179               const char *data);
 180 isc_result_t
 181 dns_sdb_putrdata(dns_sdblookup_t *lookup, dns_rdatatype_t type, dns_ttl_t ttl,
 182                  const unsigned char *rdata, unsigned int rdlen);
 183 /*%<
 184  * Add a single resource record to the lookup structure to be
 185  * returned in the query response.  dns_sdb_putrr() takes the
 186  * resource record in master file text format as a null-terminated
 187  * string, and dns_sdb_putrdata() takes the raw RDATA in
 188  * uncompressed wire format.
 189  */
 190
 191 /*% See dns_sdb_putnamerdata() */
 192 isc_result_t
 193 dns_sdb_putnamedrr(dns_sdballnodes_t *allnodes, const char *name,
 194                    const char *type, dns_ttl_t ttl, const char *data);
 195 isc_result_t
 196 dns_sdb_putnamedrdata(dns_sdballnodes_t *allnodes, const char *name,
 197                       dns_rdatatype_t type, dns_ttl_t ttl,
 198                       const void *rdata, unsigned int rdlen);
 199 /*%<
 200  * Add a single resource record to the allnodes structure to be
 201  * included in a zone transfer response, in text or wire
 202  * format as above.
 203  */
 204
 205 isc_result_t
 206 dns_sdb_putsoa(dns_sdblookup_t *lookup, const char *mname, const char *rname,
 207                isc_uint32_t serial);
 208 /*%<
 209  * This function may optionally be called from the 'authority' callback
 210  * to simplify construction of the SOA record for 'zone'.  It will
 211  * provide a SOA listing 'mname' as as the master server and 'rname' as
 212  * the responsible person mailbox.  It is the responsibility of the
 213  * driver to increment the serial number between responses if necessary.
 214  * All other SOA fields will have reasonable default values.
 215  */
 216
 217 ISC_LANG_ENDDECLS
 218
 219 #endif /* DNS_SDB_H */