1135446Strhodes/* 2254897Serwin * Copyright (C) 2004-2007, 2009, 2011, 2012 Internet Systems Consortium, Inc. ("ISC") 3135446Strhodes * Copyright (C) 2000, 2001 Internet Software Consortium. 4135446Strhodes * 5193149Sdougb * Permission to use, copy, modify, and/or distribute this software for any 6135446Strhodes * purpose with or without fee is hereby granted, provided that the above 7135446Strhodes * copyright notice and this permission notice appear in all copies. 8135446Strhodes * 9135446Strhodes * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10135446Strhodes * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11135446Strhodes * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12135446Strhodes * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13135446Strhodes * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14135446Strhodes * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15135446Strhodes * PERFORMANCE OF THIS SOFTWARE. 16135446Strhodes */ 17135446Strhodes 18254897Serwin/* $Id: sdb.h,v 1.25 2011/10/11 23:46:45 tbox Exp $ */ 19135446Strhodes 20135446Strhodes#ifndef DNS_SDB_H 21135446Strhodes#define DNS_SDB_H 1 22135446Strhodes 23135446Strhodes/***** 24135446Strhodes ***** Module Info 25135446Strhodes *****/ 26135446Strhodes 27193149Sdougb/*! \file dns/sdb.h 28170222Sdougb * \brief 29135446Strhodes * Simple database API. 30135446Strhodes */ 31135446Strhodes 32135446Strhodes/*** 33135446Strhodes *** Imports 34135446Strhodes ***/ 35135446Strhodes 36135446Strhodes#include <isc/lang.h> 37135446Strhodes 38254897Serwin#include <dns/clientinfo.h> 39135446Strhodes#include <dns/types.h> 40135446Strhodes 41135446Strhodes/*** 42135446Strhodes *** Types 43135446Strhodes ***/ 44135446Strhodes 45170222Sdougb/*% 46135446Strhodes * A simple database. This is an opaque type. 47135446Strhodes */ 48135446Strhodestypedef struct dns_sdb dns_sdb_t; 49135446Strhodes 50170222Sdougb/*% 51135446Strhodes * A simple database lookup in progress. This is an opaque type. 52135446Strhodes */ 53135446Strhodestypedef struct dns_sdblookup dns_sdblookup_t; 54135446Strhodes 55170222Sdougb/*% 56135446Strhodes * A simple database traversal in progress. This is an opaque type. 57135446Strhodes */ 58135446Strhodestypedef struct dns_sdballnodes dns_sdballnodes_t; 59135446Strhodes 60135446Strhodestypedef isc_result_t 61135446Strhodes(*dns_sdblookupfunc_t)(const char *zone, const char *name, void *dbdata, 62254897Serwin dns_sdblookup_t *lookup, 63254897Serwin dns_clientinfomethods_t *methods, 64254897Serwin dns_clientinfo_t *clientinfo); 65236374Sdougbtypedef isc_result_t 66236374Sdougb(*dns_sdblookup2func_t)(const dns_name_t *zone, const dns_name_t *name, 67254897Serwin void *dbdata, dns_sdblookup_t *lookup, 68254897Serwin dns_clientinfomethods_t *methods, 69254897Serwin dns_clientinfo_t *clientinfo); 70135446Strhodes 71135446Strhodestypedef isc_result_t 72135446Strhodes(*dns_sdbauthorityfunc_t)(const char *zone, void *dbdata, dns_sdblookup_t *); 73135446Strhodes 74135446Strhodestypedef isc_result_t 75135446Strhodes(*dns_sdballnodesfunc_t)(const char *zone, void *dbdata, 76135446Strhodes dns_sdballnodes_t *allnodes); 77135446Strhodes 78135446Strhodestypedef isc_result_t 79135446Strhodes(*dns_sdbcreatefunc_t)(const char *zone, int argc, char **argv, 80135446Strhodes void *driverdata, void **dbdata); 81135446Strhodes 82135446Strhodestypedef void 83135446Strhodes(*dns_sdbdestroyfunc_t)(const char *zone, void *driverdata, void **dbdata); 84135446Strhodes 85135446Strhodes 86135446Strhodestypedef struct dns_sdbmethods { 87135446Strhodes dns_sdblookupfunc_t lookup; 88135446Strhodes dns_sdbauthorityfunc_t authority; 89135446Strhodes dns_sdballnodesfunc_t allnodes; 90135446Strhodes dns_sdbcreatefunc_t create; 91135446Strhodes dns_sdbdestroyfunc_t destroy; 92236374Sdougb dns_sdblookup2func_t lookup2; 93135446Strhodes} dns_sdbmethods_t; 94135446Strhodes 95135446Strhodes/*** 96135446Strhodes *** Functions 97135446Strhodes ***/ 98135446Strhodes 99135446StrhodesISC_LANG_BEGINDECLS 100135446Strhodes 101135446Strhodes#define DNS_SDBFLAG_RELATIVEOWNER 0x00000001U 102135446Strhodes#define DNS_SDBFLAG_RELATIVERDATA 0x00000002U 103135446Strhodes#define DNS_SDBFLAG_THREADSAFE 0x00000004U 104236374Sdougb#define DNS_SDBFLAG_DNS64 0x00000008U 105135446Strhodes 106135446Strhodesisc_result_t 107135446Strhodesdns_sdb_register(const char *drivername, const dns_sdbmethods_t *methods, 108135446Strhodes void *driverdata, unsigned int flags, isc_mem_t *mctx, 109135446Strhodes dns_sdbimplementation_t **sdbimp); 110170222Sdougb/*%< 111135446Strhodes * Register a simple database driver for the database type 'drivername', 112135446Strhodes * implemented by the functions in '*methods'. 113135446Strhodes * 114135446Strhodes * sdbimp must point to a NULL dns_sdbimplementation_t pointer. That is, 115135446Strhodes * sdbimp != NULL && *sdbimp == NULL. It will be assigned a value that 116135446Strhodes * will later be used to identify the driver when deregistering it. 117135446Strhodes * 118135446Strhodes * The name server will perform lookups in the database by calling the 119135446Strhodes * function 'lookup', passing it a printable zone name 'zone', a printable 120135446Strhodes * domain name 'name', and a copy of the argument 'dbdata' that 121135446Strhodes * was potentially returned by the create function. The 'dns_sdblookup_t' 122135446Strhodes * argument to 'lookup' and 'authority' is an opaque pointer to be passed to 123135446Strhodes * ns_sdb_putrr(). 124135446Strhodes * 125135446Strhodes * The lookup function returns the lookup results to the name server 126135446Strhodes * by calling ns_sdb_putrr() once for each record found. On success, 127135446Strhodes * the return value of the lookup function should be ISC_R_SUCCESS. 128135446Strhodes * If the domain name 'name' does not exist, the lookup function should 129135446Strhodes * ISC_R_NOTFOUND. Any other return value is treated as an error. 130135446Strhodes * 131135446Strhodes * Lookups at the zone apex will cause the server to also call the 132135446Strhodes * function 'authority' (if non-NULL), which must provide an SOA record 133135446Strhodes * and NS records for the zone by calling ns_sdb_putrr() once for each of 134135446Strhodes * these records. The 'authority' function may be NULL if invoking 135135446Strhodes * the 'lookup' function on the zone apex will return SOA and NS records. 136135446Strhodes * 137135446Strhodes * The allnodes function, if non-NULL, fills in an opaque structure to be 138135446Strhodes * used by a database iterator. This allows the zone to be transferred. 139135446Strhodes * This may use a considerable amount of memory for large zones, and the 140193149Sdougb * zone transfer may not be fully RFC1035 compliant if the zone is 141135446Strhodes * frequently changed. 142135446Strhodes * 143135446Strhodes * The create function will be called for each zone configured 144135446Strhodes * into the name server using this database type. It can be used 145193149Sdougb * to create a "database object" containing zone specific data, 146135446Strhodes * which can make use of the database arguments specified in the 147135446Strhodes * name server configuration. 148135446Strhodes * 149135446Strhodes * The destroy function will be called to free the database object 150135446Strhodes * when its zone is destroyed. 151135446Strhodes * 152135446Strhodes * The create and destroy functions may be NULL. 153135446Strhodes * 154135446Strhodes * If flags includes DNS_SDBFLAG_RELATIVEOWNER, the lookup and authority 155135446Strhodes * functions will be called with relative names rather than absolute names. 156135446Strhodes * The string "@" represents the zone apex in this case. 157135446Strhodes * 158135446Strhodes * If flags includes DNS_SDBFLAG_RELATIVERDATA, the rdata strings may 159135446Strhodes * include relative names. Otherwise, all names in the rdata string must 160135446Strhodes * be absolute. Be aware that if relative names are allowed, any 161135446Strhodes * absolute names must contain a trailing dot. 162135446Strhodes * 163135446Strhodes * If flags includes DNS_SDBFLAG_THREADSAFE, the driver must be able to 164135446Strhodes * handle multiple lookups in parallel. Otherwise, calls into the driver 165135446Strhodes * are serialized. 166135446Strhodes */ 167135446Strhodes 168135446Strhodesvoid 169135446Strhodesdns_sdb_unregister(dns_sdbimplementation_t **sdbimp); 170170222Sdougb/*%< 171135446Strhodes * Removes the simple database driver from the list of registered database 172135446Strhodes * types. There must be no active databases of this type when this function 173135446Strhodes * is called. 174135446Strhodes */ 175135446Strhodes 176170222Sdougb/*% See dns_sdb_putradata() */ 177135446Strhodesisc_result_t 178135446Strhodesdns_sdb_putrr(dns_sdblookup_t *lookup, const char *type, dns_ttl_t ttl, 179135446Strhodes const char *data); 180135446Strhodesisc_result_t 181135446Strhodesdns_sdb_putrdata(dns_sdblookup_t *lookup, dns_rdatatype_t type, dns_ttl_t ttl, 182135446Strhodes const unsigned char *rdata, unsigned int rdlen); 183170222Sdougb/*%< 184135446Strhodes * Add a single resource record to the lookup structure to be 185135446Strhodes * returned in the query response. dns_sdb_putrr() takes the 186135446Strhodes * resource record in master file text format as a null-terminated 187135446Strhodes * string, and dns_sdb_putrdata() takes the raw RDATA in 188135446Strhodes * uncompressed wire format. 189135446Strhodes */ 190135446Strhodes 191170222Sdougb/*% See dns_sdb_putnamerdata() */ 192135446Strhodesisc_result_t 193135446Strhodesdns_sdb_putnamedrr(dns_sdballnodes_t *allnodes, const char *name, 194135446Strhodes const char *type, dns_ttl_t ttl, const char *data); 195135446Strhodesisc_result_t 196135446Strhodesdns_sdb_putnamedrdata(dns_sdballnodes_t *allnodes, const char *name, 197135446Strhodes dns_rdatatype_t type, dns_ttl_t ttl, 198135446Strhodes const void *rdata, unsigned int rdlen); 199170222Sdougb/*%< 200135446Strhodes * Add a single resource record to the allnodes structure to be 201135446Strhodes * included in a zone transfer response, in text or wire 202135446Strhodes * format as above. 203135446Strhodes */ 204135446Strhodes 205135446Strhodesisc_result_t 206135446Strhodesdns_sdb_putsoa(dns_sdblookup_t *lookup, const char *mname, const char *rname, 207135446Strhodes isc_uint32_t serial); 208170222Sdougb/*%< 209135446Strhodes * This function may optionally be called from the 'authority' callback 210135446Strhodes * to simplify construction of the SOA record for 'zone'. It will 211135446Strhodes * provide a SOA listing 'mname' as as the master server and 'rname' as 212135446Strhodes * the responsible person mailbox. It is the responsibility of the 213135446Strhodes * driver to increment the serial number between responses if necessary. 214135446Strhodes * All other SOA fields will have reasonable default values. 215135446Strhodes */ 216135446Strhodes 217135446StrhodesISC_LANG_ENDDECLS 218135446Strhodes 219135446Strhodes#endif /* DNS_SDB_H */ 220