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