libevent
dns.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2006-2007 Niels Provos <provos@citi.umich.edu>
3  * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
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 
135 #ifndef _EVENT2_DNS_H_
136 #define _EVENT2_DNS_H_
137 
138 #ifdef __cplusplus
139 extern "C" {
140 #endif
141 
142 /* For integer types. */
143 #include <event2/util.h>
144 
146 #define DNS_ERR_NONE 0
147 
148 #define DNS_ERR_FORMAT 1
149 
151 #define DNS_ERR_SERVERFAILED 2
152 
153 #define DNS_ERR_NOTEXIST 3
154 
155 #define DNS_ERR_NOTIMPL 4
156 
158 #define DNS_ERR_REFUSED 5
159 
160 #define DNS_ERR_TRUNCATED 65
161 
162 #define DNS_ERR_UNKNOWN 66
163 
164 #define DNS_ERR_TIMEOUT 67
165 
166 #define DNS_ERR_SHUTDOWN 68
167 
168 #define DNS_ERR_CANCEL 69
169 
172 #define DNS_ERR_NODATA 70
173 
174 #define DNS_IPv4_A 1
175 #define DNS_PTR 2
176 #define DNS_IPv6_AAAA 3
177 
178 #define DNS_QUERY_NO_SEARCH 1
179 
180 #define DNS_OPTION_SEARCH 1
181 #define DNS_OPTION_NAMESERVERS 2
182 #define DNS_OPTION_MISC 4
183 #define DNS_OPTION_HOSTSFILE 8
184 #define DNS_OPTIONS_ALL 15
185 
186 /* Obsolete name for DNS_QUERY_NO_SEARCH */
187 #define DNS_NO_SEARCH DNS_QUERY_NO_SEARCH
188 
199 typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);
200 
201 struct evdns_base;
202 struct event_base;
203 
216 struct evdns_base * evdns_base_new(struct event_base *event_base, int initialize_nameservers);
217 
218 
231 void evdns_base_free(struct evdns_base *base, int fail_requests);
232 
239 const char *evdns_err_to_string(int err);
240 
241 
253 int evdns_base_nameserver_add(struct evdns_base *base,
254  unsigned long int address);
255 
268 int evdns_base_count_nameservers(struct evdns_base *base);
269 
279 int evdns_base_clear_nameservers_and_suspend(struct evdns_base *base);
280 
281 
292 int evdns_base_resume(struct evdns_base *base);
293 
311 int evdns_base_nameserver_ip_add(struct evdns_base *base,
312  const char *ip_as_string);
313 
317 int
318 evdns_base_nameserver_sockaddr_add(struct evdns_base *base,
319  const struct sockaddr *sa, ev_socklen_t len, unsigned flags);
320 
321 struct evdns_request;
322 
334 struct evdns_request *evdns_base_resolve_ipv4(struct evdns_base *base, const char *name, int flags, evdns_callback_type callback, void *ptr);
335 
347 struct evdns_request *evdns_base_resolve_ipv6(struct evdns_base *base, const char *name, int flags, evdns_callback_type callback, void *ptr);
348 
349 struct in_addr;
350 struct in6_addr;
351 
363 struct evdns_request *evdns_base_resolve_reverse(struct evdns_base *base, const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
364 
365 
377 struct evdns_request *evdns_base_resolve_reverse_ipv6(struct evdns_base *base, const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
378 
386 void evdns_cancel_request(struct evdns_base *base, struct evdns_request *req);
387 
404 int evdns_base_set_option(struct evdns_base *base, const char *option, const char *val);
405 
406 
429 int evdns_base_resolv_conf_parse(struct evdns_base *base, int flags, const char *const filename);
430 
441 int evdns_base_load_hosts(struct evdns_base *base, const char *hosts_fname);
442 
453 #ifdef WIN32
454 int evdns_base_config_windows_nameservers(struct evdns_base *);
455 #define EVDNS_BASE_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
456 #endif
457 
458 
462 void evdns_base_search_clear(struct evdns_base *base);
463 
464 
470 void evdns_base_search_add(struct evdns_base *base, const char *domain);
471 
472 
481 void evdns_base_search_ndots_set(struct evdns_base *base, const int ndots);
482 
489 typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
490 
491 
500 
511 void evdns_set_transaction_id_fn(ev_uint16_t (*fn)(void));
512 
522 void evdns_set_random_bytes_fn(void (*fn)(char *, size_t));
523 
524 /*
525  * Functions used to implement a DNS server.
526  */
527 
528 struct evdns_server_request;
529 struct evdns_server_question;
530 
542 typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void *);
543 #define EVDNS_ANSWER_SECTION 0
544 #define EVDNS_AUTHORITY_SECTION 1
545 #define EVDNS_ADDITIONAL_SECTION 2
546 
547 #define EVDNS_TYPE_A 1
548 #define EVDNS_TYPE_NS 2
549 #define EVDNS_TYPE_CNAME 5
550 #define EVDNS_TYPE_SOA 6
551 #define EVDNS_TYPE_PTR 12
552 #define EVDNS_TYPE_MX 15
553 #define EVDNS_TYPE_TXT 16
554 #define EVDNS_TYPE_AAAA 28
555 
556 #define EVDNS_QTYPE_AXFR 252
557 #define EVDNS_QTYPE_ALL 255
558 
559 #define EVDNS_CLASS_INET 1
560 
561 /* flags that can be set in answers; as part of the err parameter */
562 #define EVDNS_FLAGS_AA 0x400
563 #define EVDNS_FLAGS_RD 0x080
564 
575 struct evdns_server_port *evdns_add_server_port_with_base(struct event_base *base, evutil_socket_t socket, int flags, evdns_request_callback_fn_type callback, void *user_data);
577 void evdns_close_server_port(struct evdns_server_port *port);
578 
582 void evdns_server_request_set_flags(struct evdns_server_request *req, int flags);
583 
584 /* Functions to add an answer to an in-progress DNS reply.
585  */
586 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);
587 int evdns_server_request_add_a_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
588 int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
589 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);
590 int evdns_server_request_add_cname_reply(struct evdns_server_request *req, const char *name, const char *cname, int ttl);
591 
595 int evdns_server_request_respond(struct evdns_server_request *req, int err);
599 int evdns_server_request_drop(struct evdns_server_request *req);
600 struct sockaddr;
604 int evdns_server_request_get_requesting_addr(struct evdns_server_request *_req, struct sockaddr *sa, int addr_len);
605 
607 typedef void (*evdns_getaddrinfo_cb)(int result, struct evutil_addrinfo *res, void *arg);
608 
609 struct evdns_base;
610 struct evdns_getaddrinfo_request;
628 struct evdns_getaddrinfo_request *evdns_getaddrinfo(
629  struct evdns_base *dns_base,
630  const char *nodename, const char *servname,
631  const struct evutil_addrinfo *hints_in,
632  evdns_getaddrinfo_cb cb, void *arg);
633 
634 /* Cancel an in-progress evdns_getaddrinfo. This MUST NOT be called after the
635  * getaddrinfo's callback has been invoked. The resolves will be canceled,
636  * and the callback will be invoked with the error EVUTIL_EAI_CANCEL. */
637 void evdns_getaddrinfo_cancel(struct evdns_getaddrinfo_request *req);
638 
639 #ifdef __cplusplus
640 }
641 #endif
642 
643 #endif /* !_EVENT2_DNS_H_ */
struct evdns_getaddrinfo_request * evdns_getaddrinfo(struct evdns_base *dns_base, const char *nodename, const char *servname, const struct evutil_addrinfo *hints_in, evdns_getaddrinfo_cb cb, void *arg)
Make a non-blocking getaddrinfo request using the dns_base in &#39;dns_base&#39;.
void evdns_set_log_fn(evdns_debug_log_fn_type fn)
Set the callback function to handle DNS log messages.
int evdns_base_resolv_conf_parse(struct evdns_base *base, int flags, const char *const filename)
Parse a resolv.conf file.
void(* evdns_debug_log_fn_type)(int is_warning, const char *msg)
A callback that is invoked when a log message is generated.
Definition: dns.h:489
struct evdns_request * evdns_base_resolve_ipv6(struct evdns_base *base, const char *name, int flags, evdns_callback_type callback, void *ptr)
Lookup an AAAA record for a given name.
struct evdns_request * evdns_base_resolve_reverse(struct evdns_base *base, const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr)
Lookup a PTR record for a given IP address.
int evdns_base_load_hosts(struct evdns_base *base, const char *hosts_fname)
Load an /etc/hosts-style file from &#39;hosts_fname&#39; into &#39;base&#39;.
int evdns_server_request_respond(struct evdns_server_request *req, int err)
Send back a response to a DNS request, and free the request structure.
int evdns_base_resume(struct evdns_base *base)
Resume normal operation and continue any suspended resolve requests.
int evdns_server_request_drop(struct evdns_server_request *req)
Free a DNS request without sending back a reply.
const char * evdns_err_to_string(int err)
Convert a DNS error code to a string.
void evdns_close_server_port(struct evdns_server_port *port)
Close down a DNS server port, and free associated structures.
#define evutil_socket_t
A type wide enough to hold the output of "socket()" or "accept()".
Definition: util.h:274
void(* evdns_callback_type)(int result, char type, int count, int ttl, void *addresses, void *arg)
The callback that contains the results from a lookup.
Definition: dns.h:199
int evdns_base_clear_nameservers_and_suspend(struct evdns_base *base)
Remove all configured nameservers, and suspend all pending resolves.
void evdns_base_search_ndots_set(struct evdns_base *base, const int ndots)
Set the &#39;ndots&#39; parameter for searches.
Common convenience functions for cross-platform portability and related socket manipulations.
void(* evdns_request_callback_fn_type)(struct evdns_server_request *, void *)
A callback to implement a DNS server.
Definition: dns.h:542
int evdns_base_count_nameservers(struct evdns_base *base)
Get the number of configured nameservers.
struct evdns_base * evdns_base_new(struct event_base *event_base, int initialize_nameservers)
Initialize the asynchronous DNS library.
A definition of struct addrinfo for systems that lack it.
Definition: util.h:513
void(* evdns_getaddrinfo_cb)(int result, struct evutil_addrinfo *res, void *arg)
Callback for evdns_getaddrinfo.
Definition: dns.h:607
void evdns_set_random_bytes_fn(void(*fn)(char *, size_t))
Set a callback used to generate random bytes.
int evdns_base_set_option(struct evdns_base *base, const char *option, const char *val)
Set the value of a configuration option.
void evdns_set_transaction_id_fn(ev_uint16_t(*fn)(void))
Set a callback that will be invoked to generate transaction IDs.
void evdns_server_request_set_flags(struct evdns_server_request *req, int flags)
Sets some flags in a reply we&#39;re building.
void evdns_base_search_clear(struct evdns_base *base)
Obtain nameserver information using the Windows API.
void evdns_base_free(struct evdns_base *base, int fail_requests)
Shut down the asynchronous DNS resolver and terminate all active requests.
int evdns_base_nameserver_sockaddr_add(struct evdns_base *base, const struct sockaddr *sa, ev_socklen_t len, unsigned flags)
Add a nameserver by sockaddr.
int evdns_server_request_get_requesting_addr(struct evdns_server_request *_req, struct sockaddr *sa, int addr_len)
Get the address that made a DNS request.
struct evdns_request * evdns_base_resolve_ipv4(struct evdns_base *base, const char *name, int flags, evdns_callback_type callback, void *ptr)
Lookup an A record for a given name.
struct evdns_server_port * evdns_add_server_port_with_base(struct event_base *base, evutil_socket_t socket, int flags, evdns_request_callback_fn_type callback, void *user_data)
Create a new DNS server port.
void evdns_cancel_request(struct evdns_base *base, struct evdns_request *req)
Cancels a pending DNS resolution request.
int evdns_base_nameserver_ip_add(struct evdns_base *base, const char *ip_as_string)
Add a nameserver by string address.
void evdns_base_search_add(struct evdns_base *base, const char *domain)
Add a domain to the list of search domains.
struct evdns_request * evdns_base_resolve_reverse_ipv6(struct evdns_base *base, const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr)
Lookup a PTR record for a given IPv6 address.
Structure to hold information and state for a Libevent dispatch loop.
Definition: event.h:213
int evdns_base_nameserver_add(struct evdns_base *base, unsigned long int address)
Add a nameserver.