Libevent提供了一些API用来进行DNS域名解析，并且提供了实现简单DNS服务器的能力。
本章首先描述域名解析的上层功能，然后介绍底层功能及服务器功能。
注意：Libevent的当前DNS客户端实现有一些限制，它不支持TCP查询，DNSSsec或者任意记录类型。将来的Libevent版本中可能会修复这些问题。
前言：可移植的阻塞型域名解析
为了帮助移植那些已经使用阻塞域名解析的应用程序，Libevent提供了一个标准getaddrinfo接口的可移植实现。这对于需要运行在某些特殊平台上的应用程序是很有帮助的，这些特殊平台要么没有提供getaddrinfo接口，要么其getaddrinfo接口不如我们的实现那样符合标准。
getaddrinfo接口在RFC3493的6.1章进行描述。下面的“兼容性注意事项”部分总结了在哪些方面还缺乏一致的实现。
struct evutil_addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
char * ai_canonname;
struct sockaddr *ai_addr;
struct evutil_addrinfo *ai_next;
};
#define EVUTIL_AI_PASSIVE /* ... */
#define EVUTIL_AI_CANONNAME /* ... */
#define EVUTIL_AI_NUMERICHOST /* ... */
#define EVUTIL_AI_NUMERICSERV /* ... */
#define EVUTIL_AI_V4MAPPED /* ... */
#define EVUTIL_AI_ALL /* ... */
#define EVUTIL_AI_ADDRCONFIG /* ... */
int evutil_getaddrinfo(const char *nodename, const char *servname,
const struct evutil_addrinfo *hints, struct evutil_addrinfo **res);
void evutil_freeaddrinfo(struct evutil_addrinfo *ai);
const char *evutil_gai_strerror(int err);
evutil_getaddrinfo函数尝试根据hints中的规则，解析nodename和servname，并在evutil_addrinfo结构的链表res中返回解析的结果。该函数返回0表示成功，失败时返回一个非0的错误码。
nodename和servname两者必须提供一个，如果提供了nodename，则它可以是一个文字型的IPv4地址（类似于“127.0.0.1”），或者一个文字型的IPv6地址（比如“::1”），或者是一个域名（比如“www.example.com”）。如果提供了servname，则它既可以是网络服务的符号名称（比如“https”），或者是一个十进制端口号的字符串（比如“443”）。
如果没有指定servname，则在*res中，端口号将置为0。如果不指定nodename，则*res中的地址要么是默认的本地地址，要么是“any”（如果设置了EVUTIL_AI_PASSIVE的话）
hints中的ai_flags字段提示evutil_getaddrinfo如何进行查找。它可以是0，或者是下列标志的组合：
EVUTIL_AI_PASSIVE：该标志表明，解析的地址将用来被动监听，而不是主动建链。一般情况下两者没有区别，除非nodename为NULL：对于主动建链来说，一个为NULL的nodename意味着本地地址（127.0.0.1或::1），而对于被动监听来说，一个为NULL的nodename意味着ANY（0.0.0.0或::0）.
EVUTIL_AI_CANONNAME：如果设置了该标志，则会尝试在ai_canonname字段报告主机的规范名称。
EVUTIL_AI_NUMERICHOST：如果设置了该标志，则仅会解析数字型的IPv4以及IPv6地址；如果nodename是一个需要解析的域名的话，则该函数会返回EVUTIL_EAI_NONAME错误。
EVUTIL_AI_NUMERICSERV：如果设置了该标志，则仅会解析数字型的服务名，如果servname既不是NULL，也不是十进制整数的话，则返回EVUTIL_EAI_NONAME错误。
EVUTIL_AI_V4MAPPED：该标志表明，如果ai_family为AF_INET6，并且没有发现IPv6地址的话，则会将任一IPv4地址返回为一个v4映射（v4-mapped）的IPv6地址。除非操作系统支持，否则当前的evutil_getaddrinfo不支持该标志。
EVUTIL_AI_ALL：如果将该标志和EVUTIL_AI_V4MAPPED一起设置，则结果集中的IPv4地址都将返回为v4映射的IPv6地址，而不管是否找到了IPV6地址。除非操作系统支持，否则当前的evutil_getaddrinfo不支持该标志。
EVUTIL_AI_ADDRCONFIG：设置了该标志，则只有在系统具有非本地IPV4地址的时候，结果集中才包含IPv4地址，并且只有在系统具有非本地的IPv6地址的时候，结果集中才包含IPv6地址。
hints中的ai_family字段用来告知evutil_getaddrinfo返回何种地址类型。设置为AF_INET，则仅返回IPv4地址，置为AF_INET6，则仅返回IPv6地址，置为AF_UNSPEC，则返回所有可能的地址。
hints中的ai_socktype和ai_protocol字段用来告知evutil_getaddrinfo如何使用这些地址。他们类似于传递给socket函数的socktype和protocol参数。
如果evutil_getaddrinfo执行成功，则返回一个evutil_addrinfo结构的链表res，每个结构中的ai_next指针指向下一个结构。这种链表是在堆中分配的，所以需要使用evutil_freeaddrinfo函数进行释放。
如果该函数执行失败，则返回下列数字错误码：
EVUTIL_EAI_ADDRFAMILY：请求的地址族对于nodename来说没有意义。
EVUTIL_EAI_AGAIN：在域名解析过程中发生了可恢复的错误，可以过后再次尝试。
EVUTIL_EAI_FAIL：域名解析过程中发生了不可恢复的错误，DNS服务器或者解析器可能已经崩溃了。
EVUTIL_EAI_BADFLAGS：hints中的ai_flags无效。
EVUTIL_EAI_FAMILY：不支持hints中的ai_family字段。
EVUTIL_EAI_MEMORY：解析过程中内存不足。
EVUTIL_EAI_NODATA：请求的主机虽然存在，但是却没有地址信息（或者对于请求的类型，没有相应的地址信息。）
EVUTIL_EAI_NONAME：请求的主机不存在。
EVUTIL_EAI_SERVICE：请求的服务不存在。
EVUTIL_EAI_SOCKTYPE：不支持请求的socket类型，或者它与ai_protocol不匹配。
EVUTIL_EAI_SYSTEM：域名解析过程中发生了其他系统错误，可以通过查看errno获得更多信息。
EVUTIL_EAI_CANCEL：DNS请求过程应该在完成之前被取消。evutil_getaddrinfo从不返回该错误，但是在下面介绍的evdns_getaddrinfo中可能会返回该错误。
可以通过evutil_gai_strerror函数，将这些错误码转换为一个可读的字符串信息。
注意：如果操作系统定义了addrinfo结构，则evutil_addrinfo结构仅仅是操作系统内部结构的别名。类似的，如果操作系统定义了任何AI_*标志，则相应的EVUTIL_AI_*标志也是他们的别名；如果操作系统定义了EAI_*错误，则相应的EVUTIL_EAI_*错误码等价于原始错误码。
#include <event2/util.h>
#include <sys/socket.h>
#include <sys/types.h>
#include <stdio.h>
#include <string.h>
#include <assert.h>
#include <unistd.h>
evutil_socket_t get_tcp_socket_for_host(const char *hostname, ev_uint16_t port)
{
char port_buf[6];
struct evutil_addrinfo hints;
struct evutil_addrinfo *answer = NULL;
int err;
evutil_socket_t sock;
/* Convert the port to decimal. */
evutil_snprintf(port_buf, sizeof(port_buf), "%d", (int)port);
/* Build the hints to tell getaddrinfo howto act. */
memset(&hints, 0, sizeof(hints));
hints.ai_family = AF_UNSPEC; /* v4 or v6 isfine. */
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP; /* We wanta TCP socket */
/* Only return addresses we can use. */
hints.ai_flags = EVUTIL_AI_ADDRCONFIG;
/* Look up the hostname. */
err =evutil_getaddrinfo(hostname, port_buf, &hints, &answer);
if (err != 0) {
fprintf(stderr, "Error whileresolving '%s': %s",
hostname, evutil_gai_strerror(err));
return -1;
}
/* If there was no error, we should have atleast one answer. */
assert(answer);
/* Just use the first answer. */
sock = socket(answer->ai_family,
answer->ai_socktype,
answer->ai_protocol);
if (sock < 0)
return -1;
if (connect(sock, answer->ai_addr, answer->ai_addrlen)) {
/* Note that we're doing a blockingconnect in this function.
* If this were nonblocking, we'd need to treatsome errors
* (like EINTR and EAGAIN) specially.*/
EVUTIL_CLOSESOCKET(sock);
return -1;
}
return sock;
}
这些函数都在event2/util.h中定义。
二：使用evdns_getaddrinfo进行非阻塞的域名解析
常规的getaddrinfo接口，以及上面的evutil_getaddrinfo接口的一个主要问题，就是它们是阻塞的：当调用他们时，调用线程只能在请求DNS服务器时等待其返回结果。使用Libevent时，这种方式并不是合适的处理方式。
所以，Libevent提供了一系列函数来进行非阻塞的DNS请求，并使用Libevent机制等待服务器返回结果。
typedef void (*evdns_getaddrinfo_cb)(
int result, struct evutil_addrinfo *res, void *arg);
struct evdns_getaddrinfo_request;
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);
void evdns_getaddrinfo_cancel(struct evdns_getaddrinfo_request *req);
evdns_getaddrinfo函数类似于evutil_getaddrinfo，除了它在请求DNS服务器时不阻塞，它使用Libevent的底层DNS功能来进行域名解析。因为可能无法立即返回结果，因此需要提供一个evdns_getaddrinfo_cb类型的回调函数，并提供一个该回调函数的可选的用户提供的参数。
另外，需要提供给evdns_getaddrinfo函数一个指向evdns_base的指针。该结构保存DNS解析器的状态和配置。详细信息参见下一节。
如果evdns_getaddrinfo函数即刻成功，或者即刻失败，则其返回NULL。否则，它返回一个指向evdns_getaddrinfo_request结构的指针，可以使用该指针，调用evdns_getaddrinfo_cancel函数，在请求结束前的任意时刻取消DNS请求。
注意，不管evdns_getaddrinfo函数返回NULL与否，也不管evdns_getaddrinfo_cancel是否调用，回调函数终将都会被调用。
调用evdns_getaddrinfo函数时，对于nodename，servname以及hints参数，它都有自己的内部拷贝：在名称查找的过程中，无需保证他们一直存在。
#include <event2/dns.h>
#include <event2/util.h>
#include <event2/event.h>
#include <sys/socket.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
int n_pending_requests = 0;
struct event_base *base = NULL;
struct user_data {
char *name; /* the name we're resolving */
int idx;/* its position on the command line */
};
void callback(int errcode, struct evutil_addrinfo *addr, void *ptr)
{
struct user_data *data = ptr;
const char *name= data->name;
if (errcode) {
printf("%d. %s -> %s ", data->idx, name, evutil_gai_strerror(errcode));
} else {
struct evutil_addrinfo *ai;
printf("%d. %s",data->idx, name);
if (addr->ai_canonname)
printf(" [%s]",addr->ai_canonname);
puts("");
for (ai = addr; ai; ai= ai->ai_next) {
char buf[128];
const char *s= NULL;
if (ai->ai_family == AF_INET) {
struct sockaddr_in *sin = (struct sockaddr_in *)ai->ai_addr;
s = evutil_inet_ntop(AF_INET, &sin->sin_addr, buf, 128);
} else if (ai->ai_family ==AF_INET6) {
struct sockaddr_in6 *sin6 = (struct sockaddr_in6 *)ai->ai_addr;
s = evutil_inet_ntop(AF_INET6, &sin6->sin6_addr, buf, 128);
}
if (s)
printf(" -> %s ", s);
}
evutil_freeaddrinfo(addr);
}
free(data->name);
free(data);
if (--n_pending_requests == 0)
event_base_loopexit(base, NULL);
}
/* Take a list of domain namesfrom the command line and resolve them in
* parallel. */
int main(int argc, char **argv)
{
int i;
struct evdns_base *dnsbase;
if (argc == 1) {
puts("No addresses given.");
return 0;
}
base = event_base_new();
if (!base)
return 1;
dnsbase = evdns_base_new(base, 1);
if (!dnsbase)
return 2;
for (i = 1; i < argc; ++i) {
struct evutil_addrinfo hints;
struct evdns_getaddrinfo_request *req;
struct user_data *user_data;
memset(&hints, 0, sizeof(hints));
hints.ai_family = AF_UNSPEC;
hints.ai_flags = EVUTIL_AI_CANONNAME;
/* Unless we specify a socktype, we'llget at least two entries for
* each address: one for TCP and onefor UDP. That's not what we
* want. */
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
if (!(user_data = malloc(sizeof(struct user_data)))) {
perror("malloc");
exit(1);
}
if (!(user_data->name =strdup(argv[i]))) {
perror("strdup");
exit(1);
}
user_data->idx = i;
++n_pending_requests;
req = evdns_getaddrinfo(
dnsbase, argv[i], NULL /* no service name given */,
&hints, callback, user_data);
if (req == NULL) {
printf(" [request for %s returnedimmediately] ", argv[i]);
/* No need to free user_data ordecrement n_pending_requests; that
* happened in the callback. */
}
}
if (n_pending_requests)
event_base_dispatch(base);
evdns_base_free(dnsbase, 0);
event_base_free(base);
return 0;
}
这些函数在event2/dns.h中声明。
三：创建并配置evdns_base
在使用evdns进行非阻塞的DNS解析之前，需要对evdns_base进行配置。每一个evdns_base保存一个域名服务器的列表，以及DNS配置选项，它对正在进行的DNS请求进行跟踪。
struct evdns_base *evdns_base_new(struct event_base *event_base,
int nitialize);
void evdns_base_free(struct evdns_base *base, int fail_requests);
evdns_base_new函数成功时返回一个新的evdns_base结构，失败时返回NULL。如果参数initialize为1，则该函数会根据操作系统的默认值合理的配置evdns_base。如果该参数为0，则会将evdns_base置空，不包含任何域名服务器以及配置选项。
当不再需要evdns_base的时候，可以使用evdns_base_free将其释放。如果其fail_requests参数为真，则在释放base之前，会使所有进行中的请求以错误码EVUTIL_EAI_CANCEL来调用他们的回调函数。
1：根据系统配置初始化evdns
如果需要对evdns_base如何初始化进行更多的控制，可以将initialize参数设置为0调用evdns_base_new，并调用下列函数：
#define DNS_OPTION_SEARCH 1
#define DNS_OPTION_NAMESERVERS 2
#define DNS_OPTION_MISC 4
#define DNS_OPTION_HOSTSFILE 8
#define DNS_OPTIONS_ALL 15
int evdns_base_resolv_conf_parse(struct evdns_base *base, int flags,
const char *filename);
#ifdef WIN32
int evdns_base_config_windows_nameservers(struct evdns_base *);
#define EVDNS_BASE_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
#endif
evdns_base_resolv_conf_parse函数将会扫描resolv.conf格式的文件filename，并从该文件中读取flags中列出的选项。（关于resolv.conf文件的更多信息，可以参考本地的Unix操作手册）
DNS_OPTION_SEARCH：使evdns从resolv.conf文件中读取domain和search字段以及ndots选项，并且根据这些字段决定用哪一个domain（如果有的话）来搜索不是全限定的主机名。
DNS_OPTION_NAMESERVERS：该标志使evdns从resolv.conf文件中获取域名服务器。
DNS_OPTION_MISC：该标志使evdns从resolv.conf文件中获取其他配置选项。
DNS_OPTION_HOSTSFILE：该标志使evdns从/etc/hosts中读取主机列表，作为加载resolv.conf文件的一部分。
DNS_OPTIONS_ALL：使evdns从resolv.conf文件中获取尽可能多的选项。
在Windows上，因为没有resolv.conf文件指示域名服务器在哪，可以使用evdns_base_config_windows_nameservers函数从注册表（或者NetworkParams，或者其他地方）中读取所有的域名服务器。
2：resolv.conf文件格式
resolv.conf格式的文件是一个文本文件，每一行要么是空行，要么是以“#”开头的注释，要么是包含若干参数的关键字。支持的关键字如下：
nameserver：后面跟着一个域名服务器的IP地址。作为扩展，Libevent允许为域名服务器指定一个非标准的端口，使用IP:Port或者[IPv6]:port这种格式。
domain：本地域名
search：在解析本地主机名时，需要搜索的名字列表。包含少于ndots个点的名字会被认为是本地的，而且如果不能正确解析的话，则会在这些域名中进行查找。比如，如果search为example.com，并且ndots为1的话，如果用户需要解析www，则会将其当做www.example.com。
options：一些以空格分割的选项。每一个选项要么是一个空字符串，要么是option:value格式。支持下列options：
ndots:INTEGER，用来配置search，参照上面“search”，默认值为1.
timeout:FLOAT，在请求DNS服务器时，等待的超时时间，以秒数为单位。默认为5秒。
max-timeouts:INT，DNS服务器超时几次才认为DNS服务器宕机，默认为3次。
max-inflight:INT：最多允许多少个未决的DNS请求（如果请求数过多，则多余的请求会阻塞，直到先前的请求应答了或者超时了），默认为64.
attempts:INT，放弃之前，尝试发送DNS请求的次数，默认为3.
randomize-case:INT，如果非零，evdns会为发出的DNS请求设置随机的事务ID，并且确认回应具有同样的随机事务ID值。这种称作“0x20 hack”的机制可以在一定程度上阻止对DNS的简单激活事件攻击。这个选项的默认值是1。（存疑）
bind-to:ADDRESS，如果提供了该选项，则在发送请求到域名服务器时，会绑定到给定的地址。对于Libevent2.0.4-alpha版本，该选项只应用在后面的域名服务器选项上。
initial-probe-timeout:FLOAT，当发现一个域名服务器down掉时，以指数抵减的频率探测其是否启动。该选项配置一系列超时时间的第一个超时时间，以秒为单位，默认为10。
getaddrinfo-allow-skew:FLOAT，当evdns_getaddrinfo同时请求IPv4地址以及IPv6地址时，它会在分离的DNS请求报文中进行，因为一些服务器无法在一个包中同时处理两种请求。一旦它对于一种地址类型有了回应，它会等待一段时间看另一个答案是否已经到达。该选项配置这段时间的长度，以秒为单位，默认为3秒。
不识别的符号和选项都会被忽略。
3：手动配置evdns
如果需要更加细粒度的控制evdns的行为，可以使用下列函数：
int evdns_base_nameserver_sockaddr_add(struct evdns_base *base,
const struct sockaddr *sa, ev_socklen_t len,
unsigned flags);
int evdns_base_nameserver_ip_add(struct evdns_base *base,
const char *ip_as_string);
int evdns_base_load_hosts(struct evdns_base *base, const char *hosts_fname);
void evdns_base_search_clear(struct evdns_base *base);
void evdns_base_search_add(struct evdns_base *base, const char *domain);
void evdns_base_search_ndots_set(struct evdns_base *base, int ndots);
int evdns_base_set_option(struct evdns_base *base, const char *option,
const char *val);
int evdns_base_count_nameservers(struct evdns_base *base);
evdns_base_nameserver_sockaddr_add函数通过socket地址的形式，向evdns_base添加一个域名服务器。flags参数目前是被忽略的，而且为了向前兼容性应该置为0。该函数成功是返回0，失败时返回负数。
evdns_base_nameserver_ip_add函数也是向evdns_base添加域名服务器。不过它是以字符串的形式添加，该字符串可以是一个IPv4地址，一个IPv6地址，一个有端口号的IPv4地址（IPv4:Port），或者一个有端口号的IPv6地址（[IPv6]：port）。该函数成功时返回0，失败时返回负数。
evdns_base_load_hosts函数从hosts_name中加载一个主机文件（类似于/etc/hosts的格式）。该函数成功时返回0，失败时返回负数。
evdns_base_search_clear函数从evdns_base中清除所有当前的search后缀（就像search选项中配置的那样）；evdns_base_search_add函数则增加一个后缀。
evdns_base_set_option函数向evdns_base添加一个选项key和该选项的值value，key和value都是字符串的形式。（2.0.3版本之前，选项名后面必须有一个冒号）
解析一系列的配置文件之后，如果希望看到是否已经添加了域名服务器，可以使用evdns_base_count_nameservers查看有多少个域名服务器。
4：库端的配置
Libevent提供了一对函数可以对evdns模块进行库级别的设置：
typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
void evdns_set_log_fn(evdns_debug_log_fn_type fn);
void evdns_set_transaction_id_fn(ev_uint16_t (*fn)(void));
由于历史的原因，evdns子系统具有其自己独立的日志功能；可以使用evdns_set_log_fn函数添加回调函数，对消息进行处理。
出于安全性的考虑，evdns需要一个好的随机数源：在使用“0x20 hack”时，它被用来获取难以被猜中的事务ID，从而用来随机化查询（参考“randomize-case”选项）。然而老版本的Libevent，并没有提供一个安全的RNG。可以通过调用evdns_set_transaction_id_fn ，并向其提供一个能够返回难以预测的2字节无符号整数的函数，来为evdns设置一个更好的随机数产生器
在Libevent2.0.4-alpha及其之后的版本，Libevent使用自己的内部的安全RNG；所以evdns_set_transaction_id_fn函数不在起作用。
四：底层DNS接口
有时需要以比evdns_getaddrinfo能更加细粒度的控制进行特别的DNS请求。Libevent提供了相应的接口。
1：缺少的特性：
目前，Libevent的DNS缺少一些其他底层DNS系统所能提供的特性，比如对于任意请求类型和TCP请求的支持。如果需要那些evdns所不支持的特性，希望您能够贡献一个补丁。或者也可以考虑更加全能的DNS库比如c-ares。
#define DNS_QUERY_NO_SEARCH /* ... */
#define DNS_IPv4_A /* ... */
#define DNS_PTR /* ... */
#define DNS_IPv6_AAAA /* ... */
typedef void (*evdns_callback_type)(int result, char type, int count,
int ttl, void *addresses, void *arg);
struct evdns_request *evdns_base_resolve_ipv4(struct evdns_base *base,
const char *name, int flags, evdns_callback_type callback, void *ptr);
struct evdns_request *evdns_base_resolve_ipv6(struct evdns_base *base,
const char *name, int flags, evdns_callback_type callback, void *ptr);
struct evdns_request *evdns_base_resolve_reverse(struct evdns_base *base,
const struct in_addr *in, int flags, evdns_callback_type callback,
void *ptr);
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);
这些解析函数为一个特殊的记录发起DNS请求。每一个函数都使用evdns_base来进行请求，函数参数还包括需要查询的源（既可以是正向查找时的主机名，也可以是反向查找时的一个地址），一系列决定如何进行查找的标志集合，当查找结束时调用的回调函数，以及一个用户提供的传递给回调函数的参数的指针。
flags参数可以是0，或者是DNS_QUERY_NO_SEARCH ，DNS_QUERY_NO_SEARCH 表示在原始搜索失败的时候，明确禁止在search列表中进行搜索。DNS_QUERY_NO_SEARCH 标志对于反向查询没有意义，因为反向查询不会进行搜索。
当请求完成时（成功或失败），就会调用回调函数。回调函数的参数有：result表明成功或者是一个错误码（参看下面的DNS错误码），一个记录类型（DNS_IPv4_A，DNS_IPv6_AAAA或 DNS_PTR之一），addresses是记录的个数，ttl秒数，地址本身以及用户提供的参数指针。
如果发生了错误，则回调函数的addresses参数为NULL。如果没有发生错误，对于PTR记录来说，它是一个NULL结尾的字符串。对于IPv4记录来说，它是一个网络字节序的4字节的数组。对于IPv6来说，则是一个网络字节序的16字节数组。（注意，即使没有错误，addresses的数量也可以是0。比如名字存在，但是却没有请求类型的记录）
可以传递给回调函数的错误码如下：
|
错误码 |
意义 |
|
DNS_ERR_NONE |
没有错误发生 |
|
DNS_ERR_FORMAT |
服务器无法理解该请求 |
|
DNS_ERR_SERVERFAILED |
服务器发生了内部错误 |
|
DNS_ERR_NOTEXIST |
对于给定的name，没有record |
|
DNS_ERR_NOTIMPL |
服务器无法理解该类型的请求 |
|
DNS_ERR_REFUSED |
因策略设置，服务器决绝该请求 |
|
DNS_ERR_TRUNCATED |
DNS 记录不适合UDP报文 |
|
DNS_ERR_UNKNOWN |
未知的内部错误 |
|
DNS_ERR_TIMEOUT |
请求超时 |
|
DNS_ERR_SHUTDOWN |
用户要求关闭evdns系统 |
|
DNS_ERR_CANCEL |
用户要求取消这次请求 |
|
DNS_ERR_NODATA |
虽然收到了响应，但是其中却没有包含答案 |
可以使用下面的接口将错误码转换为可读的字符串：
const char *evdns_err_to_string(int err);
每一个解析函数都返回一个不透明的evdns_request结构，可以使用该结构，在回调函数调用之前的任一时刻取消请求：
void evdns_cancel_request(struct evdns_base *base, struct evdns_request *req);
使用该函数取消一个请求，会使得回调函数以DNS_ERR_CANCEL为结果码被调用。
五：挂起DNS客户端操作、改变域名服务器
有时希望能够在不太影响正在进行的DNS请求的情况下，对DNS子系统重新配置或者关闭。
int evdns_base_clear_nameservers_and_suspend(struct evdns_base *base);
int evdns_base_resume(struct evdns_base *base);
如果在evdns_base上调用函数evdns_base_clear_nameservers_and_suspend，则所有的域名服务器都会被删除，并且未决的请求会被保留，直到重新添加域名服务器并且调用evdns_name_resume为止。
这些函数成功时返回0，失败时返回-1。
六：DNS服务器接口
Libevent提供了简单的功能实现一个普通的DNS服务器，并且对UDP的DNS请求进行应答。本节的内容需要你熟悉一些DNS协议。
1：创建和关闭DNS服务器
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);
typedef void (*evdns_request_callback_fn_type)(
struct evdns_server_request *request,
void *user_data);
void evdns_close_server_port(struct evdns_server_port *port);
调用evdns_add_server_port_with_base开始监听DNS请求。该函数的参数有：一个处理事件的event_base，一个用来监听的UDP socket，flags变量（目前总是为0）；当收到新的DNS请求时调用的回调函数；一个用户提供的回调函数的参数指针。该函数返回一个新的evdns_server_port对象。
当DNS 服务器的工作完成时，可以将该对象传递给evdns_close_server_port函数进行关闭。
2：检测DNS请求
不幸的是，Libevent目前没有为通过可编程的接口来获取DNS请求提供一个很好的方式。相反的，需要包含event2/dns_struct.h，并且手动检测evdns_server_quest结构。
将来版本的Libevent如果能提供一个更好的操作方式的话就好了。
struct evdns_server_request {
int flags;
int nquestions;
struct evdns_server_question **questions;
};
#define EVDNS_QTYPE_AXFR 252
#define EVDNS_QTYPE_ALL 255
struct evdns_server_question {
int type;
int dns_question_class;
char name[1];
};
请求的flags字段包含了请求中设置的DNS标志；nquestions是请求中包含的问题数；questions是指向结构体evdns_server_question的指针数组。每一个evdns_server_question都包含了请求的资源类型（参考下面的EVDNS_*_TYPE宏），请求的类型（典型的是EVDNS_CLASS_INET）以及请求主机名的名称。
int evdns_server_request_get_requesting_addr(struct evdns_server_request *req,
struct sockaddr *sa, int addr_len);
有时需要知道某特定的DNS请求来自何方。可以通过调用函数evdns_server_request_get_requestion_addr函数来获得。需要传递一个足够大小的sockaddr来保存地址：建议使用sockaddr_storage结构。
3：响应DNS请求
DNS服务器每收到一个请求，都会将该请求，连同用户提供的指针，一起传递到回调函数中。该回调函数必须要么能响应请求或者忽略请求，要么保证该请求最终会被应答或者忽略。
在应答请求之前，可以向应答中添加一个或多个答案：
int evdns_server_request_add_a_reply(struct evdns_server_request *req,
const char *name, int n, const void *addrs, int ttl);
int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req,
const char *name, int n, const void *addrs, int ttl);
int evdns_server_request_add_cname_reply(struct evdns_server_request *req,
const char *name, const char *cname, int ttl);
上述函数会添加一个单独的RR（A，AAAA类型或者CNAME）到req请求的应答中。每个函数中，参数name就是要添加到答案中的主机名，ttl就是答案中的生存时间秒数。对于A以及AAAA记录来说，n就是需要添加的地址个数，addrs是指向原始地址的指针，它要么是在A记录中的4字节的IPv4地址，要么是AAAA记录中的16字节的IPv6地址。
这些函数成功时返回0，失败时返回-1。
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);
该函数向请求的应答中添加一个PTR记录。req和ttl参数类似于上面的参数。必须以一个in（IPv4地址）或者inaddr_name（在.arpa域中的地址）表明要应答的那个地址。hostname参数就是PTR查询的答案。
#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_CLASS_INET 1
int evdns_server_request_add_reply(struc tevdns_server_request *req,
int section, const char *name, int type, int dns_class, int ttl,
int datalen, int is_name, const char *data);
该函数向req请求的DNS应答添加任意的RR。section参数表明需要添加哪一部分，而且该值必须是EVDNS_*_SECTION的其中之一。name参数是RR中的name字段。type参数是RR中的type字段，而且可能的话应该是EVDNS_TYPE_*的其中之一。dns_class参数是RR中的class字段，而且一般应该是EVDNS_CLASS_INET。ttl参数是RR中的存活时间字段。RR中的rdata和rdlength字段将会由data中的datalen个字节产生。如果is_name为true，则data将会编码为一个DNS名，否则，它将按照字面意思包含到RR中。
int evdns_server_request_respond(struct evdns_server_request *req, int err);
int evdns_server_request_drop(struct evdns_server_request *req);
evdns_server_request_respond函数发送一个DNS回应，包含所有RRs，以及错误码err。如果收到一个不想应答的请求，可以通过调用evdns_server_request_drop函数忽略它，从而可以释放所有相关内存以及记录结构。
#define EVDNS_FLAGS_AA 0x400
#define EVDNS_FLAGS_RD 0x080
void evdns_server_request_set_flags(struct evdns_server_request *req, int flags);
如果需要在应答消息中设置任何标志，可以在发送应答之前的任意时间调用该函数。
4：DNS服务器例子
#include <event2/dns.h>
#include<event2/dns_struct.h>
#include <event2/util.h>
#include <event2/event.h>
#include <sys/socket.h>
#include <stdio.h>
#include <string.h>
#include <assert.h>
/* Let's try binding to5353. Port 53 is more traditional, buton most
operating systems it requires rootprivileges. */
#define LISTEN_PORT 5353
#define LOCALHOST_IPV4_ARPA"1.0.0.127.in-addr.arpa"
#define LOCALHOST_IPV6_ARPA("1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0."
"0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa")
const ev_uint8_tLOCALHOST_IPV4[] = { 127, 0, 0, 1 };
const ev_uint8_tLOCALHOST_IPV6[] = { 0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,1 };
#define TTL 4242
/* This toy DNS server callbackanswers requests for localhost (mapping it to
127.0.0.1 or ::1) and for 127.0.0.1 or ::1(mapping them to localhost).
*/
void server_callback(structevdns_server_request *request, void *data)
{
int i;
int error=DNS_ERR_NONE;
/* We should try to answer all thequestions. Some DNS servers don't do
this reliably, though, so you shouldthink hard before putting two
questions in one request yourself. */
for (i=0; i < request->nquestions;++i) {
const struct evdns_server_question *q =request->questions[i];
int ok=-1;
/* We don't use regular strcasecmphere, since we want a locale-
independent comparison. */
if (0 ==evutil_ascii_strcasecmp(q->name, "localhost")) {
if (q->type == EVDNS_TYPE_A)
ok =evdns_server_request_add_a_reply(
request, q->name, 1,LOCALHOST_IPV4, TTL);
else if (q->type ==EVDNS_TYPE_AAAA)
ok =evdns_server_request_add_aaaa_reply(
request, q->name, 1,LOCALHOST_IPV6, TTL);
} else if (0 ==evutil_ascii_strcasecmp(q->name, LOCALHOST_IPV4_ARPA)) {
if (q->type == EVDNS_TYPE_PTR)
ok =evdns_server_request_add_ptr_reply(
request, NULL,q->name, "LOCALHOST", TTL);
} else if (0 ==evutil_ascii_strcasecmp(q->name, LOCALHOST_IPV6_ARPA)) {
if (q->type == EVDNS_TYPE_PTR)
ok =evdns_server_request_add_ptr_reply(
request, NULL,q->name, "LOCALHOST", TTL);
} else {
error = DNS_ERR_NOTEXIST;
}
if (ok<0 &&error==DNS_ERR_NONE)
error = DNS_ERR_SERVERFAILED;
}
/* Now send the reply. */
evdns_server_request_respond(request,error);
}
int main(int argc, char **argv)
{
struct event_base *base;
struct evdns_server_port *server;
evutil_socket_t server_fd;
struct sockaddr_in listenaddr;
base = event_base_new();
if (!base)
return 1;
server_fd = socket(AF_INET, SOCK_DGRAM, 0);
if (server_fd < 0)
return 2;
memset(&listenaddr, 0, sizeof(listenaddr));
listenaddr.sin_family = AF_INET;
listenaddr.sin_port = htons(LISTEN_PORT);
listenaddr.sin_addr.s_addr = INADDR_ANY;
if (bind(server_fd, (structsockaddr*)&listenaddr, sizeof(listenaddr))<0)
return 3;
server = evdns_add_server_port_with_base(base,server_fd, 0,
server_callback, NULL);
event_base_dispatch(base);
evdns_close_server_port(server);
event_base_free(base);
return 0;
}
七：废弃的DNS接口
void evdns_base_search_ndots_set(struct evdns_base *base, const int ndots);
int evdns_base_nameserver_add(struct evdns_base *base,
unsigned long int address);
void evdns_set_random_bytes_fn(void (*fn)(char *, size_t));
struct evdns_server_port *evdns_add_server_port(evutil_socket_t socket,
int flags, evdns_request_callback_fn_type callback, void *user_data);
调用evdns_base_search_ndots_set函数等价于以ndots选项调用函数evdns_base_set_option。
函数evdns_base_nameserver_add类似于evdns_base_nameserver_ip_add，除了它只能添加IPv4地址的域名服务器。IPv4地址是网络字节序的4字节数组。
在Libevent2.0.1-alpha之前，无法为一个DNS服务器指定一个event base，只能使用evdns_add_server_port函数，它使用默认的event_base。
在 Libevent2.0.1-alpha到2.0.3-alpha之间，需要使用evdns_set_random_bytes_fn函数来指定一个产生随机数的函数，而不是使用evdns_set_transaction_id_fn。目前它不再有任何作用，现在Libevent有了自己的安全的RNG。
DNS_QUERY_NO_SEARCH标志也被称为DNS_NO_SEARCH。
在Libevent2.0.1-alpha之前，没有单独的evdns_base记号：所有evdns子系统中的信息都是全局存储的，而且操作它的函数没有evdns_base参数。这些函数全都是已经废弃了，他们在event2/dns_compat.h中声明。他们通过一个全局的evdns_base来实现；可以通过调用Libevent 2.0.3-alpha引进的函数evdns_get_global_base来访问该evdns_base。
|
Current function |
Obsolete global-evdns_base version |
|
event_base_new() |
evdns_init() |
|
evdns_base_free() |
evdns_shutdown() |
|
evdns_base_nameserver_add() |
evdns_nameserver_add() |
|
evdns_base_count_nameservers() |
evdns_count_nameservers() |
|
evdns_base_clear_nameservers_and_suspend() |
evdns_clear_nameservers_and_suspend() |
|
evdns_base_resume() |
evdns_resume() |
|
evdns_base_nameserver_ip_add() |
evdns_nameserver_ip_add() |
|
evdns_base_resolve_ipv4() |
evdns_resolve_ipv4() |
|
evdns_base_resolve_ipv6() |
evdns_resolve_ipv6() |
|
evdns_base_resolve_reverse() |
evdns_resolve_reverse() |
|
evdns_base_resolve_reverse_ipv6() |
evdns_resolve_reverse_ipv6() |
|
evdns_base_set_option() |
evdns_set_option() |
|
evdns_base_resolv_conf_parse() |
evdns_resolv_conf_parse() |
|
evdns_base_search_clear() |
evdns_search_clear() |
|
evdns_base_search_add() |
evdns_search_add() |
|
evdns_base_search_ndots_set() |
evdns_search_ndots_set() |
|
evdns_base_config_windows_nameservers() |
evdns_config_windows_nameservers() |
当且仅当存在evdns_config_windows_nameservers()函数时，EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED宏才被定义。
原文：http://www.wangafu.net/~nickm/libevent-book/Ref9_dns.html