dns.h

Go to the documentation of this file.

/*
 * Copyright (c) 2006-2007 Niels Provos <provos@citi.umich.edu>
 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
 *
 * 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)
 */
 
#ifndef EVENT2_DNS_H_INCLUDED_
#define EVENT2_DNS_H_INCLUDED_
 
#include <event2/visibility.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* For integer types. */
#include <event2/util.h>
 
#define DNS_ERR_NONE 0
 
#define DNS_ERR_FORMAT 1
 
#define DNS_ERR_SERVERFAILED 2
 
#define DNS_ERR_NOTEXIST 3
 
#define DNS_ERR_NOTIMPL 4
 
#define DNS_ERR_REFUSED 5
 
#define DNS_ERR_TRUNCATED 65
 
#define DNS_ERR_UNKNOWN 66
 
#define DNS_ERR_TIMEOUT 67
 
#define DNS_ERR_SHUTDOWN 68
 
#define DNS_ERR_CANCEL 69
 
#define DNS_ERR_NODATA 70
 
#define DNS_IPv4_A 1
#define DNS_PTR 2
#define DNS_IPv6_AAAA 3
#define DNS_CNAME 4
 
#define DNS_QUERY_NO_SEARCH 0x01
 
#define DNS_QUERY_USEVC 0x02
 
#define DNS_QUERY_IGNTC 0x04
 
#define DNS_CNAME_CALLBACK 0x80
 
/* Allow searching */
#define DNS_OPTION_SEARCH 1
/* Parse "nameserver" and add default if no such section */
#define DNS_OPTION_NAMESERVERS 2
/* Parse additional options like:
 * - timeout:
 * - getaddrinfo-allow-skew:
 * - max-timeouts:
 * - max-inflight:
 * - attempts:
 * - randomize-case:
 * - initial-probe-timeout:
 * - max-probe-timeout:
 * - probe-backoff-factor:
 * - tcp-idle-timeout:
 * - edns-udp-size:
 * - use-vc
 * - ignore-tc
 */
#define DNS_OPTION_MISC 4
/* Load hosts file (i.e. "/etc/hosts") */
#define DNS_OPTION_HOSTSFILE 8
 
#define DNS_OPTIONS_ALL (    \
    DNS_OPTION_SEARCH      | \
    DNS_OPTION_NAMESERVERS | \
    DNS_OPTION_MISC        | \
    DNS_OPTION_HOSTSFILE   | \
    0                        \
)
/* Do not "default" nameserver (i.e. "127.0.0.1:53") if there is no nameservers
 * in resolv.conf, (iff DNS_OPTION_NAMESERVERS is set) */
#define DNS_OPTION_NAMESERVERS_NO_DEFAULT 16
 
/* Obsolete name for DNS_QUERY_NO_SEARCH */
#define DNS_NO_SEARCH DNS_QUERY_NO_SEARCH
 
typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);
 
struct evdns_base;
struct event_base;
 
#define EVDNS_BASE_INITIALIZE_NAMESERVERS 1
 
#define EVDNS_BASE_DISABLE_WHEN_INACTIVE 0x8000
 
#define EVDNS_BASE_NAMESERVERS_NO_DEFAULT 0x10000
 
/* No errors */
#define EVDNS_ERROR_NONE 0
/* Failed to open file */
#define EVDNS_ERROR_FAILED_TO_OPEN_FILE 1
/* Failed to stat file */
#define EVDNS_ERROR_FAILED_TO_STAT_FILE 2
/* File too large */
#define EVDNS_ERROR_FILE_TOO_LARGE 3
/* Out of memory */
#define EVDNS_ERROR_OUT_OF_MEMORY 4
/* Short read from file */
#define EVDNS_ERROR_SHORT_READ_FROM_FILE 5
/* No nameservers configured */
#define EVDNS_ERROR_NO_NAMESERVERS_CONFIGURED 6
 
EVENT2_EXPORT_SYMBOL
struct evdns_base * evdns_base_new(struct event_base *event_base, int flags);
 
 
EVENT2_EXPORT_SYMBOL
void evdns_base_free(struct evdns_base *base, int fail_requests);
 
EVENT2_EXPORT_SYMBOL
void evdns_base_clear_host_addresses(struct evdns_base *base);
 
EVENT2_EXPORT_SYMBOL
const char *evdns_err_to_string(int err);
 
 
EVENT2_EXPORT_SYMBOL
int evdns_base_nameserver_add(struct evdns_base *base,
    unsigned long int address);
 
EVENT2_EXPORT_SYMBOL
int evdns_base_count_nameservers(struct evdns_base *base);
 
EVENT2_EXPORT_SYMBOL
int evdns_base_clear_nameservers_and_suspend(struct evdns_base *base);
 
 
EVENT2_EXPORT_SYMBOL
int evdns_base_resume(struct evdns_base *base);
 
EVENT2_EXPORT_SYMBOL
int evdns_base_nameserver_ip_add(struct evdns_base *base,
    const char *ip_as_string);
 
EVENT2_EXPORT_SYMBOL
int
evdns_base_nameserver_sockaddr_add(struct evdns_base *base,
    const struct sockaddr *sa, ev_socklen_t len, unsigned flags);
 
struct evdns_request;
 
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);
 
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);
 
struct in_addr;
struct in6_addr;
 
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);
 
 
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);
 
EVENT2_EXPORT_SYMBOL
void evdns_cancel_request(struct evdns_base *base, struct evdns_request *req);
 
EVENT2_EXPORT_SYMBOL
int evdns_base_set_option(struct evdns_base *base, const char *option, const char *val);
 
 
EVENT2_EXPORT_SYMBOL
int evdns_base_resolv_conf_parse(struct evdns_base *base, int flags, const char *const filename);
 
EVENT2_EXPORT_SYMBOL
int evdns_base_load_hosts(struct evdns_base *base, const char *hosts_fname);
 
#if defined(EVENT_IN_DOXYGEN_) || defined(_WIN32)
 
EVENT2_EXPORT_SYMBOL
int evdns_base_config_windows_nameservers(struct evdns_base *);
#define EVDNS_BASE_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
#endif
 
 
EVENT2_EXPORT_SYMBOL
void evdns_base_search_clear(struct evdns_base *base);
 
 
EVENT2_EXPORT_SYMBOL
void evdns_base_search_add(struct evdns_base *base, const char *domain);
 
 
EVENT2_EXPORT_SYMBOL
void evdns_base_search_ndots_set(struct evdns_base *base, const int ndots);
 
typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
 
 
EVENT2_EXPORT_SYMBOL
void evdns_set_log_fn(evdns_debug_log_fn_type fn);
 
/*
 * Functions used to implement a DNS server.
 */
 
struct evdns_server_request;
struct evdns_server_question;
 
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
 
/* flags that can be set in answers; as part of the err parameter */
#define EVDNS_FLAGS_AA  0x400
#define EVDNS_FLAGS_RD  0x080
 
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);
 
struct evconnlistener;
 
EVENT2_EXPORT_SYMBOL
struct evdns_server_port *evdns_add_server_port_with_listener(
    struct event_base *base, struct evconnlistener *listener, int flags,
    evdns_request_callback_fn_type callback, void *user_data);
 
EVENT2_EXPORT_SYMBOL
void evdns_close_server_port(struct evdns_server_port *port);
 
enum evdns_server_option {
    EVDNS_SOPT_TCP_MAX_CLIENTS,
    EVDNS_SOPT_TCP_IDLE_TIMEOUT,
};
 
EVENT2_EXPORT_SYMBOL
int evdns_server_port_set_option(struct evdns_server_port *port, enum evdns_server_option option, size_t value);
 
EVENT2_EXPORT_SYMBOL
void evdns_server_request_set_flags(struct evdns_server_request *req, int flags);
 
/* Functions to add an answer to an in-progress DNS reply.
 */
EVENT2_EXPORT_SYMBOL
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);
EVENT2_EXPORT_SYMBOL
int evdns_server_request_add_a_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
EVENT2_EXPORT_SYMBOL
int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
EVENT2_EXPORT_SYMBOL
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);
EVENT2_EXPORT_SYMBOL
int evdns_server_request_add_cname_reply(struct evdns_server_request *req, const char *name, const char *cname, int ttl);
 
EVENT2_EXPORT_SYMBOL
int evdns_server_request_respond(struct evdns_server_request *req, int err);
EVENT2_EXPORT_SYMBOL
int evdns_server_request_drop(struct evdns_server_request *req);
struct sockaddr;
EVENT2_EXPORT_SYMBOL
int evdns_server_request_get_requesting_addr(struct evdns_server_request *req, struct sockaddr *sa, int addr_len);
 
typedef void (*evdns_getaddrinfo_cb)(int result, struct evutil_addrinfo *res, void *arg);
 
struct evdns_base;
struct evdns_getaddrinfo_request;
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);
 
/* Cancel an in-progress evdns_getaddrinfo.  This MUST NOT be called after the
 * getaddrinfo's callback has been invoked.  The resolves will be canceled,
 * and the callback will be invoked with the error EVUTIL_EAI_CANCEL. */
EVENT2_EXPORT_SYMBOL
void evdns_getaddrinfo_cancel(struct evdns_getaddrinfo_request *req);
 
EVENT2_EXPORT_SYMBOL
int evdns_base_get_nameserver_addr(struct evdns_base *base, int idx,
    struct sockaddr *sa, ev_socklen_t len);
 
EVENT2_EXPORT_SYMBOL
int evdns_base_get_nameserver_fd(struct evdns_base *base, int idx);
 
#ifdef __cplusplus
}
#endif
 
#endif  /* !EVENT2_DNS_H_INCLUDED_ */