libev/evdns.h

/*
 * Copyright (c) 2006 Niels Provos <provos@citi.umich.edu>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*
 * The original DNS code is due to Adam Langley with heavy
 * modifications by Nick Mathewson.  Adam put his DNS software in the
 * public domain.  You can find his original copyright below.  Please,
 * aware that the code as part of libevent is governed by the 3-clause
 * BSD license above.
 *
 * This software is Public Domain. To view a copy of the public domain dedication,
 * visit http://creativecommons.org/licenses/publicdomain/ or send a letter to
 * Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
 *
 * I ask and expect, but do not require, that all derivative works contain an
 * attribution similar to:
 *      Parts developed by Adam Langley <agl@imperialviolet.org>
 *
 * You may wish to replace the word "Parts" with something else depending on
 * the amount of original code.
 *
 * (Derivative works does not include programs which link against, run or include
 * the source verbatim in their source distributions)
 */

/*
 * Welcome, gentle reader
 *
 * Async DNS lookups are really a whole lot harder than they should be,
 * mostly stemming from the fact that the libc resolver has never been
 * very good at them. Before you use this library you should see if libc
 * can do the job for you with the modern async call getaddrinfo_a
 * (see http://www.imperialviolet.org/page25.html#e498). Otherwise,
 * please continue.
 *
 * This code is based on libevent and you must call event_init before
 * any of the APIs in this file. You must also seed the OpenSSL random
 * source if you are using OpenSSL for ids (see below).
 *
 * This library is designed to be included and shipped with your source
 * code. You statically link with it. You should also test for the
 * existence of strtok_r and define HAVE_STRTOK_R if you have it.
 *
 * The DNS protocol requires a good source of id numbers and these
 * numbers should be unpredictable for spoofing reasons. There are
 * three methods for generating them here and you must define exactly
 * one of them. In increasing order of preference:
 *
 * DNS_USE_GETTIMEOFDAY_FOR_ID:
 *   Using the bottom 16 bits of the usec result from gettimeofday. This
 *   is a pretty poor solution but should work anywhere.
 * DNS_USE_CPU_CLOCK_FOR_ID:
 *   Using the bottom 16 bits of the nsec result from the CPU's time
 *   counter. This is better, but may not work everywhere. Requires
 *   POSIX realtime support and you'll need to link against -lrt on
 *   glibc systems at least.
 * DNS_USE_OPENSSL_FOR_ID:
 *   Uses the OpenSSL RAND_bytes call to generate the data. You must
 *   have seeded the pool before making any calls to this library.
 *
 * The library keeps track of the state of nameservers and will avoid
 * them when they go down. Otherwise it will round robin between them.
 *
 * Quick start guide:
 *   #include "evdns.h"
 *   void callback(int result, char type, int count, int ttl,
 *               void *addresses, void *arg);
 *   evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
 *   evdns_resolve("www.hostname.com", 0, callback, NULL);
 *
 * When the lookup is complete the callback function is called. The
 * first argument will be one of the DNS_ERR_* defines in evdns.h.
 * Hopefully it will be DNS_ERR_NONE, in which case type will be
 * DNS_IPv4_A, count will be the number of IP addresses, ttl is the time
 * which the data can be cached for (in seconds), addresses will point
 * to an array of uint32_t's and arg will be whatever you passed to
 * evdns_resolve.
 *
 * Searching:
 *
 * In order for this library to be a good replacement for glibc's resolver it
 * supports searching. This involves setting a list of default domains, in
 * which names will be queried for. The number of dots in the query name
 * determines the order in which this list is used.
 *
 * Searching appears to be a single lookup from the point of view of the API,
 * although many DNS queries may be generated from a single call to
 * evdns_resolve. Searching can also drastically slow down the resolution
 * of names.
 *
 * To disable searching:
 *   1. Never set it up. If you never call evdns_resolv_conf_parse or
 *   evdns_search_add then no searching will occur.
 *
 *   2. If you do call evdns_resolv_conf_parse then don't pass
 *   DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it).
 *
 *   3. When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag.
 *
 * The order of searches depends on the number of dots in the name. If the
 * number is greater than the ndots setting then the names is first tried
 * globally. Otherwise each search domain is appended in turn.
 *
 * The ndots setting can either be set from a resolv.conf, or by calling
 * evdns_search_ndots_set.
 *
 * For example, with ndots set to 1 (the default) and a search domain list of
 * ["myhome.net"]:
 *  Query: www
 *  Order: www.myhome.net, www.
 *
 *  Query: www.abc
 *  Order: www.abc., www.abc.myhome.net
 *
 * API reference:
 *
 * int evdns_nameserver_add(unsigned long int address)
 *   Add a nameserver. The address should be an IP address in
 *   network byte order. The type of address is chosen so that
 *   it matches in_addr.s_addr.
 *   Returns non-zero on error.
 *
 * int evdns_nameserver_ip_add(const char *ip_as_string)
 *   This wraps the above function by parsing a string as an IP
 *   address and adds it as a nameserver.
 *   Returns non-zero on error
 *
 * int evdns_resolve(const char *name, int flags,
 *                    evdns_callback_type callback,
 *                    void *ptr)
 *   Resolve a name. The name parameter should be a DNS name.
 *   The flags parameter should be 0, or DNS_QUERY_NO_SEARCH
 *   which disables searching for this query. (see defn of
 *   searching above).
 *
 *   The callback argument is a function which is called when
 *   this query completes and ptr is an argument which is passed
 *   to that callback function.
 *
 *   Returns non-zero on error
 *
 * void evdns_search_clear()
 *   Clears the list of search domains
 *
 * void evdns_search_add(const char *domain)
 *   Add a domain to the list of search domains
 *
 * void evdns_search_ndots_set(int ndots)
 *   Set the number of dots which, when found in a name, causes
 *   the first query to be without any search domain.
 *
 * int evdns_count_nameservers(void)
 *   Return the number of configured nameservers (not necessarily the
 *   number of running nameservers).  This is useful for double-checking
 *   whether our calls to the various nameserver configuration functions
 *   have been successful.
 *
 * int evdns_clear_nameservers_and_suspend(void)
 *   Remove all currently configured nameservers, and suspend all pending
 *   resolves.  Resolves will not necessarily be re-attempted until
 *   evdns_resume() is called.
 *
 * int evdns_resume(void)
 *   Re-attempt resolves left in limbo after an earlier call to
 *   evdns_clear_nameservers_and_suspend().
 *
 * int evdns_config_windows_nameservers(void)
 *   Attempt to configure a set of nameservers based on platform settings on
 *   a win32 host.  Preferentially tries to use GetNetworkParams; if that fails,
 *   looks in the registry.  Returns 0 on success, nonzero on failure.
 *
 * int evdns_resolv_conf_parse(int flags, const char *filename)
 *   Parse a resolv.conf like file from the given filename.
 *
 *   See the man page for resolv.conf for the format of this file.
 *   The flags argument determines what information is parsed from
 *   this file:
 *     DNS_OPTION_SEARCH - domain, search and ndots options
 *     DNS_OPTION_NAMESERVERS - nameserver lines
 *     DNS_OPTION_MISC - timeout and attempts options
 *     DNS_OPTIONS_ALL - all of the above
 *   The following directives are not parsed from the file:
 *     sortlist, rotate, no-check-names, inet6, debug
 *
 *   Returns non-zero on error:
 *    0 no errors
 *    1 failed to open file
 *    2 failed to stat file
 *    3 file too large
 *    4 out of memory
 *    5 short read from file
 *    6 no nameservers in file
 *
 * Internals:
 *
 * Requests are kept in two queues. The first is the inflight queue. In
 * this queue requests have an allocated transaction id and nameserver.
 * They will soon be transmitted if they haven't already been.
 *
 * The second is the waiting queue. The size of the inflight ring is
 * limited and all other requests wait in waiting queue for space. This
 * bounds the number of concurrent requests so that we don't flood the
 * nameserver. Several algorithms require a full walk of the inflight
 * queue and so bounding its size keeps thing going nicely under huge
 * (many thousands of requests) loads.
 *
 * If a nameserver loses too many requests it is considered down and we
 * try not to use it. After a while we send a probe to that nameserver
 * (a lookup for google.com) and, if it replies, we consider it working
 * again. If the nameserver fails a probe we wait longer to try again
 * with the next probe.
 */

#ifndef EVENTDNS_H
#define EVENTDNS_H

#ifdef __cplusplus
extern "C" {
#endif

/* Error codes 0-5 are as described in RFC 1035. */
#define DNS_ERR_NONE 0
/* The name server was unable to interpret the query */
#define DNS_ERR_FORMAT 1
/* The name server was unable to process this query due to a problem with the
 * name server */
#define DNS_ERR_SERVERFAILED 2
/* The domain name does not exist */
#define DNS_ERR_NOTEXIST 3
/* The name server does not support the requested kind of query */
#define DNS_ERR_NOTIMPL 4
/* The name server refuses to reform the specified operation for policy
 * reasons */
#define DNS_ERR_REFUSED 5
/* The reply was truncated or ill-formated */
#define DNS_ERR_TRUNCATED 65
/* An unknown error occurred */
#define DNS_ERR_UNKNOWN 66
/* Communication with the server timed out */
#define DNS_ERR_TIMEOUT 67
/* The request was canceled because the DNS subsystem was shut down. */
#define DNS_ERR_SHUTDOWN 68

#define DNS_IPv4_A 1
#define DNS_PTR 2
#define DNS_IPv6_AAAA 3

#define DNS_QUERY_NO_SEARCH 1

#define DNS_OPTION_SEARCH 1
#define DNS_OPTION_NAMESERVERS 2
#define DNS_OPTION_MISC 4
#define DNS_OPTIONS_ALL 7

/* 
 * The callback that contains the results from a lookup.
 * - type is either DNS_IPv4_A or DNS_PTR or DNS_IPv6_AAAA
 * - count contains the number of addresses of form type
 * - ttl is the number of seconds the resolution may be cached for.
 * - addresses needs to be cast according to type
 */
typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);

int evdns_init(void);
void evdns_shutdown(int fail_requests);
const char *evdns_err_to_string(int err);
int evdns_nameserver_add(unsigned long int address);
int evdns_count_nameservers(void);
int evdns_clear_nameservers_and_suspend(void);
int evdns_resume(void);
int evdns_nameserver_ip_add(const char *ip_as_string);
int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr);
int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
struct in_addr;
struct in6_addr;
int evdns_resolve_reverse(struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
int evdns_resolve_reverse_ipv6(struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
int evdns_set_option(const char *option, const char *val, int flags);
int evdns_resolv_conf_parse(int flags, const char *);
#ifdef MS_WINDOWS
int evdns_config_windows_nameservers(void);
#endif
void evdns_search_clear(void);
void evdns_search_add(const char *domain);
void evdns_search_ndots_set(const int ndots);

typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
void evdns_set_log_fn(evdns_debug_log_fn_type fn);

#define DNS_NO_SEARCH 1

#ifdef __cplusplus
}
#endif

/*
 * Structures and functions used to implement a DNS server.
 */

struct evdns_server_request {
        int flags;
        int nquestions;
        struct evdns_server_question **questions;
};
struct evdns_server_question {
        int type;
        int class;
        char name[1];
};
typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void *);
#define EVDNS_ANSWER_SECTION 0
#define EVDNS_AUTHORITY_SECTION 1
#define EVDNS_ADDITIONAL_SECTION 2

#define EVDNS_TYPE_A       1
#define EVDNS_TYPE_NS      2
#define EVDNS_TYPE_CNAME   5
#define EVDNS_TYPE_SOA     6
#define EVDNS_TYPE_PTR    12
#define EVDNS_TYPE_MX     15
#define EVDNS_TYPE_TXT    16
#define EVDNS_TYPE_AAAA   28

#define EVDNS_QTYPE_AXFR 252
#define EVDNS_QTYPE_ALL  255

#define EVDNS_CLASS_INET   1

struct evdns_server_port *evdns_add_server_port(int socket, int is_tcp, evdns_request_callback_fn_type callback, void *user_data);
void evdns_close_server_port(struct evdns_server_port *port);

int evdns_server_request_add_reply(struct evdns_server_request *req, int section, const char *name, int type, int class, int ttl, int datalen, int is_name, const char *data);
int evdns_server_request_add_a_reply(struct evdns_server_request *req, const char *name, int n, void *addrs, int ttl);
int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req, const char *name, int n, void *addrs, int ttl);
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);
int evdns_server_request_add_cname_reply(struct evdns_server_request *req, const char *name, const char *cname, int ttl);

int evdns_server_request_respond(struct evdns_server_request *req, int err);
int evdns_server_request_drop(struct evdns_server_request *req);
struct sockaddr;
int evdns_server_request_get_requesting_addr(struct evdns_server_request *_req, struct sockaddr *sa, int addr_len);

#endif  /* !EVENTDNS_H */
Revision:	1.1
Committed:	Fri Nov 2 22:39:57 2007 UTC (16 years, 10 months ago) by root
Content type:	text/plain
Branch:	MAIN
CVS Tags:	rel-0_5, rel-0_6, rel-0_51
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.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			/*
51			* Welcome, gentle reader
52			*
53			* Async DNS lookups are really a whole lot harder than they should be,
54			* mostly stemming from the fact that the libc resolver has never been
55			* very good at them. Before you use this library you should see if libc
56			* can do the job for you with the modern async call getaddrinfo_a
57			* (see http://www.imperialviolet.org/page25.html#e498). Otherwise,
58			* please continue.
59			*
60			* This code is based on libevent and you must call event_init before
61			* any of the APIs in this file. You must also seed the OpenSSL random
62			* source if you are using OpenSSL for ids (see below).
63			*
64			* This library is designed to be included and shipped with your source
65			* code. You statically link with it. You should also test for the
66			* existence of strtok_r and define HAVE_STRTOK_R if you have it.
67			*
68			* The DNS protocol requires a good source of id numbers and these
69			* numbers should be unpredictable for spoofing reasons. There are
70			* three methods for generating them here and you must define exactly
71			* one of them. In increasing order of preference:
72			*
73			* DNS_USE_GETTIMEOFDAY_FOR_ID:
74			* Using the bottom 16 bits of the usec result from gettimeofday. This
75			* is a pretty poor solution but should work anywhere.
76			* DNS_USE_CPU_CLOCK_FOR_ID:
77			* Using the bottom 16 bits of the nsec result from the CPU's time
78			* counter. This is better, but may not work everywhere. Requires
79			* POSIX realtime support and you'll need to link against -lrt on
80			* glibc systems at least.
81			* DNS_USE_OPENSSL_FOR_ID:
82			* Uses the OpenSSL RAND_bytes call to generate the data. You must
83			* have seeded the pool before making any calls to this library.
84			*
85			* The library keeps track of the state of nameservers and will avoid
86			* them when they go down. Otherwise it will round robin between them.
87			*
88			* Quick start guide:
89			* #include "evdns.h"
90			* void callback(int result, char type, int count, int ttl,
91			* void addresses, void arg);
92			* evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
93			* evdns_resolve("www.hostname.com", 0, callback, NULL);
94			*
95			* When the lookup is complete the callback function is called. The
96			* first argument will be one of the DNS_ERR_* defines in evdns.h.
97			* Hopefully it will be DNS_ERR_NONE, in which case type will be
98			* DNS_IPv4_A, count will be the number of IP addresses, ttl is the time
99			* which the data can be cached for (in seconds), addresses will point
100			* to an array of uint32_t's and arg will be whatever you passed to
101			* evdns_resolve.
102			*
103			* Searching:
104			*
105			* In order for this library to be a good replacement for glibc's resolver it
106			* supports searching. This involves setting a list of default domains, in
107			* which names will be queried for. The number of dots in the query name
108			* determines the order in which this list is used.
109			*
110			* Searching appears to be a single lookup from the point of view of the API,
111			* although many DNS queries may be generated from a single call to
112			* evdns_resolve. Searching can also drastically slow down the resolution
113			* of names.
114			*
115			* To disable searching:
116			* 1. Never set it up. If you never call evdns_resolv_conf_parse or
117			* evdns_search_add then no searching will occur.
118			*
119			* 2. If you do call evdns_resolv_conf_parse then don't pass
120			* DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it).
121			*
122			* 3. When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag.
123			*
124			* The order of searches depends on the number of dots in the name. If the
125			* number is greater than the ndots setting then the names is first tried
126			* globally. Otherwise each search domain is appended in turn.
127			*
128			* The ndots setting can either be set from a resolv.conf, or by calling
129			* evdns_search_ndots_set.
130			*
131			* For example, with ndots set to 1 (the default) and a search domain list of
132			* ["myhome.net"]:
133			* Query: www
134			* Order: www.myhome.net, www.
135			*
136			* Query: www.abc
137			* Order: www.abc., www.abc.myhome.net
138			*
139			* API reference:
140			*
141			* int evdns_nameserver_add(unsigned long int address)
142			* Add a nameserver. The address should be an IP address in
143			* network byte order. The type of address is chosen so that
144			* it matches in_addr.s_addr.
145			* Returns non-zero on error.
146			*
147			* int evdns_nameserver_ip_add(const char *ip_as_string)
148			* This wraps the above function by parsing a string as an IP
149			* address and adds it as a nameserver.
150			* Returns non-zero on error
151			*
152			* int evdns_resolve(const char *name, int flags,
153			* evdns_callback_type callback,
154			* void *ptr)
155			* Resolve a name. The name parameter should be a DNS name.
156			* The flags parameter should be 0, or DNS_QUERY_NO_SEARCH
157			* which disables searching for this query. (see defn of
158			* searching above).
159			*
160			* The callback argument is a function which is called when
161			* this query completes and ptr is an argument which is passed
162			* to that callback function.
163			*
164			* Returns non-zero on error
165			*
166			* void evdns_search_clear()
167			* Clears the list of search domains
168			*
169			* void evdns_search_add(const char *domain)
170			* Add a domain to the list of search domains
171			*
172			* void evdns_search_ndots_set(int ndots)
173			* Set the number of dots which, when found in a name, causes
174			* the first query to be without any search domain.
175			*
176			* int evdns_count_nameservers(void)
177			* Return the number of configured nameservers (not necessarily the
178			* number of running nameservers). This is useful for double-checking
179			* whether our calls to the various nameserver configuration functions
180			* have been successful.
181			*
182			* int evdns_clear_nameservers_and_suspend(void)
183			* Remove all currently configured nameservers, and suspend all pending
184			* resolves. Resolves will not necessarily be re-attempted until
185			* evdns_resume() is called.
186			*
187			* int evdns_resume(void)
188			* Re-attempt resolves left in limbo after an earlier call to
189			* evdns_clear_nameservers_and_suspend().
190			*
191			* int evdns_config_windows_nameservers(void)
192			* Attempt to configure a set of nameservers based on platform settings on
193			* a win32 host. Preferentially tries to use GetNetworkParams; if that fails,
194			* looks in the registry. Returns 0 on success, nonzero on failure.
195			*
196			* int evdns_resolv_conf_parse(int flags, const char *filename)
197			* Parse a resolv.conf like file from the given filename.
198			*
199			* See the man page for resolv.conf for the format of this file.
200			* The flags argument determines what information is parsed from
201			* this file:
202			* DNS_OPTION_SEARCH - domain, search and ndots options
203			* DNS_OPTION_NAMESERVERS - nameserver lines
204			* DNS_OPTION_MISC - timeout and attempts options
205			* DNS_OPTIONS_ALL - all of the above
206			* The following directives are not parsed from the file:
207			* sortlist, rotate, no-check-names, inet6, debug
208			*
209			* Returns non-zero on error:
210			* 0 no errors
211			* 1 failed to open file
212			* 2 failed to stat file
213			* 3 file too large
214			* 4 out of memory
215			* 5 short read from file
216			* 6 no nameservers in file
217			*
218			* Internals:
219			*
220			* Requests are kept in two queues. The first is the inflight queue. In
221			* this queue requests have an allocated transaction id and nameserver.
222			* They will soon be transmitted if they haven't already been.
223			*
224			* The second is the waiting queue. The size of the inflight ring is
225			* limited and all other requests wait in waiting queue for space. This
226			* bounds the number of concurrent requests so that we don't flood the
227			* nameserver. Several algorithms require a full walk of the inflight
228			* queue and so bounding its size keeps thing going nicely under huge
229			* (many thousands of requests) loads.
230			*
231			* If a nameserver loses too many requests it is considered down and we
232			* try not to use it. After a while we send a probe to that nameserver
233			* (a lookup for google.com) and, if it replies, we consider it working
234			* again. If the nameserver fails a probe we wait longer to try again
235			* with the next probe.
236			*/
237
238			#ifndef EVENTDNS_H
239			#define EVENTDNS_H
240
241			#ifdef __cplusplus
242			extern "C" {
243			#endif
244
245			/* Error codes 0-5 are as described in RFC 1035. */
246			#define DNS_ERR_NONE 0
247			/* The name server was unable to interpret the query */
248			#define DNS_ERR_FORMAT 1
249			/* The name server was unable to process this query due to a problem with the
250			* name server */
251			#define DNS_ERR_SERVERFAILED 2
252			/* The domain name does not exist */
253			#define DNS_ERR_NOTEXIST 3
254			/* The name server does not support the requested kind of query */
255			#define DNS_ERR_NOTIMPL 4
256			/* The name server refuses to reform the specified operation for policy
257			* reasons */
258			#define DNS_ERR_REFUSED 5
259			/* The reply was truncated or ill-formated */
260			#define DNS_ERR_TRUNCATED 65
261			/* An unknown error occurred */
262			#define DNS_ERR_UNKNOWN 66
263			/* Communication with the server timed out */
264			#define DNS_ERR_TIMEOUT 67
265			/* The request was canceled because the DNS subsystem was shut down. */
266			#define DNS_ERR_SHUTDOWN 68
267
268			#define DNS_IPv4_A 1
269			#define DNS_PTR 2
270			#define DNS_IPv6_AAAA 3
271
272			#define DNS_QUERY_NO_SEARCH 1
273
274			#define DNS_OPTION_SEARCH 1
275			#define DNS_OPTION_NAMESERVERS 2
276			#define DNS_OPTION_MISC 4
277			#define DNS_OPTIONS_ALL 7
278
279			/*
280			* The callback that contains the results from a lookup.
281			* - type is either DNS_IPv4_A or DNS_PTR or DNS_IPv6_AAAA
282			* - count contains the number of addresses of form type
283			* - ttl is the number of seconds the resolution may be cached for.
284			* - addresses needs to be cast according to type
285			*/
286			typedef void (evdns_callback_type) (int result, char type, int count, int ttl, void addresses, void *arg);
287
288			int evdns_init(void);
289			void evdns_shutdown(int fail_requests);
290			const char *evdns_err_to_string(int err);
291			int evdns_nameserver_add(unsigned long int address);
292			int evdns_count_nameservers(void);
293			int evdns_clear_nameservers_and_suspend(void);
294			int evdns_resume(void);
295			int evdns_nameserver_ip_add(const char *ip_as_string);
296			int evdns_resolve_ipv4(const char name, int flags, evdns_callback_type callback, void ptr);
297			int evdns_resolve_ipv6(const char name, int flags, evdns_callback_type callback, void ptr);
298			struct in_addr;
299			struct in6_addr;
300			int evdns_resolve_reverse(struct in_addr in, int flags, evdns_callback_type callback, void ptr);
301			int evdns_resolve_reverse_ipv6(struct in6_addr in, int flags, evdns_callback_type callback, void ptr);
302			int evdns_set_option(const char option, const char val, int flags);
303			int evdns_resolv_conf_parse(int flags, const char *);
304			#ifdef MS_WINDOWS
305			int evdns_config_windows_nameservers(void);
306			#endif
307			void evdns_search_clear(void);
308			void evdns_search_add(const char *domain);
309			void evdns_search_ndots_set(const int ndots);
310
311			typedef void (evdns_debug_log_fn_type)(int is_warning, const char msg);
312			void evdns_set_log_fn(evdns_debug_log_fn_type fn);
313
314			#define DNS_NO_SEARCH 1
315
316			#ifdef __cplusplus
317			}
318			#endif
319
320			/*
321			* Structures and functions used to implement a DNS server.
322			*/
323
324			struct evdns_server_request {
325			int flags;
326			int nquestions;
327			struct evdns_server_question **questions;
328			};
329			struct evdns_server_question {
330			int type;
331			int class;
332			char name[1];
333			};
334			typedef void (evdns_request_callback_fn_type)(struct evdns_server_request , void *);
335			#define EVDNS_ANSWER_SECTION 0
336			#define EVDNS_AUTHORITY_SECTION 1
337			#define EVDNS_ADDITIONAL_SECTION 2
338
339			#define EVDNS_TYPE_A 1
340			#define EVDNS_TYPE_NS 2
341			#define EVDNS_TYPE_CNAME 5
342			#define EVDNS_TYPE_SOA 6
343			#define EVDNS_TYPE_PTR 12
344			#define EVDNS_TYPE_MX 15
345			#define EVDNS_TYPE_TXT 16
346			#define EVDNS_TYPE_AAAA 28
347
348			#define EVDNS_QTYPE_AXFR 252
349			#define EVDNS_QTYPE_ALL 255
350
351			#define EVDNS_CLASS_INET 1
352
353			struct evdns_server_port evdns_add_server_port(int socket, int is_tcp, evdns_request_callback_fn_type callback, void user_data);
354			void evdns_close_server_port(struct evdns_server_port *port);
355
356			int evdns_server_request_add_reply(struct evdns_server_request req, int section, const char name, int type, int class, int ttl, int datalen, int is_name, const char *data);
357			int evdns_server_request_add_a_reply(struct evdns_server_request req, const char name, int n, void *addrs, int ttl);
358			int evdns_server_request_add_aaaa_reply(struct evdns_server_request req, const char name, int n, void *addrs, int ttl);
359			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);
360			int evdns_server_request_add_cname_reply(struct evdns_server_request req, const char name, const char *cname, int ttl);
361
362			int evdns_server_request_respond(struct evdns_server_request *req, int err);
363			int evdns_server_request_drop(struct evdns_server_request *req);
364			struct sockaddr;
365			int evdns_server_request_get_requesting_addr(struct evdns_server_request _req, struct sockaddr sa, int addr_len);
366
367			#endif /* !EVENTDNS_H */