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