2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2001 Internet Software Consortium.
5 * Permission to use, copy, modify, and 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.
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.
18 /* $Id: resolver.h,v 1.34.2.1 2004/03/09 06:11:21 marka Exp $ */
20 #ifndef DNS_RESOLVER_H
21 #define DNS_RESOLVER_H 1
30 * This is the BIND 9 resolver, the module responsible for resolving DNS
31 * requests by iteratively querying authoritative servers and following
32 * referrals. This is a "full resolver", not to be confused with
33 * the stub resolvers most people associate with the word "resolver".
34 * The full resolver is part of the caching name server or resolver
35 * daemon the stub resolver talks to.
38 * The module ensures appropriate synchronization of data structures it
39 * creates and manipulates.
42 * No anticipated impact.
48 * No anticipated impact.
51 * RFCs: 1034, 1035, 2181, <TBS>
56 #include <isc/socket.h>
58 #include <dns/types.h>
59 #include <dns/fixedname.h>
64 * A dns_fetchevent_t is sent when a 'fetch' completes. Any of 'db',
65 * 'node', 'rdataset', and 'sigrdataset' may be bound. It is the
66 * receiver's responsibility to detach before freeing the event.
68 * 'rdataset' and 'sigrdataset' are the values that were supplied when
69 * dns_resolver_createfetch() was called. They are returned to the
70 * caller so that they may be freed.
72 typedef struct dns_fetchevent {
73 ISC_EVENT_COMMON(struct dns_fetchevent);
76 dns_rdatatype_t qtype;
79 dns_rdataset_t * rdataset;
80 dns_rdataset_t * sigrdataset;
81 dns_fixedname_t foundname;
85 * Options that modify how a 'fetch' is done.
87 #define DNS_FETCHOPT_TCP 0x01 /* Use TCP. */
88 #define DNS_FETCHOPT_UNSHARED 0x02 /* See below. */
89 #define DNS_FETCHOPT_RECURSIVE 0x04 /* Set RD? */
90 #define DNS_FETCHOPT_NOEDNS0 0x08 /* Do not use EDNS. */
91 #define DNS_FETCHOPT_FORWARDONLY 0x10 /* Only use forwarders. */
92 #define DNS_FETCHOPT_NOVALIDATE 0x20 /* Disable validation. */
95 * XXXRTH Should this API be made semi-private? (I.e.
96 * _dns_resolver_create()).
100 dns_resolver_create(dns_view_t *view,
101 isc_taskmgr_t *taskmgr, unsigned int ntasks,
102 isc_socketmgr_t *socketmgr,
103 isc_timermgr_t *timermgr,
104 unsigned int options,
105 dns_dispatchmgr_t *dispatchmgr,
106 dns_dispatch_t *dispatchv4,
107 dns_dispatch_t *dispatchv6,
108 dns_resolver_t **resp);
114 * Generally, applications should not create a resolver directly, but
115 * should instead call dns_view_createresolver().
117 * No options are currently defined.
121 * 'view' is a valid view.
123 * 'taskmgr' is a valid task manager.
127 * 'socketmgr' is a valid socket manager.
129 * 'timermgr' is a valid timer manager.
131 * 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
133 * 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
135 * *resp != NULL && *resp == NULL.
139 * ISC_R_SUCCESS On success.
141 * Anything else Failure.
145 dns_resolver_freeze(dns_resolver_t *res);
151 * Certain configuration changes cannot be made after the resolver
152 * is frozen. Fetches cannot be created until the resolver is frozen.
156 * 'res' is a valid, unfrozen resolver.
164 dns_resolver_prime(dns_resolver_t *res);
170 * Resolvers which have a forwarding policy other than dns_fwdpolicy_only
171 * need to be primed with the root nameservers, otherwise the root
172 * nameserver hints data may be used indefinitely. This function requests
173 * that the resolver start a priming fetch, if it isn't already priming.
177 * 'res' is a valid, frozen resolver.
182 dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task,
183 isc_event_t **eventp);
185 * Send '*eventp' to 'task' when 'res' has completed shutdown.
189 * It is not safe to detach the last reference to 'res' until
190 * shutdown is complete.
194 * 'res' is a valid resolver.
196 * 'task' is a valid task.
198 * *eventp is a valid event.
206 dns_resolver_shutdown(dns_resolver_t *res);
208 * Start the shutdown process for 'res'.
212 * This call has no effect if the resolver is already shutting down.
216 * 'res' is a valid resolver.
220 dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);
223 dns_resolver_detach(dns_resolver_t **resp);
226 dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name,
227 dns_rdatatype_t type,
228 dns_name_t *domain, dns_rdataset_t *nameservers,
229 dns_forwarders_t *forwarders,
230 unsigned int options, isc_task_t *task,
231 isc_taskaction_t action, void *arg,
232 dns_rdataset_t *rdataset,
233 dns_rdataset_t *sigrdataset,
234 dns_fetch_t **fetchp);
236 * Recurse to answer a question.
240 * This call starts a query for 'name', type 'type'.
242 * The 'domain' is a parent domain of 'name' for which
243 * a set of name servers 'nameservers' is known. If no
244 * such name server information is available, set
245 * 'domain' and 'nameservers' to NULL.
247 * 'forwarders' is unimplemented, and subject to change when
248 * we figure out how selective forwarding will work.
250 * When the fetch completes (successfully or otherwise), a
251 * DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be
254 * The values of 'rdataset' and 'sigrdataset' will be returned in
255 * the FETCHDONE event.
259 * 'res' is a valid resolver that has been frozen.
261 * 'name' is a valid name.
263 * 'type' is not a meta type other than ANY.
265 * 'domain' is a valid name or NULL.
267 * 'nameservers' is a valid NS rdataset (whose owner name is 'domain')
268 * iff. 'domain' is not NULL.
270 * 'forwarders' is NULL.
272 * 'options' contains valid options.
274 * 'rdataset' is a valid, disassociated rdataset.
276 * 'sigrdataset' is NULL, or is a valid, disassociated rdataset.
278 * fetchp != NULL && *fetchp == NULL.
282 * ISC_R_SUCCESS Success
284 * Many other values are possible, all of which indicate failure.
288 dns_resolver_cancelfetch(dns_fetch_t *fetch);
294 * If 'fetch' has not completed, post its FETCHDONE event with a
295 * result code of ISC_R_CANCELED.
299 * 'fetch' is a valid fetch.
303 dns_resolver_destroyfetch(dns_fetch_t **fetchp);
309 * '*fetchp' is a valid fetch.
311 * The caller has received the FETCHDONE event (either because the
312 * fetch completed or because dns_resolver_cancelfetch() was called).
320 dns_resolver_dispatchmgr(dns_resolver_t *resolver);
323 dns_resolver_dispatchv4(dns_resolver_t *resolver);
326 dns_resolver_dispatchv6(dns_resolver_t *resolver);
329 dns_resolver_socketmgr(dns_resolver_t *resolver);
332 dns_resolver_taskmgr(dns_resolver_t *resolver);
335 dns_resolver_getlamettl(dns_resolver_t *resolver);
337 * Get the resolver's lame-ttl. zero => no lame processing.
340 * 'resolver' to be valid.
344 dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl);
346 * Set the resolver's lame-ttl. zero => no lame processing.
349 * 'resolver' to be valid.
354 #endif /* DNS_RESOLVER_H */