Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / dns / include / dns / sdlz.h
1 /*
2  * Portions Copyright (C) 2005-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
3  * Portions Copyright (C) 1999-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 /*
19  * Copyright (C) 2002 Stichting NLnet, Netherlands, stichting@nlnet.nl.
20  *
21  * Permission to use, copy, modify, and distribute this software for any
22  * purpose with or without fee is hereby granted, provided that the
23  * above copyright notice and this permission notice appear in all
24  * copies.
25  *
26  * THE SOFTWARE IS PROVIDED "AS IS" AND STICHTING NLNET
27  * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
28  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
29  * STICHTING NLNET BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
30  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
31  * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
32  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
33  * USE OR PERFORMANCE OF THIS SOFTWARE.
34  *
35  * The development of Dynamically Loadable Zones (DLZ) for Bind 9 was
36  * conceived and contributed by Rob Butler.
37  *
38  * Permission to use, copy, modify, and distribute this software for any
39  * purpose with or without fee is hereby granted, provided that the
40  * above copyright notice and this permission notice appear in all
41  * copies.
42  *
43  * THE SOFTWARE IS PROVIDED "AS IS" AND ROB BUTLER
44  * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
45  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
46  * ROB BUTLER BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
47  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
48  * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
49  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
50  * USE OR PERFORMANCE OF THIS SOFTWARE.
51  */
52
53 /* $Id: sdlz.h,v 1.7.128.2 2009/01/19 23:47:03 tbox Exp $ */
54
55 /*! \file dns/sdlz.h */
56
57 #ifndef SDLZ_H
58 #define SDLZ_H 1
59
60 #include <dns/dlz.h>
61
62 ISC_LANG_BEGINDECLS
63
64 #define DNS_SDLZFLAG_THREADSAFE         0x00000001U
65 #define DNS_SDLZFLAG_RELATIVEOWNER      0x00000002U
66 #define DNS_SDLZFLAG_RELATIVERDATA      0x00000004U
67
68  /* A simple DLZ database. */
69 typedef struct dns_sdlz_db dns_sdlz_db_t;
70
71  /* A simple DLZ database lookup in progress. */
72 typedef struct dns_sdlzlookup dns_sdlzlookup_t;
73
74  /* A simple DLZ database traversal in progress. */
75 typedef struct dns_sdlzallnodes dns_sdlzallnodes_t;
76
77
78 typedef isc_result_t
79 (*dns_sdlzallnodesfunc_t)(const char *zone, void *driverarg, void *dbdata,
80                           dns_sdlzallnodes_t *allnodes);
81
82 /*%<
83  * Method prototype.  Drivers implementing the SDLZ interface may
84  * supply an all nodes method.  This method is called when the DNS
85  * server is performing a zone transfer query, after the allow zone
86  * transfer method has been called.  This method is only called if the
87  * allow zone transfer method returned ISC_R_SUCCESS.  This method and
88  * the allow zone transfer method are both required for zone transfers
89  * to be supported.  If the driver generates data dynamically (instead
90  * of searching in a database for it) it should not implement this
91  * function as a zone transfer would be meaningless.  A SDLZ driver
92  * does not have to implement an all nodes method.
93  */
94
95 typedef isc_result_t
96 (*dns_sdlzallowzonexfr_t)(void *driverarg, void *dbdata, const char *name,
97                           const char *client);
98
99 /*%<
100  * Method prototype.  Drivers implementing the SDLZ interface may
101  * supply an allow zone transfer method.  This method is called when
102  * the DNS server is performing a zone transfer query, before the all
103  * nodes method can be called.  This method and the all node method
104  * are both required for zone transfers to be supported.  If the
105  * driver generates data dynamically (instead of searching in a
106  * database for it) it should not implement this function as a zone
107  * transfer would be meaningless.  A SDLZ driver does not have to
108  * implement an allow zone transfer method.
109  *
110  * This method should return ISC_R_SUCCESS if the zone is supported by
111  * the database and a zone transfer is allowed for the specified
112  * client.  If the zone is supported by the database, but zone
113  * transfers are not allowed for the specified client this method
114  * should return ISC_R_NOPERM..  Lastly the method should return
115  * ISC_R_NOTFOUND if the zone is not supported by the database.  If an
116  * error occurs it should return a result code indicating the type of
117  * error.
118  */
119
120 typedef isc_result_t
121 (*dns_sdlzauthorityfunc_t)(const char *zone, void *driverarg, void *dbdata,
122                            dns_sdlzlookup_t *lookup);
123
124 /*%<
125  * Method prototype.  Drivers implementing the SDLZ interface may
126  * supply an authority method.  This method is called when the DNS
127  * server is performing a query, after both the find zone and lookup
128  * methods have been called.  This method is required if the lookup
129  * function does not supply authority information for the dns
130  * record. A SDLZ driver does not have to implement an authority
131  * method.
132  */
133
134 typedef isc_result_t
135 (*dns_sdlzcreate_t)(const char *dlzname, unsigned int argc, char *argv[],
136                     void *driverarg, void **dbdata);
137
138 /*%<
139  * Method prototype.  Drivers implementing the SDLZ interface may
140  * supply a create method.  This method is called when the DNS server
141  * is starting up and creating drivers for use later. A SDLZ driver
142  * does not have to implement a create method.
143  */
144
145 typedef void
146 (*dns_sdlzdestroy_t)(void *driverarg, void *dbdata);
147
148 /*%<
149  * Method prototype.  Drivers implementing the SDLZ interface may
150  * supply a destroy method.  This method is called when the DNS server
151  * is shutting down and no longer needs the driver.  A SDLZ driver does
152  * not have to implement a destroy method.
153  */
154
155 typedef isc_result_t
156 (*dns_sdlzfindzone_t)(void *driverarg, void *dbdata, const char *name);
157
158 /*%<
159  * Method prototype.  Drivers implementing the SDLZ interface MUST
160  * supply a find zone method.  This method is called when the DNS
161  * server is performing a query to to determine if 'name' is a
162  * supported dns zone.  The find zone method will be called with the
163  * longest possible name first, and continue to be called with
164  * successively shorter domain names, until any of the following
165  * occur:
166  *
167  * \li  1) the function returns (ISC_R_SUCCESS) indicating a zone name
168  *         match.
169  *
170  * \li  2) a problem occurs, and the functions returns anything other than
171  *         (ISC_R_NOTFOUND)
172  *
173  * \li  3) we run out of domain name labels. I.E. we have tried the
174  *         shortest domain name
175  *
176  * \li  4) the number of labels in the domain name is less than min_labels
177  *         for dns_dlzfindzone
178  *
179  * The driver's find zone method should return ISC_R_SUCCESS if the
180  * zone is supported by the database.  Otherwise it should return
181  * ISC_R_NOTFOUND, if the zone is not supported.  If an error occurs
182  * it should return a result code indicating the type of error.
183  */
184
185 typedef isc_result_t
186 (*dns_sdlzlookupfunc_t)(const char *zone, const char *name, void *driverarg,
187                         void *dbdata, dns_sdlzlookup_t *lookup);
188
189 /*%<
190  * Method prototype.  Drivers implementing the SDLZ interface MUST
191  * supply a lookup method.  This method is called when the DNS server
192  * is performing a query, after the find zone and before any other
193  * methods have been called.  This function returns record DNS record
194  * information using the dns_sdlz_putrr and dns_sdlz_putsoa functions.
195  * If this function supplies authority information for the DNS record
196  * the authority method is not required.  If it does not, the
197  * authority function is required.  A SDLZ driver must implement a
198  * lookup method.
199  */
200
201 typedef struct dns_sdlzmethods {
202         dns_sdlzcreate_t        create;
203         dns_sdlzdestroy_t       destroy;
204         dns_sdlzfindzone_t      findzone;
205         dns_sdlzlookupfunc_t    lookup;
206         dns_sdlzauthorityfunc_t authority;
207         dns_sdlzallnodesfunc_t  allnodes;
208         dns_sdlzallowzonexfr_t  allowzonexfr;
209 } dns_sdlzmethods_t;
210
211 isc_result_t
212 dns_sdlzregister(const char *drivername, const dns_sdlzmethods_t *methods,
213                  void *driverarg, unsigned int flags, isc_mem_t *mctx,
214                  dns_sdlzimplementation_t **sdlzimp);
215 /*%<
216  * Register a dynamically loadable zones (dlz) driver for the database
217  * type 'drivername', implemented by the functions in '*methods'.
218  *
219  * sdlzimp must point to a NULL dns_sdlzimplementation_t pointer.
220  * That is, sdlzimp != NULL && *sdlzimp == NULL.  It will be assigned
221  * a value that will later be used to identify the driver when
222  * deregistering it.
223  */
224
225 void
226 dns_sdlzunregister(dns_sdlzimplementation_t **sdlzimp);
227
228 /*%<
229  * Removes the sdlz driver from the list of registered sdlz drivers.
230  * There must be no active sdlz drivers of this type when this
231  * function is called.
232  */
233
234 isc_result_t
235 dns_sdlz_putnamedrr(dns_sdlzallnodes_t *allnodes, const char *name,
236                    const char *type, dns_ttl_t ttl, const char *data);
237 /*%<
238  * Add a single resource record to the allnodes structure to be later
239  * parsed into a zone transfer response.
240  */
241
242 isc_result_t
243 dns_sdlz_putrr(dns_sdlzlookup_t *lookup, const char *type, dns_ttl_t ttl,
244               const char *data);
245 /*%<
246  * Add a single resource record to the lookup structure to be later
247  * parsed into a query response.
248  */
249
250 isc_result_t
251 dns_sdlz_putsoa(dns_sdlzlookup_t *lookup, const char *mname, const char *rname,
252                isc_uint32_t serial);
253 /*%<
254  * This function may optionally be called from the 'authority'
255  * callback to simplify construction of the SOA record for 'zone'.  It
256  * will provide a SOA listing 'mname' as as the master server and
257  * 'rname' as the responsible person mailbox.  It is the
258  * responsibility of the driver to increment the serial number between
259  * responses if necessary.  All other SOA fields will have reasonable
260  * default values.
261  */
262
263
264 ISC_LANG_ENDDECLS
265
266 #endif /* SDLZ_H */