libevent: event2/dns.h Source File

libevent 2.1.12 Event notification library

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_INCLUDED_
136#define EVENT2_DNS_H_INCLUDED_
137
138#include <event2/visibility.h>
139
140#ifdef __cplusplus
141extern "C" {
142#endif
143
144/* For integer types. */
145#include <event2/util.h>
146
148#define DNS_ERR_NONE 0
150#define DNS_ERR_FORMAT 1
153#define DNS_ERR_SERVERFAILED 2
155#define DNS_ERR_NOTEXIST 3
157#define DNS_ERR_NOTIMPL 4
160#define DNS_ERR_REFUSED 5
162#define DNS_ERR_TRUNCATED 65
164#define DNS_ERR_UNKNOWN 66
166#define DNS_ERR_TIMEOUT 67
168#define DNS_ERR_SHUTDOWN 68
170#define DNS_ERR_CANCEL 69
174#define DNS_ERR_NODATA 70
175
176#define DNS_IPv4_A 1
177#define DNS_PTR 2
178#define DNS_IPv6_AAAA 3
179
180#define DNS_QUERY_NO_SEARCH 1
181
182/* Allow searching */
183#define DNS_OPTION_SEARCH 1
184/* Parse "nameserver" and add default if no such section */
185#define DNS_OPTION_NAMESERVERS 2
186/* Parse additional options like:
187 * - timeout:
188 * - getaddrinfo-allow-skew:
189 * - max-timeouts:
190 * - max-inflight:
191 * - attempts:
192 * - randomize-case:
193 * - initial-probe-timeout:
194 */
195#define DNS_OPTION_MISC 4
196/* Load hosts file (i.e. "/etc/hosts") */
197#define DNS_OPTION_HOSTSFILE 8
205#define DNS_OPTIONS_ALL ( \
206 DNS_OPTION_SEARCH | \
207 DNS_OPTION_NAMESERVERS | \
208 DNS_OPTION_MISC | \
209 DNS_OPTION_HOSTSFILE | \
210 0 \
211)
212/* Do not "default" nameserver (i.e. "127.0.0.1:53") if there is no nameservers
213 * in resolv.conf, (iff DNS_OPTION_NAMESERVERS is set) */
214#define DNS_OPTION_NAMESERVERS_NO_DEFAULT 16
215
216/* Obsolete name for DNS_QUERY_NO_SEARCH */
217#define DNS_NO_SEARCH DNS_QUERY_NO_SEARCH
218
229 typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);
230
231struct evdns_base;
232struct event_base;
233
235#define EVDNS_BASE_INITIALIZE_NAMESERVERS 1
238#define EVDNS_BASE_DISABLE_WHEN_INACTIVE 0x8000
242#define EVDNS_BASE_NAMESERVERS_NO_DEFAULT 0x10000
243
257EVENT2_EXPORT_SYMBOL
258 struct evdns_base * evdns_base_new(struct event_base *event_base, int initialize_nameservers);
259
260
273EVENT2_EXPORT_SYMBOL
274 void evdns_base_free(struct evdns_base *base, int fail_requests);
275
282EVENT2_EXPORT_SYMBOL
283 void evdns_base_clear_host_addresses(struct evdns_base *base);
284
291EVENT2_EXPORT_SYMBOL
292 const char *evdns_err_to_string(int err);
293
294
306EVENT2_EXPORT_SYMBOL
307 int evdns_base_nameserver_add(struct evdns_base *base,
308 unsigned long int address);
309
322EVENT2_EXPORT_SYMBOL
323 int evdns_base_count_nameservers(struct evdns_base *base);
324
334EVENT2_EXPORT_SYMBOL
335 int evdns_base_clear_nameservers_and_suspend(struct evdns_base *base);
336
337
348EVENT2_EXPORT_SYMBOL
349 int evdns_base_resume(struct evdns_base *base);
350
368EVENT2_EXPORT_SYMBOL
369 int evdns_base_nameserver_ip_add(struct evdns_base *base,
370 const char *ip_as_string);
371
375EVENT2_EXPORT_SYMBOL
376int
377evdns_base_nameserver_sockaddr_add(struct evdns_base *base,
378 const struct sockaddr *sa, ev_socklen_t len, unsigned flags);
379
380struct evdns_request;
381
393EVENT2_EXPORT_SYMBOL
394 struct evdns_request *evdns_base_resolve_ipv4(struct evdns_base *base, const char *name, int flags, evdns_callback_type callback, void *ptr);
395
407EVENT2_EXPORT_SYMBOL
408 struct evdns_request *evdns_base_resolve_ipv6(struct evdns_base *base, const char *name, int flags, evdns_callback_type callback, void *ptr);
409
410struct in_addr;
411struct in6_addr;
412
424EVENT2_EXPORT_SYMBOL
425 struct evdns_request *evdns_base_resolve_reverse(struct evdns_base *base, const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
426
427
439EVENT2_EXPORT_SYMBOL
440 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);
441
449EVENT2_EXPORT_SYMBOL
450 void evdns_cancel_request(struct evdns_base *base, struct evdns_request *req);
451
469EVENT2_EXPORT_SYMBOL
470 int evdns_base_set_option(struct evdns_base *base, const char *option, const char *val);
471
472
495EVENT2_EXPORT_SYMBOL
496 int evdns_base_resolv_conf_parse(struct evdns_base *base, int flags, const char *const filename);
497
511EVENT2_EXPORT_SYMBOL
512 int evdns_base_load_hosts(struct evdns_base *base, const char *hosts_fname);
513
514#if defined(EVENT_IN_DOXYGEN_) || defined(_WIN32)
525EVENT2_EXPORT_SYMBOL
526 int evdns_base_config_windows_nameservers(struct evdns_base *);
527#define EVDNS_BASE_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
528#endif
529
530
534EVENT2_EXPORT_SYMBOL
535 void evdns_base_search_clear(struct evdns_base *base);
536
537
543EVENT2_EXPORT_SYMBOL
544 void evdns_base_search_add(struct evdns_base *base, const char *domain);
545
546
555EVENT2_EXPORT_SYMBOL
556 void evdns_base_search_ndots_set(struct evdns_base *base, const int ndots);
557
564 typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
565
566
574EVENT2_EXPORT_SYMBOL
575 void evdns_set_log_fn(evdns_debug_log_fn_type fn);
576
587EVENT2_EXPORT_SYMBOL
588 void evdns_set_transaction_id_fn(ev_uint16_t (*fn)(void));
589
599EVENT2_EXPORT_SYMBOL
600 void evdns_set_random_bytes_fn(void (*fn)(char *, size_t));
601
602/*
603 * Functions used to implement a DNS server.
604 */
605
606struct evdns_server_request;
607struct evdns_server_question;
608
620 typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void *);
621#define EVDNS_ANSWER_SECTION 0
622#define EVDNS_AUTHORITY_SECTION 1
623#define EVDNS_ADDITIONAL_SECTION 2
624
625#define EVDNS_TYPE_A 1
626#define EVDNS_TYPE_NS 2
627#define EVDNS_TYPE_CNAME 5
628#define EVDNS_TYPE_SOA 6
629#define EVDNS_TYPE_PTR 12
630#define EVDNS_TYPE_MX 15
631#define EVDNS_TYPE_TXT 16
632#define EVDNS_TYPE_AAAA 28
633
634#define EVDNS_QTYPE_AXFR 252
635#define EVDNS_QTYPE_ALL 255
636
637#define EVDNS_CLASS_INET 1
638
639/* flags that can be set in answers; as part of the err parameter */
640#define EVDNS_FLAGS_AA 0x400
641#define EVDNS_FLAGS_RD 0x080
642
654EVENT2_EXPORT_SYMBOL
655 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);
657EVENT2_EXPORT_SYMBOL
658 void evdns_close_server_port(struct evdns_server_port *port);
659
663EVENT2_EXPORT_SYMBOL
664 void evdns_server_request_set_flags(struct evdns_server_request *req, int flags);
665
666/* Functions to add an answer to an in-progress DNS reply.
667 */
668EVENT2_EXPORT_SYMBOL
669int 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);
670EVENT2_EXPORT_SYMBOL
671int evdns_server_request_add_a_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
672EVENT2_EXPORT_SYMBOL
673int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
674EVENT2_EXPORT_SYMBOL
675int evdns_server_request_add_ptr_reply(struct evdns_server_request *req, struct in_addr *in, const char *inaddr_name, const char *hostname, int ttl);
676EVENT2_EXPORT_SYMBOL
677int evdns_server_request_add_cname_reply(struct evdns_server_request *req, const char *name, const char *cname, int ttl);
678
682EVENT2_EXPORT_SYMBOL
683 int evdns_server_request_respond(struct evdns_server_request *req, int err);
687EVENT2_EXPORT_SYMBOL
688 int evdns_server_request_drop(struct evdns_server_request *req);
689struct sockaddr;
693EVENT2_EXPORT_SYMBOL
694 int evdns_server_request_get_requesting_addr(struct evdns_server_request *req, struct sockaddr *sa, int addr_len);
695
697 typedef void (*evdns_getaddrinfo_cb)(int result, struct evutil_addrinfo *res, void *arg);
698
699struct evdns_base;
700struct evdns_getaddrinfo_request;
718EVENT2_EXPORT_SYMBOL
719 struct evdns_getaddrinfo_request *evdns_getaddrinfo(
720 struct evdns_base *dns_base,
721 const char *nodename, const char *servname,
722 const struct evutil_addrinfo *hints_in,
723 evdns_getaddrinfo_cb cb, void *arg);
724
725/* Cancel an in-progress evdns_getaddrinfo. This MUST NOT be called after the
726 * getaddrinfo's callback has been invoked. The resolves will be canceled,
727 * and the callback will be invoked with the error EVUTIL_EAI_CANCEL. */
728EVENT2_EXPORT_SYMBOL
729void evdns_getaddrinfo_cancel(struct evdns_getaddrinfo_request *req);
730
743EVENT2_EXPORT_SYMBOL
744 int evdns_base_get_nameserver_addr(struct evdns_base *base, int idx,
745 struct sockaddr *sa, ev_socklen_t len);
746
747#ifdef __cplusplus
748}
749#endif
750
751#endif /* !EVENT2_DNS_H_INCLUDED_ */
evdns_request_callback_fn_type
void(* evdns_request_callback_fn_type)(struct evdns_server_request *, void *)
A callback to implement a DNS server.
Definition: dns.h:620
evdns_cancel_request
EVENT2_EXPORT_SYMBOL void evdns_cancel_request(struct evdns_base *base, struct evdns_request *req)
Cancels a pending DNS resolution request.
evdns_server_request_get_requesting_addr
EVENT2_EXPORT_SYMBOL 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.
evdns_base_nameserver_ip_add
EVENT2_EXPORT_SYMBOL int evdns_base_nameserver_ip_add(struct evdns_base *base, const char *ip_as_string)
Add a nameserver by string address.
evdns_getaddrinfo_cb
void(* evdns_getaddrinfo_cb)(int result, struct evutil_addrinfo *res, void *arg)
Callback for evdns_getaddrinfo.
Definition: dns.h:697
evdns_base_resolve_reverse_ipv6
EVENT2_EXPORT_SYMBOL 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.
evdns_server_request_drop
EVENT2_EXPORT_SYMBOL int evdns_server_request_drop(struct evdns_server_request *req)
Free a DNS request without sending back a reply.
evdns_base_get_nameserver_addr
EVENT2_EXPORT_SYMBOL int evdns_base_get_nameserver_addr(struct evdns_base *base, int idx, struct sockaddr *sa, ev_socklen_t len)
Retrieve the address of the 'idx'th configured nameserver.
evdns_base_clear_host_addresses
EVENT2_EXPORT_SYMBOL void evdns_base_clear_host_addresses(struct evdns_base *base)
Remove all hosts entries that have been loaded into the event_base via evdns_base_load_hosts or via e...
evdns_set_transaction_id_fn
EVENT2_EXPORT_SYMBOL void evdns_set_transaction_id_fn(ev_uint16_t(*fn)(void))
Set a callback that will be invoked to generate transaction IDs.
evdns_base_resolve_reverse
EVENT2_EXPORT_SYMBOL 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.
evdns_base_resume
EVENT2_EXPORT_SYMBOL int evdns_base_resume(struct evdns_base *base)
Resume normal operation and continue any suspended resolve requests.
evdns_callback_type
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:229
evdns_base_load_hosts
EVENT2_EXPORT_SYMBOL int evdns_base_load_hosts(struct evdns_base *base, const char *hosts_fname)
Load an /etc/hosts-style file from 'hosts_fname' into 'base'.
evdns_base_nameserver_add
EVENT2_EXPORT_SYMBOL int evdns_base_nameserver_add(struct evdns_base *base, unsigned long int address)
Add a nameserver.
evdns_server_request_respond
EVENT2_EXPORT_SYMBOL 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.
evdns_err_to_string
EVENT2_EXPORT_SYMBOL const char * evdns_err_to_string(int err)
Convert a DNS error code to a string.
evdns_base_resolve_ipv6
EVENT2_EXPORT_SYMBOL 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.
evdns_base_count_nameservers
EVENT2_EXPORT_SYMBOL int evdns_base_count_nameservers(struct evdns_base *base)
Get the number of configured nameservers.
evdns_base_new
EVENT2_EXPORT_SYMBOL struct evdns_base * evdns_base_new(struct event_base *event_base, int initialize_nameservers)
Initialize the asynchronous DNS library.
evdns_base_set_option
EVENT2_EXPORT_SYMBOL int evdns_base_set_option(struct evdns_base *base, const char *option, const char *val)
Set the value of a configuration option.
evdns_base_resolv_conf_parse
EVENT2_EXPORT_SYMBOL int evdns_base_resolv_conf_parse(struct evdns_base *base, int flags, const char *const filename)
Parse a resolv.conf file.
evdns_base_search_add
EVENT2_EXPORT_SYMBOL void evdns_base_search_add(struct evdns_base *base, const char *domain)
Add a domain to the list of search domains.
evdns_server_request_set_flags
EVENT2_EXPORT_SYMBOL void evdns_server_request_set_flags(struct evdns_server_request *req, int flags)
Sets some flags in a reply we're building.
evdns_debug_log_fn_type
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:564
evdns_set_random_bytes_fn
EVENT2_EXPORT_SYMBOL void evdns_set_random_bytes_fn(void(*fn)(char *, size_t))
Set a callback used to generate random bytes.
evdns_base_search_clear
EVENT2_EXPORT_SYMBOL void evdns_base_search_clear(struct evdns_base *base)
Clear the list of search domains.
evdns_base_free
EVENT2_EXPORT_SYMBOL void evdns_base_free(struct evdns_base *base, int fail_requests)
Shut down the asynchronous DNS resolver and terminate all active requests.
evdns_close_server_port
EVENT2_EXPORT_SYMBOL void evdns_close_server_port(struct evdns_server_port *port)
Close down a DNS server port, and free associated structures.
evdns_base_config_windows_nameservers
EVENT2_EXPORT_SYMBOL int evdns_base_config_windows_nameservers(struct evdns_base *)
Obtain nameserver information using the Windows API.
evdns_base_nameserver_sockaddr_add
EVENT2_EXPORT_SYMBOL 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.
evdns_base_resolve_ipv4
EVENT2_EXPORT_SYMBOL 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.
evdns_add_server_port_with_base
EVENT2_EXPORT_SYMBOL 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.
evdns_getaddrinfo
EVENT2_EXPORT_SYMBOL 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 'dns_base'.
evdns_base_search_ndots_set
EVENT2_EXPORT_SYMBOL void evdns_base_search_ndots_set(struct evdns_base *base, const int ndots)
Set the 'ndots' parameter for searches.
evdns_set_log_fn
EVENT2_EXPORT_SYMBOL void evdns_set_log_fn(evdns_debug_log_fn_type fn)
Set the callback function to handle DNS log messages.
evdns_base_clear_nameservers_and_suspend
EVENT2_EXPORT_SYMBOL int evdns_base_clear_nameservers_and_suspend(struct evdns_base *base)
Remove all configured nameservers, and suspend all pending resolves.
event_base
Structure to hold information and state for a Libevent dispatch loop.
Definition: event.h:219
evutil_addrinfo
A definition of struct addrinfo for systems that lack it.
Definition: util.h:679
util.h
Common convenience functions for cross-platform portability and related socket manipulations.
evutil_socket_t
#define evutil_socket_t
A type wide enough to hold the output of "socket()" or "accept()".
Definition: util.h:310