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