DNS with libevent: high-level and low-level functionality

libevent提供了少量用于解析DNS名字的API，以及用于实现简单DNS服务器的机制。
我们从用于名字查询的高层机制开始介绍，然后介绍底层机制和服务器机制。

Portable blocking name resolution

为移植已经使用阻塞式名字解析的程序，libevent提供了标准getaddrinfo()接口的可移植实现。对于需要运行在没有getaddrinfo(）函数，或者getaddrinfo()不像我们的替代函数那样遵循标准的平台上的程序，这个替代实现很有用。

getaddrinfo()接口由RFC 中定义。关于libevent如何不满足其一致性实现的概述，请看下面的“兼容性提示”节。

/* Extension from POSIX.1:2001.  */
#ifdef __USE_XOPEN2K
#define evutil_addrinfo addrinfo
/* Structure to contain information about address of a service provider.  */
struct addrinfo
{int ai_flags;			/* Input flags.  */int ai_family;		/* Protocol family for socket.  */int ai_socktype;		/* Socket type.  */int ai_protocol;		/* Protocol for socket.  */socklen_t ai_addrlen;		/* Length of socket address.  */struct sockaddr *ai_addr;	/* Socket address for socket.  */char *ai_canonname;		/* Canonical name for service location.  */struct addrinfo *ai_next;	/* Pointer to next in list.  */
};

/** @name evutil_getaddrinfo() error codesThese values are possible error codes for evutil_getaddrinfo() andrelated functions.@{
*/
#if defined(EAI_ADDRFAMILY) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_ADDRFAMILY EAI_ADDRFAMILY
#else
#define EVUTIL_EAI_ADDRFAMILY -901
#endif
#if defined(EAI_AGAIN) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_AGAIN EAI_AGAIN
#else
#define EVUTIL_EAI_AGAIN -902
#endif
#if defined(EAI_BADFLAGS) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_BADFLAGS EAI_BADFLAGS
#else
#define EVUTIL_EAI_BADFLAGS -903
#endif
#if defined(EAI_FAIL) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_FAIL EAI_FAIL
#else
#define EVUTIL_EAI_FAIL -904
#endif
#if defined(EAI_FAMILY) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_FAMILY EAI_FAMILY
#else
#define EVUTIL_EAI_FAMILY -905
#endif
#if defined(EAI_MEMORY) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_MEMORY EAI_MEMORY
#else
#define EVUTIL_EAI_MEMORY -906
#endif
/* This test is a bit complicated, since some MS SDKs decide to* remove NODATA or redefine it to be the same as NONAME, in a* fun interpretation of RFC 2553 and RFC 3493. */
#if defined(EAI_NODATA) && defined(EVENT__HAVE_GETADDRINFO) && (!defined(EAI_NONAME) || EAI_NODATA != EAI_NONAME)
#define EVUTIL_EAI_NODATA EAI_NODATA
#else
#define EVUTIL_EAI_NODATA -907
#endif
#if defined(EAI_NONAME) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_NONAME EAI_NONAME
#else
#define EVUTIL_EAI_NONAME -908
#endif
#if defined(EAI_SERVICE) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_SERVICE EAI_SERVICE
#else
#define EVUTIL_EAI_SERVICE -909
#endif
#if defined(EAI_SOCKTYPE) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_SOCKTYPE EAI_SOCKTYPE
#else
#define EVUTIL_EAI_SOCKTYPE -910
#endif
#if defined(EAI_SYSTEM) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_EAI_SYSTEM EAI_SYSTEM
#else
#define EVUTIL_EAI_SYSTEM -911
#endif#define EVUTIL_EAI_CANCEL -90001#if defined(AI_PASSIVE) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_AI_PASSIVE AI_PASSIVE
#else
#define EVUTIL_AI_PASSIVE 0x1000
#endif
#if defined(AI_CANONNAME) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_AI_CANONNAME AI_CANONNAME
#else
#define EVUTIL_AI_CANONNAME 0x2000
#endif
#if defined(AI_NUMERICHOST) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_AI_NUMERICHOST AI_NUMERICHOST
#else
#define EVUTIL_AI_NUMERICHOST 0x4000
#endif
#if defined(AI_NUMERICSERV) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_AI_NUMERICSERV AI_NUMERICSERV
#else
#define EVUTIL_AI_NUMERICSERV 0x8000
#endif
#if defined(AI_V4MAPPED) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_AI_V4MAPPED AI_V4MAPPED
#else
#define EVUTIL_AI_V4MAPPED 0x10000
#endif
#if defined(AI_ALL) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_AI_ALL AI_ALL
#else
#define EVUTIL_AI_ALL 0x20000
#endif
#if defined(AI_ADDRCONFIG) && defined(EVENT__HAVE_GETADDRINFO)
#define EVUTIL_AI_ADDRCONFIG AI_ADDRCONFIG
#else
#define EVUTIL_AI_ADDRCONFIG 0x40000
#endif
/**@}*/

​

int evutil_getaddrinfo(const char *nodename, const char *servname, const struct addrinfo *hints_in, struct addrinfo **res);

voidevutil_freeaddrinfo(struct evutil_addrinfo *ai)
{
#ifdef EVENT__HAVE_GETADDRINFOif (!(ai->ai_flags & EVUTIL_AI_LIBEVENT_ALLOCATED)) {freeaddrinfo(ai);return;}
#endifwhile (ai) {struct evutil_addrinfo *next = ai->ai_next;if (ai->ai_canonname)mm_free(ai->ai_canonname);mm_free(ai);ai = next;}
}

evutil_getaddrinfo()函数试图根据hints给出的规则，解析指定的nodename和servname，建立一个evutil_addrinfo结构体链表，将其存储在*res中。成功时函数返回0，失败时返回非零的错误码。

必须至少提供nodename和servname中的一个。如果提供了nodename，则它是IPv4字面地址（如127.0.0.1）、IPv6字面地(如::1、或者是DNS名字（如www.example.com）。如果提供了servname，则它是某网络服务的符号名（如https），或者是一个包含十进制端口号的字符串（如443）。

如果不指定servname，则res中的端口号将是零。如果不指定nodename，则res中的地址要么是localhost(默认），要么是“任意”（如果设置了EVUTIL_AI_PASSIVE）。

hints的ai_flags字段指示evutil_getaddrinfo如何进行查询，它可以包含0个或者多个以或运算连接的下述标志：

• EVUTIL_AI_PASSIVE

这个标志指示将地址用于监听，而不是连接。通常二者没有差别，除非nodename为空：对于连接，空的nodename表示localhost（127.0.0.1或者::1）；而对于监听，空的nodename表示任意（0.0.0.0或者::0）。

• EVUTIL_AI_CANONNAME

如果设置了这个标志，则函数试图在ai_canonname字段中报告标准名称。

• EVUTIL_AI_NUMERICHOST

如果设置了这个标志，函数仅仅解析数值类型的IPv4和IPv6地址；如果nodename要求名字查询，函数返回EVUTIL_EAI_NONAME错误。

• EVUTIL_AI_NUMERICSERV

如果设置了这个标志，函数仅仅解析数值类型的服务名。如果servname不是空，也不是十进制整数，函数返回EVUTIL_EAI_NONAME错误。

• EVUTIL_AI_V4MAPPED

这个标志表示，如果ai_family是AF_INET6，但是找不到IPv6地址，则应该以v4映射(v4-mapped)型IPv6地址的形式返回结果中的IPv4地址。当前evutil_getaddrinfo()不支持这个标志，除非操作系统支持它。

• EVUTIL_AI_ALL

如果设置了这个标志和EVUTIL_AI_V4MAPPED，则无论结果是否包含IPv6地址，IPv4地址都应该以v4映射型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_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_SERVICE

  请求的服务不存在。

• EVUTIL_EAI_SOCKTYPE

  不支持请求的套接字类型，或者套接字类型与ai_protocol不匹配。

• EVUTIL_EAI_SYSTEM

  名字解析中发生其他系统错误，更多信息请检查errno。

• EVUTIL_EAI_CANCEL

  应用程序在解析完成前请求取消。evutil_getaddrinfo()函数从不产生这个错误，但是后面描述的evdns_getaddrinfo()可能产生这个错误。
  调用evutil_gai_strerror()可以将上述错误值转化成描述性的字符串。

Attention

如果操作系统定义了addrinfo结构体，则evutil_addrinfo仅仅是操作系统内置的addrinfo结构体的别名。类似地，如果操作系统定义了AI_标志，则相应的EVUTIL_AI_标志仅仅是本地标志的别名；如果操作系统定义了EAI_错误，则相应的EVUTIL_EAI_只是本地错误码的别名。

example

#include <event2/util.h>
#include <event2/event.h>#include <sys/socket.h>
#include <netinet/in.h>
#include <sys/types.h>
#include <string.h>
#include <memory.h>#include <assert.h>
#include <unistd.h>/* Set N bytes of S to C.  */
extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull ((1));
evutil_socket_t 
get_tcp_socket_for_host(const char *hostname,ev_uint64_t port){char port_str[6];struct evutil_addrinfo hints;struct evutil_addrinfo *res = nullptr;int err;evutil_socket_t sock;evutil_snprintf(port_str,sizeof(port_str),"%llu",(unsigned long long)port);memset((&hints), 0, sizeof(hints));hints.ai_family = AF_UNSPEC;hints.ai_socktype = SOCK_STREAM;hints.ai_flags = EVUTIL_AI_ADDRCONFIG;hints.ai_protocol = IPPROTO_TCP;err = evutil_getaddrinfo(hostname,port_str,&hints,&res);if(err < 0){return -1;}assert(res);sock = socket(res->ai_family,res->ai_socktype,res->ai_protocol);if(sock < 0){EVUTIL_CLOSESOCKET(sock);return -1;}if(connect(sock,res->ai_addr,res->ai_addrlen) < 0){EVUTIL_CLOSESOCKET(sock);return -1;}return sock;}

上述函数和常量是2.0.3-alpha版本新增加的，声明在event2/util.h中。

Non-blocking name resolution using evdns_getaddrinfo()

通常的getaddrinfo()，以及上面的evutil_getaddrinfo()的问题是，它们是阻塞的：调用线程必须等待函数查询DNS服务器，等待回应。对于libevent，这可能不是期望的行为。

对于非阻塞式应用，libevent提供了一组函数用于启动DNS请求，让libevent等待服务器回应。

/** Callback for evdns_getaddrinfo. */
typedef void (*evdns_getaddrinfo_cb)(int result, struct evutil_addrinfo *res, void *arg);

/* State data used to implement an in-progress getaddrinfo. */
struct evdns_getaddrinfo_request {struct evdns_base *evdns_base;/* Copy of the modified 'hints' data that we'll use to build* answers. */struct evutil_addrinfo hints;/* The callback to invoke when we're done */evdns_getaddrinfo_cb user_cb;/* User-supplied data to give to the callback. */void *user_data;/* The port to use when building sockaddrs. */ev_uint16_t port;/* The sub_request for an A record (if any) */struct getaddrinfo_subrequest ipv4_request;/* The sub_request for an AAAA record (if any) */struct getaddrinfo_subrequest ipv6_request;/* The cname result that we were told (if any) */char *cname_result;/* If we have one request answered and one request still inflight,* then this field holds the answer from the first request... */struct evutil_addrinfo *pending_result;/* And this event is a timeout that will tell us to cancel the second* request if it's taking a long time. */struct event timeout;/* And this field holds the error code from the first request... */int pending_error;/* If this is set, the user canceled this request. */unsigned user_canceled : 1;/* If this is set, the user can no longer cancel this request; we're* just waiting for the free. */unsigned request_done : 1;
};

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 *data)   

除了不会阻塞在DNS查询上，而是使用libevent的底层DNS机制进行查询外，evdns_getaddrinfo()和evutil_getaddrinfo()是一样的。因为函数不是总能立即返回结果，所以需要提供一个evdns_getaddrinfo_cb类型的回调函数，以及一个给回调函数的可选的用户参数。

此外，调用evdns_getaddrinfo()还要求一个evdns_base指针。evdns_base结构体为libevent的DNS解析器保持状态和配置。关于如何获取evdns_base指针，请看下一节。

如果失败或者立即成功，函数返回NULL。否则，函数返回一个evdns_getaddrinfo_request指针。在解析完成之前可以随时使用evdns_getaddrinfo_cancel()和这个指针来取消解析。

注意：不论evdns_getaddrinfo()是否返回NULL，是否调用了evdns_getaddrinfo_cancel()，回调函数总是会被调用。

evdns_getaddrinfo()内部会复制nodename、servname和hints参数，所以查询进行过程中不必保持这些参数有效。

example

使用evdns_getaddrinfo()的非阻塞查询

#include <event2/event.h>
#include <event2/util.h>
#include <event2/dns.h>#include <sys/socket.h>
#include <netinet/in.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 resloving*/int idx;/*its  position on the command line*/
};void callback(int errcode, struct evutil_addrinfo *addr, void *ptr) {// 将指针转换为用户数据结构struct user_data *data = (struct user_data*)ptr;const char *name = data->name;if (errcode) {// 如果出错，打印错误信息printf("%d %s -> %s\n", 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, sizeof(buf));} 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, sizeof(buf));}// 如果成功转换地址，打印它if (s) {printf(" -> %s\n", s);}}// 释放地址信息结构evutil_freeaddrinfo(addr);}// 释放用户数据中的名称和数据结构free(data->name);free(data);// 如果没有待处理请求，退出事件循环if (--n_pending_requests == 0) {event_base_loopexit(base, NULL);}
}int main(int argc, char **argv) {int i ;struct evdns_base *dnsbase;if(argc == 1){puts("No address given");return 0;}base = event_base_new();if(!base){puts("event_base_new failed");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 *data;memset(&hints, 0, sizeof(hints));hints.ai_family = AF_UNSPEC;hints.ai_socktype = SOCK_STREAM;hints.ai_flags = EVUTIL_AI_CANONNAME;hints.ai_protocol = IPPROTO_TCP;if(!(data = (struct user_data*)malloc(sizeof(struct user_data)))){puts("malloc failed");return 3;}if(!(data->name = strdup(argv[i]))){puts("strdup failed");return 4;}data->idx = i;++n_pending_requests;req = evdns_getaddrinfo(dnsbase, argv[i], NULL,&hints, callback,data);if(req == NULL){puts("evdns_getaddrinfo failed");return 5;}}if(n_pending_requests)event_base_dispatch(base);evdns_base_free(dnsbase,0);event_base_free(base);
}

上述函数是2.0.3-alpha版本新增加的，声明在event2/dns.h中。

Create and configure evdns_base

使用evdns进行非阻塞DNS查询之前需要配置一个evdns_base。evdns_base存储名字服务器列表和DNS配置选项.
跟踪活动的、进行中的DNS请求。

struct evdns_base * evdns_base_new(struct event_base *event_base, int flags);
void evdns_base_free(struct evdns_base *base, int fail_requests);

成功时evdns_base_new()返回一个新建的evdns_base，失败时返回NULL。如果initialize参数为true，函数试图根据操作系统的默认值配置evdns_base；否则，函数让evdns_base为空，不配置名字服务器和选项。

可以用evdns_base_free()释放不再使用的evdns_base。如果fail_request参数为true，函数会在释放evdns_base前让所有进行中的请求使用取消错误码调用其回调函数。

Initialize evdns using system configuration

如果需要更多地控制evdns_base如何初始化，可以为evdns_base_new()的initialize参数传递0，然后调用下述函数。

#define DNS_OPTION_HOSTSFILE 1
#define DNS_OPTION_NAMESERVERS 2
#define DNS_OPTION_MISC 4
#define DNS_OPTION_HOSTSFILE 8
#define DNS_OPTIONS_ALL 15int evdns_base_resolv_conf_parse(struct evdns_base *base, int flags, const char *const filename);#ifdef WIN32int evdns_base_resolv_config_windows_namseservers(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

  请求从resolv.conf文件读取domain和search字段以及ndots选项，使用它们来确定使用哪个域（如果存在）来搜索不是全限定的主机名。

• DNS_OPTION_NAMESERVERS

  请求从resolv.conf中读取名字服务器地址。

• DNS_OPTION_MISC

  请求从resolv.conf文件中读取其他配置选项。

• DNS_OPTION_HOSTSFILE

  请求从/etc/hosts文件读取主机列表。

• DNS_OPTION_ALL

  请求从resolv.conf文件获取尽量多的信息。

Windows中没有可以告知名字服务器在哪里的resolv.conf文件，但可以用evdns_base_config_windows_nameservers()函数从注册表（或者NetworkParams，或者其他隐藏的地方）读取名字服务器。

resolv.conf File Format

resolv.conf是一个文本文件，每一行要么是空行，要么包含以#开头的注释，要么由一个跟随零个或者多个参数的标记组成。可以识别的标记有：

• nameserver

  必须后随一个名字服务器的IP地址。作为一个扩展，libevent允许使用IP:Port或者[IPv6]:port语法为名字服务器指定非标准端口。

• domain

本地域名

• search

  解析本地主机名时要搜索的名字列表。如果不能正确解析任何含有少于“ndots”个点的本地名字，则在这些域名中进行搜索。比如说，如果“search”字段值为example.com，“ndots”为1，则用户请求解析“www”时，函数认为那是“www.example.com”。

• options

空格分隔的选项列表。选项要么是空字符串，要么具有格式option:value（如果有参数）。可识别的选项有：
ndots:INTEGER
用于配置搜索，请参考上面的“search”，默认值是1。

 timeout:FLOAT等待DNS服务器响应的时间，单位是秒。默认值为5秒。max-timeouts:INT名字服务器响应超时几次才认为服务器当机？默认是3次。max-inflight:INT最多允许多少个未决的DNS请求？（如果试图发出多于这么多个请求，则过多的请求将被延迟，直到某个请求被响应或者超时）。默认值是XXX。attempts:INT在放弃之前重新传输多少次DNS请求？默认值是XXX。

如果非零，evdns会为发出的DNS请求设置随机的事务ID，并且确认回应具有同样的随机事务ID值。这种称作“0x20 hack”的机制可以在一定程度上阻止对DNS的简单激活事件攻击。这个选项的默认值是1。

（这段原文不易理解，译文可能很不准确。这里给出原文：If nonzero,we randomize the case on outgoing DNS requests and make sure that replies have the same case as our requests.This so-called “0x20 hack” can help prevent some otherwise simple active events against DNS.）

 bind-to:ADDRESS如果提供，则向名字服务器发送数据之前绑定到给出的地址。对于2.0.4-alpha版本，这个设置仅应用于后面的名字服务器条目。initial-probe-timeout:FLOAT确定名字服务器当机后，libevent以指数级降低的频率探测服务器以判断服务器是否恢复。这个选项配置（探测时间间隔）序列中的第一个超时，单位是秒。默认值是10。getaddrinfo-allow-skew:FLOAT同时请求IPv4和IPv6地址时，evdns_getaddrinfo()用单独的DNS请求包分别请求两种地址，因为有些服务器不能在一个包中同时处理两种请求。服务器回应一种地址类型后，函数等待一段时间确定另一种类型的地址是否到达。这个选项配置等待多长时间，单位是秒。默认值是3秒。不识别的字段和选项会被忽略。

Manually configure evdns

如果需要更精细地控制evdns的行为，可以使用下述函数：

int evdns_base_nameserver_sockaddr_add(struct evdns_base *base, const struct sockaddr *sa, socklen_t len,unsigned int 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()函数通过地址向evdns_base添加名字服务器。当前忽略flags参数，为向前兼容考虑，应该传入0。成功时函数返回0，失败时返回负值。（这个函数在2.0.7-rc版本加入）

evdns_base_nameserver_ip_add()函数向evdns_base加入字符串表示的名字服务器，格式可以是IPv4地址、IPv6地址、带端口号的IPv4地址（IPv4:Port)，或者带端口号的IPv6地址（[IPv6]:Port）。成功时函数返回0，失败时返回负值。

evdns_base_load_hosts()函数从hosts_fname文件中载入主机文件（格式与/etc/hosts相同）。成功时函数返回0，失败时返回负值。

evdns_base_search_clear()函数从evdns_base中移除所有（通过search配置的）搜索后缀；evdns_base_search_add()则添加后缀。

evdns_base_set_option()函数设置evdns_base中某选项的值。选项和值都用字符串表示。（2.0.3版本之前，选项名后面必须有一个冒号）

解析一组配置文件后，可以使用evdns_base_count_nameservers()查看添加了多少个名字服务器。

Library configuration

有一些为evdns模块设置库级别配置的函数：

/**A callback that is invoked when a log message is generated@param is_warning indicates if the log message is a 'warning'@param msg the content of the log message*/
typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
void evdns_set_log_fn(evdns_debug_log_fn_type);
void evdns_set_transaction_id_fn(evdns_debug_log_fn_type);

因为历史原因，evdns子系统有自己单独的日志。evdns_set_log_fn()可以设置一个回调函数，以便在丢弃日志消息前做一些操作。

为安全起见，evdns需要一个良好的随机数发生源：使用0x20 hack的时候，evdns通过这个源来获取难以猜测（hard-to-guess）的事务ID以随机化查询（请参考“randomize-case”选项）。然而，较老版本的libevent没有自己的安全的RNG（随机数发生器）。此时可以通过调用evdns_set_transaction_id_fn()，传入一个返回难以预测（hard-to-predict）的两字节无符号整数的函数，来为evdns设置一个更好的随机数发生器。

2.0.4-alpha以及后续版本中，libevent有自己内置的安全的RNG，evdns_set_transaction_id_fn()就没有效果了。

Low-level DNS interface

有时候需要启动能够比从evdns_getaddrinfo()获取的DNS请求进行更精细控制的特别的DNS请求，libevent也为此提供了接口。

Missing features

当前libevent的DNS支持缺少其他底层DNS系统所具有的一些特征，如支持任意请求类型和TCP请求。如果需要evdns所不具有的特征，欢迎贡献一个补丁。也可以看看其他全特征的DNS库，如c-ares。

/*** The callback that contains the results from a lookup.* - result is one of the DNS_ERR_* values (DNS_ERR_NONE for success)* - 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.  It will be an array of*   4-byte sequences for ipv4, or an array of 16-byte sequences for ipv6,*   or a nul-terminated string for PTR.*/
typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);struct evdns_request* evdns_base_resolve_ipv4(evutil_socket_t fd, const char *hostname, evdns_callback_type callback, void *arg);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对反向查询无效，因为反向查询不进行搜索。

请求完成（不论是否成功）时回调函数会被调用。回调函数的参数是指示成功或者错误码（参看下面的DNS错误表）的result、一个记录类型（DNS_IPv4_A、DNS_IPv6_AAAA，或者DNS_PTR）、addresses中的记录数、以秒为单位的存活时间、地址（查询结果），以及用户提供的指针。

发生错误时传给回调函数的addresses参数为NULL。没有错误时：对于PTR记录，addresses是空字符结束的字符串；对于IPv4记录，则是网络字节序的四字节地址值数组；对于IPv6记录，则是网络字节序的16字节记录数组。（注意：即使没有错误，addresses的个数也可能是0。名字存在，但是没有请求类型的记录时就会出现这种情况）

可能传递给回调函数的错误码如下：

DNS ERRORCODE

错误码	意义
DNS_ERR_NONE	没有错误
DNS_ERR_FORMAT	服务器不识别查询请求
DNS_ERR_SERVERFAILED	服务器内部错误
DNS_ERR_NOTEXIST	没有给定名字的记录
DNS_ERR_NOTIMPL	服务器不识别这种类型的查询
DNS_ERR_REFUSED	因为策略设置，服务器拒绝查询
DNS_ERR_TRUNCATED	DNS记录不适合UDP分组
DNS_ERR_UNKNOWN	未知的内部错误
DNS_ERR_TIMEOUT	等待超时
DNS_ERR_SHUTDOWN	用户请求关闭evdns系统
DNS_ERR_CANCEL	用户请求取消查询

可以用下述函数将错误码转换成错误描述字符串

const char *
evdns_err_to_string(int err)
{switch (err) {case DNS_ERR_NONE: return "no error";case DNS_ERR_FORMAT: return "misformatted query";case DNS_ERR_SERVERFAILED: return "server failed";case DNS_ERR_NOTEXIST: return "name does not exist";case DNS_ERR_NOTIMPL: return "query not implemented";case DNS_ERR_REFUSED: return "refused";case DNS_ERR_TRUNCATED: return "reply truncated or ill-formed";case DNS_ERR_UNKNOWN: return "unknown";case DNS_ERR_TIMEOUT: return "request timed out";case DNS_ERR_SHUTDOWN: return "dns subsystem shut down";case DNS_ERR_CANCEL: return "dns request canceled";case DNS_ERR_NODATA: return "no records in the reply";default: return "[Unknown error code]";}
}	

每个解析函数都返回不透明的evdns_request结构体指针。回调函数被调用前的任何时候都可以用这个指针来取消请求：

/* exported function */
void evdns_cancel_request(struct evdns_base *base, struct evdns_request *handle)

Suspend DNS client operation and change name server

有时候需要重新配置或者关闭DNS子系统，但不能影响进行中的DNS请求。

int evdns_base_clear_nameservers_and_suspend(struct evdns_base *base);
int evdns_base_resume(struct evdns_base *base);

evdns_base_clear_nameservers_and_suspend()会移除所有名字服务器，但未决的请求会被保留，直到随后重新添加名字服务器，调用evdns_base_resume()。

这些函数成功时返回0，失败时返回-1。它们在2.0.1-alpha版本引入。

DNS server API

libevent为实现不重要的DNS服务器，响应通过UDP传输的DNS请求提供了简单机制。本章节要求读者对DNS协议有一定的了解。

Create and close DNS server

struct evdns_server_port* evdns_add_server_port_with_base(struct event_base *base, int socket, int flags, evdns_request_callback_fn_type callback, void *user_data);
/**A callback to implement a DNS server.  The callback function receives a DNSrequest.  It should then optionally add a number of answers to the replyusing the evdns_server_request_add_*_reply functions, before calling eitherevdns_server_request_respond to send the reply back, orevdns_server_request_drop to decline to answer the request.@param req A newly received request@param user_data A pointer that was passed toevdns_add_server_port_with_base().*/
typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void * user_data);
void evdns_close_server_port(struct evdns_server_port *port);

要开始监听DNS请求，调用evdns_add_server_port_with_base()。函数要求用于事件处理的event_base、用于监听的UDP套接字、可用的标志（现在总是0）、一个收到DNS查询时要调用的回调函数，以及要传递给回调函数的用户数据指针。函数返回evdns_server_port对象。

使用DNS服务器完成工作后，需要调用evdns_close_server_port()。

evdns_add_server_port_with_base()是2.0.1-alpha版本引入的，而evdns_close_server_port()则由1.3版本引入。

Check DNS request

不幸的是，当前libevent没有提供较好的获取DNS请求的编程接口，用户需要包含event2/dns_struct.h文件，查看evdns_server_request结构体。

未来版本的libevent应该会提供更好的方法。

 /** Structures used to implement a DNS server.*/
struct evdns_server_request {int flags;int nquestions;struct evdns_server_question **questions;
};#define EVDNS_QTYPE_ALL  255;
#define EVDNS_QTYPE_AXFR 252;/** Structures 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;
#ifdef __cplusplusint dns_question_class;
#else/* You should refer to this field as "dns_question_class".  The* name "class" works in C for backward compatibility, and will be* removed in a future version. (1.5 or later). */int class;
#define dns_question_class class
#endifchar name[1];
};#ifdef __cplusplus
}
#endif

flags字段包含请求中设置的DNS标志；nquestions字段是请求中的问题数；questions是evdns_server_question结构体指针数组。每个evdns_server_question包含请求的资源类型（请看下面的EVDNS_*_TYPE宏列表）、请求类别（通常为EVDNS_CLASS_INET），以及请求的主机名。

这些结构体在1.3版本中引入，但是1.4版之前的名字是dns_question_class。名字中的“class”会让C++用户迷惑。仍然使用原来的“class”名字的C程序将不能在未来发布版本中正确工作。

int evdns_server_request_get_requesting_addr(struct evdns_server_request *req, struct sockaddr *sa, int addr_len);

有时候需要知道某特定DNS请求来自何方，这时调用evdns_server_request_get_requesting_add()就可以了。应该传入有足够存储空间以容量地址的sockaddr：建议使用sockaddr_storage结构体。

这个函数在1.3版本中引入。

Response DNS request

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);

上述函数为请求req的DNS回应的结果节添加一个RR（类型分别为A、AAAA和CNAME）。各个函数中，name是要为之添加结果的主机名，ttl是以秒为单位的存活时间。对于A和AAAA记录，n是要添加的地址个数，addrs是到原始地址的指针：对于A记录，是以n4字节序列格式给出的IPv4地址；对于AAAA记录，是以n16字节序列格式给出的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_INET4   1int 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);

这个函数为请求req的DNS回应添加任意RR。section字段指示添加到哪一节，其值应该是某个EVDNS_SECTION。name参数是RR的名字字段。type参数是RR的类型字段，其值应该是某个EVDNS_TYPE。dns_class参数是RR的类别字段。RR的rdata和rdlength字段将从data处的datalen字节中产生。如果is_name为true，data将被编码成DNS名字（例如，使用DNS名字压缩）。否则，data将被直接包含到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回应，带有用户添加的所有RR，以及错误码err。如果不想回应某个请求，可以调用evdns_server_request_drop()来忽略请求，释放请求关联的内存和结构体。

#define EVDNS_FLAGS_AA 0X400
#define EVDNS_FLAGS_RD 0X080void evdns_server_request_set_flags(struct evdns_server_request *req,int flags);

如果要为回应消息设置任何标志，可以在发送回应前的任何时候调用这个函数。

除了evdns_server_request_set_flags()首次在2.0.1-alpha版本中出现外，本节描述的所有函数都在1.3版本中引入。

DNS server example

Obosolote API

void evdns_base_search_ndot_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()等价于使用evdns_base_set_option()设置ndots选项。

除了只能添加IPv4地址的名字服务器外，evdns_base_nameserver_add()函数的行为与evdns_base_nameserver_ip_add()相同。特别的是，evdns_base_nameserver_add()要求网络字节序的四字节地址。

2.0.1-alpha版本之前，不能为DNS服务端口指定event_base。通过evdns_add_server_port()添加的服务端口只能使用默认的event_base。

从版本2.0.1-alpha到2.0.3-alpha，可以使用evdns_set_random_bytes_fn()，而不是evdns_set_transsaction_id_fn()，来指定用于产生随机数的函数。这个函数现在没有效果了，因为libevent有自己的安全的随机数发生器了。

DNS_QUERY_NO_SEARCH标志曾经称作DNS_NO_SEARCH。

2.0.1-alpha版本之前，没有单独的evdns_base记号：evdns子系统中的所有信息都是全局存储的，操作这些信息的函数不需要evdns_base参数。这些函数现在都废弃了，但是还声明在event2/dns_compat.h中。它们通过一个单独的全局evdns_base实现，通过2.0.3-alpha版本引入的evdns_get_global_base()可以访问这个evdns_base。

EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED宏会被定义。
·3313122