Annotation of embedaddon/libevent/evdns.h, revision 1.1.1.1
1.1 misho 1: /*
2: * Copyright (c) 2006 Niels Provos <provos@citi.umich.edu>
3: * All rights reserved.
4: *
5: * Redistribution and use in source and binary forms, with or without
6: * modification, are permitted provided that the following conditions
7: * are met:
8: * 1. Redistributions of source code must retain the above copyright
9: * notice, this list of conditions and the following disclaimer.
10: * 2. Redistributions in binary form must reproduce the above copyright
11: * notice, this list of conditions and the following disclaimer in the
12: * documentation and/or other materials provided with the distribution.
13: * 3. The name of the author may not be used to endorse or promote products
14: * derived from this software without specific prior written permission.
15: *
16: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19: * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25: * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26: */
27:
28: /*
29: * The original DNS code is due to Adam Langley with heavy
30: * modifications by Nick Mathewson. Adam put his DNS software in the
31: * public domain. You can find his original copyright below. Please,
32: * aware that the code as part of libevent is governed by the 3-clause
33: * BSD license above.
34: *
35: * This software is Public Domain. To view a copy of the public domain dedication,
36: * visit http://creativecommons.org/licenses/publicdomain/ or send a letter to
37: * Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
38: *
39: * I ask and expect, but do not require, that all derivative works contain an
40: * attribution similar to:
41: * Parts developed by Adam Langley <agl@imperialviolet.org>
42: *
43: * You may wish to replace the word "Parts" with something else depending on
44: * the amount of original code.
45: *
46: * (Derivative works does not include programs which link against, run or include
47: * the source verbatim in their source distributions)
48: */
49:
50: /** @file evdns.h
51: *
52: * Welcome, gentle reader
53: *
54: * Async DNS lookups are really a whole lot harder than they should be,
55: * mostly stemming from the fact that the libc resolver has never been
56: * very good at them. Before you use this library you should see if libc
57: * can do the job for you with the modern async call getaddrinfo_a
58: * (see http://www.imperialviolet.org/page25.html#e498). Otherwise,
59: * please continue.
60: *
61: * This code is based on libevent and you must call event_init before
62: * any of the APIs in this file. You must also seed the OpenSSL random
63: * source if you are using OpenSSL for ids (see below).
64: *
65: * This library is designed to be included and shipped with your source
66: * code. You statically link with it. You should also test for the
67: * existence of strtok_r and define HAVE_STRTOK_R if you have it.
68: *
69: * The DNS protocol requires a good source of id numbers and these
70: * numbers should be unpredictable for spoofing reasons. There are
71: * three methods for generating them here and you must define exactly
72: * one of them. In increasing order of preference:
73: *
74: * DNS_USE_GETTIMEOFDAY_FOR_ID:
75: * Using the bottom 16 bits of the usec result from gettimeofday. This
76: * is a pretty poor solution but should work anywhere.
77: * DNS_USE_CPU_CLOCK_FOR_ID:
78: * Using the bottom 16 bits of the nsec result from the CPU's time
79: * counter. This is better, but may not work everywhere. Requires
80: * POSIX realtime support and you'll need to link against -lrt on
81: * glibc systems at least.
82: * DNS_USE_OPENSSL_FOR_ID:
83: * Uses the OpenSSL RAND_bytes call to generate the data. You must
84: * have seeded the pool before making any calls to this library.
85: *
86: * The library keeps track of the state of nameservers and will avoid
87: * them when they go down. Otherwise it will round robin between them.
88: *
89: * Quick start guide:
90: * #include "evdns.h"
91: * void callback(int result, char type, int count, int ttl,
92: * void *addresses, void *arg);
93: * evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
94: * evdns_resolve("www.hostname.com", 0, callback, NULL);
95: *
96: * When the lookup is complete the callback function is called. The
97: * first argument will be one of the DNS_ERR_* defines in evdns.h.
98: * Hopefully it will be DNS_ERR_NONE, in which case type will be
99: * DNS_IPv4_A, count will be the number of IP addresses, ttl is the time
100: * which the data can be cached for (in seconds), addresses will point
101: * to an array of uint32_t's and arg will be whatever you passed to
102: * evdns_resolve.
103: *
104: * Searching:
105: *
106: * In order for this library to be a good replacement for glibc's resolver it
107: * supports searching. This involves setting a list of default domains, in
108: * which names will be queried for. The number of dots in the query name
109: * determines the order in which this list is used.
110: *
111: * Searching appears to be a single lookup from the point of view of the API,
112: * although many DNS queries may be generated from a single call to
113: * evdns_resolve. Searching can also drastically slow down the resolution
114: * of names.
115: *
116: * To disable searching:
117: * 1. Never set it up. If you never call evdns_resolv_conf_parse or
118: * evdns_search_add then no searching will occur.
119: *
120: * 2. If you do call evdns_resolv_conf_parse then don't pass
121: * DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it).
122: *
123: * 3. When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag.
124: *
125: * The order of searches depends on the number of dots in the name. If the
126: * number is greater than the ndots setting then the names is first tried
127: * globally. Otherwise each search domain is appended in turn.
128: *
129: * The ndots setting can either be set from a resolv.conf, or by calling
130: * evdns_search_ndots_set.
131: *
132: * For example, with ndots set to 1 (the default) and a search domain list of
133: * ["myhome.net"]:
134: * Query: www
135: * Order: www.myhome.net, www.
136: *
137: * Query: www.abc
138: * Order: www.abc., www.abc.myhome.net
139: *
140: * Internals:
141: *
142: * Requests are kept in two queues. The first is the inflight queue. In
143: * this queue requests have an allocated transaction id and nameserver.
144: * They will soon be transmitted if they haven't already been.
145: *
146: * The second is the waiting queue. The size of the inflight ring is
147: * limited and all other requests wait in waiting queue for space. This
148: * bounds the number of concurrent requests so that we don't flood the
149: * nameserver. Several algorithms require a full walk of the inflight
150: * queue and so bounding its size keeps thing going nicely under huge
151: * (many thousands of requests) loads.
152: *
153: * If a nameserver loses too many requests it is considered down and we
154: * try not to use it. After a while we send a probe to that nameserver
155: * (a lookup for google.com) and, if it replies, we consider it working
156: * again. If the nameserver fails a probe we wait longer to try again
157: * with the next probe.
158: */
159:
160: #ifndef EVENTDNS_H
161: #define EVENTDNS_H
162:
163: #ifdef __cplusplus
164: extern "C" {
165: #endif
166:
167: /* For integer types. */
168: #include <evutil.h>
169:
170: /** Error codes 0-5 are as described in RFC 1035. */
171: #define DNS_ERR_NONE 0
172: /** The name server was unable to interpret the query */
173: #define DNS_ERR_FORMAT 1
174: /** The name server was unable to process this query due to a problem with the
175: * name server */
176: #define DNS_ERR_SERVERFAILED 2
177: /** The domain name does not exist */
178: #define DNS_ERR_NOTEXIST 3
179: /** The name server does not support the requested kind of query */
180: #define DNS_ERR_NOTIMPL 4
181: /** The name server refuses to reform the specified operation for policy
182: * reasons */
183: #define DNS_ERR_REFUSED 5
184: /** The reply was truncated or ill-formated */
185: #define DNS_ERR_TRUNCATED 65
186: /** An unknown error occurred */
187: #define DNS_ERR_UNKNOWN 66
188: /** Communication with the server timed out */
189: #define DNS_ERR_TIMEOUT 67
190: /** The request was canceled because the DNS subsystem was shut down. */
191: #define DNS_ERR_SHUTDOWN 68
192:
193: #define DNS_IPv4_A 1
194: #define DNS_PTR 2
195: #define DNS_IPv6_AAAA 3
196:
197: #define DNS_QUERY_NO_SEARCH 1
198:
199: #define DNS_OPTION_SEARCH 1
200: #define DNS_OPTION_NAMESERVERS 2
201: #define DNS_OPTION_MISC 4
202: #define DNS_OPTIONS_ALL 7
203:
204: /**
205: * The callback that contains the results from a lookup.
206: * - type is either DNS_IPv4_A or DNS_PTR or DNS_IPv6_AAAA
207: * - count contains the number of addresses of form type
208: * - ttl is the number of seconds the resolution may be cached for.
209: * - addresses needs to be cast according to type
210: */
211: typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);
212:
213: /**
214: Initialize the asynchronous DNS library.
215:
216: This function initializes support for non-blocking name resolution by
217: calling evdns_resolv_conf_parse() on UNIX and
218: evdns_config_windows_nameservers() on Windows.
219:
220: @return 0 if successful, or -1 if an error occurred
221: @see evdns_shutdown()
222: */
223: int evdns_init(void);
224:
225:
226: /**
227: Shut down the asynchronous DNS resolver and terminate all active requests.
228:
229: If the 'fail_requests' option is enabled, all active requests will return
230: an empty result with the error flag set to DNS_ERR_SHUTDOWN. Otherwise,
231: the requests will be silently discarded.
232:
233: @param fail_requests if zero, active requests will be aborted; if non-zero,
234: active requests will return DNS_ERR_SHUTDOWN.
235: @see evdns_init()
236: */
237: void evdns_shutdown(int fail_requests);
238:
239:
240: /**
241: Convert a DNS error code to a string.
242:
243: @param err the DNS error code
244: @return a string containing an explanation of the error code
245: */
246: const char *evdns_err_to_string(int err);
247:
248:
249: /**
250: Add a nameserver.
251:
252: The address should be an IPv4 address in network byte order.
253: The type of address is chosen so that it matches in_addr.s_addr.
254:
255: @param address an IP address in network byte order
256: @return 0 if successful, or -1 if an error occurred
257: @see evdns_nameserver_ip_add()
258: */
259: int evdns_nameserver_add(unsigned long int address);
260:
261:
262: /**
263: Get the number of configured nameservers.
264:
265: This returns the number of configured nameservers (not necessarily the
266: number of running nameservers). This is useful for double-checking
267: whether our calls to the various nameserver configuration functions
268: have been successful.
269:
270: @return the number of configured nameservers
271: @see evdns_nameserver_add()
272: */
273: int evdns_count_nameservers(void);
274:
275:
276: /**
277: Remove all configured nameservers, and suspend all pending resolves.
278:
279: Resolves will not necessarily be re-attempted until evdns_resume() is called.
280:
281: @return 0 if successful, or -1 if an error occurred
282: @see evdns_resume()
283: */
284: int evdns_clear_nameservers_and_suspend(void);
285:
286:
287: /**
288: Resume normal operation and continue any suspended resolve requests.
289:
290: Re-attempt resolves left in limbo after an earlier call to
291: evdns_clear_nameservers_and_suspend().
292:
293: @return 0 if successful, or -1 if an error occurred
294: @see evdns_clear_nameservers_and_suspend()
295: */
296: int evdns_resume(void);
297:
298:
299: /**
300: Add a nameserver.
301:
302: This wraps the evdns_nameserver_add() function by parsing a string as an IP
303: address and adds it as a nameserver.
304:
305: @return 0 if successful, or -1 if an error occurred
306: @see evdns_nameserver_add()
307: */
308: int evdns_nameserver_ip_add(const char *ip_as_string);
309:
310:
311: /**
312: Lookup an A record for a given name.
313:
314: @param name a DNS hostname
315: @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
316: @param callback a callback function to invoke when the request is completed
317: @param ptr an argument to pass to the callback function
318: @return 0 if successful, or -1 if an error occurred
319: @see evdns_resolve_ipv6(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6()
320: */
321: int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr);
322:
323:
324: /**
325: Lookup an AAAA record for a given name.
326:
327: @param name a DNS hostname
328: @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
329: @param callback a callback function to invoke when the request is completed
330: @param ptr an argument to pass to the callback function
331: @return 0 if successful, or -1 if an error occurred
332: @see evdns_resolve_ipv4(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6()
333: */
334: int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
335:
336: struct in_addr;
337: struct in6_addr;
338:
339: /**
340: Lookup a PTR record for a given IP address.
341:
342: @param in an IPv4 address
343: @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
344: @param callback a callback function to invoke when the request is completed
345: @param ptr an argument to pass to the callback function
346: @return 0 if successful, or -1 if an error occurred
347: @see evdns_resolve_reverse_ipv6()
348: */
349: int evdns_resolve_reverse(const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
350:
351:
352: /**
353: Lookup a PTR record for a given IPv6 address.
354:
355: @param in an IPv6 address
356: @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
357: @param callback a callback function to invoke when the request is completed
358: @param ptr an argument to pass to the callback function
359: @return 0 if successful, or -1 if an error occurred
360: @see evdns_resolve_reverse_ipv6()
361: */
362: int evdns_resolve_reverse_ipv6(const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
363:
364:
365: /**
366: Set the value of a configuration option.
367:
368: The currently available configuration options are:
369:
370: ndots, timeout, max-timeouts, max-inflight, and attempts
371:
372: @param option the name of the configuration option to be modified
373: @param val the value to be set
374: @param flags either 0 | DNS_OPTION_SEARCH | DNS_OPTION_MISC
375: @return 0 if successful, or -1 if an error occurred
376: */
377: int evdns_set_option(const char *option, const char *val, int flags);
378:
379:
380: /**
381: Parse a resolv.conf file.
382:
383: The 'flags' parameter determines what information is parsed from the
384: resolv.conf file. See the man page for resolv.conf for the format of this
385: file.
386:
387: The following directives are not parsed from the file: sortlist, rotate,
388: no-check-names, inet6, debug.
389:
390: If this function encounters an error, the possible return values are: 1 =
391: failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of
392: memory, 5 = short read from file, 6 = no nameservers listed in the file
393:
394: @param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC|
395: DNS_OPTIONS_ALL
396: @param filename the path to the resolv.conf file
397: @return 0 if successful, or various positive error codes if an error
398: occurred (see above)
399: @see resolv.conf(3), evdns_config_windows_nameservers()
400: */
401: int evdns_resolv_conf_parse(int flags, const char *const filename);
402:
403:
404: /**
405: Obtain nameserver information using the Windows API.
406:
407: Attempt to configure a set of nameservers based on platform settings on
408: a win32 host. Preferentially tries to use GetNetworkParams; if that fails,
409: looks in the registry.
410:
411: @return 0 if successful, or -1 if an error occurred
412: @see evdns_resolv_conf_parse()
413: */
414: #ifdef WIN32
415: int evdns_config_windows_nameservers(void);
416: #endif
417:
418:
419: /**
420: Clear the list of search domains.
421: */
422: void evdns_search_clear(void);
423:
424:
425: /**
426: Add a domain to the list of search domains
427:
428: @param domain the domain to be added to the search list
429: */
430: void evdns_search_add(const char *domain);
431:
432:
433: /**
434: Set the 'ndots' parameter for searches.
435:
436: Sets the number of dots which, when found in a name, causes
437: the first query to be without any search domain.
438:
439: @param ndots the new ndots parameter
440: */
441: void evdns_search_ndots_set(const int ndots);
442:
443: /**
444: A callback that is invoked when a log message is generated
445:
446: @param is_warning indicates if the log message is a 'warning'
447: @param msg the content of the log message
448: */
449: typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
450:
451:
452: /**
453: Set the callback function to handle log messages.
454:
455: @param fn the callback to be invoked when a log message is generated
456: */
457: void evdns_set_log_fn(evdns_debug_log_fn_type fn);
458:
459: /**
460: Set a callback that will be invoked to generate transaction IDs. By
461: default, we pick transaction IDs based on the current clock time.
462:
463: @param fn the new callback, or NULL to use the default.
464: */
465: void evdns_set_transaction_id_fn(ev_uint16_t (*fn)(void));
466:
467: #define DNS_NO_SEARCH 1
468:
469: /*
470: * Structures and functions used to implement a DNS server.
471: */
472:
473: struct evdns_server_request {
474: int flags;
475: int nquestions;
476: struct evdns_server_question **questions;
477: };
478: struct evdns_server_question {
479: int type;
480: #ifdef __cplusplus
481: int dns_question_class;
482: #else
483: /* You should refer to this field as "dns_question_class". The
484: * name "class" works in C for backward compatibility, and will be
485: * removed in a future version. (1.5 or later). */
486: int class;
487: #define dns_question_class class
488: #endif
489: char name[1];
490: };
491: typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void *);
492: #define EVDNS_ANSWER_SECTION 0
493: #define EVDNS_AUTHORITY_SECTION 1
494: #define EVDNS_ADDITIONAL_SECTION 2
495:
496: #define EVDNS_TYPE_A 1
497: #define EVDNS_TYPE_NS 2
498: #define EVDNS_TYPE_CNAME 5
499: #define EVDNS_TYPE_SOA 6
500: #define EVDNS_TYPE_PTR 12
501: #define EVDNS_TYPE_MX 15
502: #define EVDNS_TYPE_TXT 16
503: #define EVDNS_TYPE_AAAA 28
504:
505: #define EVDNS_QTYPE_AXFR 252
506: #define EVDNS_QTYPE_ALL 255
507:
508: #define EVDNS_CLASS_INET 1
509:
510: struct evdns_server_port *evdns_add_server_port(int socket, int is_tcp, evdns_request_callback_fn_type callback, void *user_data);
511: void evdns_close_server_port(struct evdns_server_port *port);
512:
513: int evdns_server_request_add_reply(struct evdns_server_request *req, int section, const char *name, int type, int dns_class, int ttl, int datalen, int is_name, const char *data);
514: int evdns_server_request_add_a_reply(struct evdns_server_request *req, const char *name, int n, void *addrs, int ttl);
515: int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req, const char *name, int n, void *addrs, int ttl);
516: int evdns_server_request_add_ptr_reply(struct evdns_server_request *req, struct in_addr *in, const char *inaddr_name, const char *hostname, int ttl);
517: int evdns_server_request_add_cname_reply(struct evdns_server_request *req, const char *name, const char *cname, int ttl);
518:
519: int evdns_server_request_respond(struct evdns_server_request *req, int err);
520: int evdns_server_request_drop(struct evdns_server_request *req);
521: struct sockaddr;
522: int evdns_server_request_get_requesting_addr(struct evdns_server_request *_req, struct sockaddr *sa, int addr_len);
523:
524: #ifdef __cplusplus
525: }
526: #endif
527:
528: #endif /* !EVENTDNS_H */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to evdns.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libevent