dns.h 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643
  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. * The original DNS code is due to Adam Langley with heavy
  29. * modifications by Nick Mathewson. Adam put his DNS software in the
  30. * public domain. You can find his original copyright below. Please,
  31. * aware that the code as part of Libevent is governed by the 3-clause
  32. * BSD license above.
  33. *
  34. * This software is Public Domain. To view a copy of the public domain dedication,
  35. * visit http://creativecommons.org/licenses/publicdomain/ or send a letter to
  36. * Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
  37. *
  38. * I ask and expect, but do not require, that all derivative works contain an
  39. * attribution similar to:
  40. * Parts developed by Adam Langley <agl@imperialviolet.org>
  41. *
  42. * You may wish to replace the word "Parts" with something else depending on
  43. * the amount of original code.
  44. *
  45. * (Derivative works does not include programs which link against, run or include
  46. * the source verbatim in their source distributions)
  47. */
  48. /** @file event2/dns.h
  49. *
  50. * Welcome, gentle reader
  51. *
  52. * Async DNS lookups are really a whole lot harder than they should be,
  53. * mostly stemming from the fact that the libc resolver has never been
  54. * very good at them. Before you use this library you should see if libc
  55. * can do the job for you with the modern async call getaddrinfo_a
  56. * (see http://www.imperialviolet.org/page25.html#e498). Otherwise,
  57. * please continue.
  58. *
  59. * The library keeps track of the state of nameservers and will avoid
  60. * them when they go down. Otherwise it will round robin between them.
  61. *
  62. * Quick start guide:
  63. * #include "evdns.h"
  64. * void callback(int result, char type, int count, int ttl,
  65. * void *addresses, void *arg);
  66. * evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
  67. * evdns_resolve("www.hostname.com", 0, callback, NULL);
  68. *
  69. * When the lookup is complete the callback function is called. The
  70. * first argument will be one of the DNS_ERR_* defines in evdns.h.
  71. * Hopefully it will be DNS_ERR_NONE, in which case type will be
  72. * DNS_IPv4_A, count will be the number of IP addresses, ttl is the time
  73. * which the data can be cached for (in seconds), addresses will point
  74. * to an array of uint32_t's and arg will be whatever you passed to
  75. * evdns_resolve.
  76. *
  77. * Searching:
  78. *
  79. * In order for this library to be a good replacement for glibc's resolver it
  80. * supports searching. This involves setting a list of default domains, in
  81. * which names will be queried for. The number of dots in the query name
  82. * determines the order in which this list is used.
  83. *
  84. * Searching appears to be a single lookup from the point of view of the API,
  85. * although many DNS queries may be generated from a single call to
  86. * evdns_resolve. Searching can also drastically slow down the resolution
  87. * of names.
  88. *
  89. * To disable searching:
  90. * 1. Never set it up. If you never call evdns_resolv_conf_parse or
  91. * evdns_search_add then no searching will occur.
  92. *
  93. * 2. If you do call evdns_resolv_conf_parse then don't pass
  94. * DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it).
  95. *
  96. * 3. When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag.
  97. *
  98. * The order of searches depends on the number of dots in the name. If the
  99. * number is greater than the ndots setting then the names is first tried
  100. * globally. Otherwise each search domain is appended in turn.
  101. *
  102. * The ndots setting can either be set from a resolv.conf, or by calling
  103. * evdns_search_ndots_set.
  104. *
  105. * For example, with ndots set to 1 (the default) and a search domain list of
  106. * ["myhome.net"]:
  107. * Query: www
  108. * Order: www.myhome.net, www.
  109. *
  110. * Query: www.abc
  111. * Order: www.abc., www.abc.myhome.net
  112. *
  113. * Internals:
  114. *
  115. * Requests are kept in two queues. The first is the inflight queue. In
  116. * this queue requests have an allocated transaction id and nameserver.
  117. * They will soon be transmitted if they haven't already been.
  118. *
  119. * The second is the waiting queue. The size of the inflight ring is
  120. * limited and all other requests wait in waiting queue for space. This
  121. * bounds the number of concurrent requests so that we don't flood the
  122. * nameserver. Several algorithms require a full walk of the inflight
  123. * queue and so bounding its size keeps thing going nicely under huge
  124. * (many thousands of requests) loads.
  125. *
  126. * If a nameserver loses too many requests it is considered down and we
  127. * try not to use it. After a while we send a probe to that nameserver
  128. * (a lookup for google.com) and, if it replies, we consider it working
  129. * again. If the nameserver fails a probe we wait longer to try again
  130. * with the next probe.
  131. */
  132. #ifndef _EVENT2_DNS_H_
  133. #define _EVENT2_DNS_H_
  134. #ifdef __cplusplus
  135. extern "C" {
  136. #endif
  137. /* For integer types. */
  138. #include <event2/util.h>
  139. /** Error codes 0-5 are as described in RFC 1035. */
  140. #define DNS_ERR_NONE 0
  141. /** The name server was unable to interpret the query */
  142. #define DNS_ERR_FORMAT 1
  143. /** The name server was unable to process this query due to a problem with the
  144. * name server */
  145. #define DNS_ERR_SERVERFAILED 2
  146. /** The domain name does not exist */
  147. #define DNS_ERR_NOTEXIST 3
  148. /** The name server does not support the requested kind of query */
  149. #define DNS_ERR_NOTIMPL 4
  150. /** The name server refuses to reform the specified operation for policy
  151. * reasons */
  152. #define DNS_ERR_REFUSED 5
  153. /** The reply was truncated or ill-formatted */
  154. #define DNS_ERR_TRUNCATED 65
  155. /** An unknown error occurred */
  156. #define DNS_ERR_UNKNOWN 66
  157. /** Communication with the server timed out */
  158. #define DNS_ERR_TIMEOUT 67
  159. /** The request was canceled because the DNS subsystem was shut down. */
  160. #define DNS_ERR_SHUTDOWN 68
  161. /** The request was canceled via a call to evdns_cancel_request */
  162. #define DNS_ERR_CANCEL 69
  163. /** There were no answers and no error condition in the DNS packet.
  164. * This can happen when you ask for an address that exists, but a record
  165. * type that doesn't. */
  166. #define DNS_ERR_NODATA 70
  167. #define DNS_IPv4_A 1
  168. #define DNS_PTR 2
  169. #define DNS_IPv6_AAAA 3
  170. #define DNS_QUERY_NO_SEARCH 1
  171. #define DNS_OPTION_SEARCH 1
  172. #define DNS_OPTION_NAMESERVERS 2
  173. #define DNS_OPTION_MISC 4
  174. #define DNS_OPTION_HOSTSFILE 8
  175. #define DNS_OPTIONS_ALL 15
  176. /* Obsolete name for DNS_QUERY_NO_SEARCH */
  177. #define DNS_NO_SEARCH DNS_QUERY_NO_SEARCH
  178. /**
  179. * The callback that contains the results from a lookup.
  180. * - result is one of the DNS_ERR_* values (DNS_ERR_NONE for success)
  181. * - type is either DNS_IPv4_A or DNS_PTR or DNS_IPv6_AAAA
  182. * - count contains the number of addresses of form type
  183. * - ttl is the number of seconds the resolution may be cached for.
  184. * - addresses needs to be cast according to type. It will be an array of
  185. * 4-byte sequences for ipv4, or an array of 16-byte sequences for ipv6,
  186. * or a nul-terminated string for PTR.
  187. */
  188. typedef void (*evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg);
  189. struct evdns_base;
  190. struct event_base;
  191. /**
  192. Initialize the asynchronous DNS library.
  193. This function initializes support for non-blocking name resolution by
  194. calling evdns_resolv_conf_parse() on UNIX and
  195. evdns_config_windows_nameservers() on Windows.
  196. @param event_base the event base to associate the dns client with
  197. @param initialize_nameservers 1 if resolve.conf processing should occur
  198. @return evdns_base object if successful, or NULL if an error occurred.
  199. @see evdns_base_free()
  200. */
  201. struct evdns_base * evdns_base_new(struct event_base *event_base, int initialize_nameservers);
  202. /**
  203. Shut down the asynchronous DNS resolver and terminate all active requests.
  204. If the 'fail_requests' option is enabled, all active requests will return
  205. an empty result with the error flag set to DNS_ERR_SHUTDOWN. Otherwise,
  206. the requests will be silently discarded.
  207. @param evdns_base the evdns base to free
  208. @param fail_requests if zero, active requests will be aborted; if non-zero,
  209. active requests will return DNS_ERR_SHUTDOWN.
  210. @see evdns_base_new()
  211. */
  212. void evdns_base_free(struct evdns_base *base, int fail_requests);
  213. /**
  214. Convert a DNS error code to a string.
  215. @param err the DNS error code
  216. @return a string containing an explanation of the error code
  217. */
  218. const char *evdns_err_to_string(int err);
  219. /**
  220. Add a nameserver.
  221. The address should be an IPv4 address in network byte order.
  222. The type of address is chosen so that it matches in_addr.s_addr.
  223. @param base the evdns_base to which to add the name server
  224. @param address an IP address in network byte order
  225. @return 0 if successful, or -1 if an error occurred
  226. @see evdns_base_nameserver_ip_add()
  227. */
  228. int evdns_base_nameserver_add(struct evdns_base *base,
  229. unsigned long int address);
  230. /**
  231. Get the number of configured nameservers.
  232. This returns the number of configured nameservers (not necessarily the
  233. number of running nameservers). This is useful for double-checking
  234. whether our calls to the various nameserver configuration functions
  235. have been successful.
  236. @param base the evdns_base to which to apply this operation
  237. @return the number of configured nameservers
  238. @see evdns_base_nameserver_add()
  239. */
  240. int evdns_base_count_nameservers(struct evdns_base *base);
  241. /**
  242. Remove all configured nameservers, and suspend all pending resolves.
  243. Resolves will not necessarily be re-attempted until evdns_base_resume() is called.
  244. @param base the evdns_base to which to apply this operation
  245. @return 0 if successful, or -1 if an error occurred
  246. @see evdns_base_resume()
  247. */
  248. int evdns_base_clear_nameservers_and_suspend(struct evdns_base *base);
  249. /**
  250. Resume normal operation and continue any suspended resolve requests.
  251. Re-attempt resolves left in limbo after an earlier call to
  252. evdns_base_clear_nameservers_and_suspend().
  253. @param base the evdns_base to which to apply this operation
  254. @return 0 if successful, or -1 if an error occurred
  255. @see evdns_base_clear_nameservers_and_suspend()
  256. */
  257. int evdns_base_resume(struct evdns_base *base);
  258. /**
  259. Add a nameserver by string address.
  260. This function parses a n IPv4 or IPv6 address from a string and adds it as a
  261. nameserver. It supports the following formats:
  262. - [IPv6Address]:port
  263. - [IPv6Address]
  264. - IPv6Address
  265. - IPv4Address:port
  266. - IPv4Address
  267. If no port is specified, it defaults to 53.
  268. @param base the evdns_base to which to apply this operation
  269. @return 0 if successful, or -1 if an error occurred
  270. @see evdns_base_nameserver_add()
  271. */
  272. int evdns_base_nameserver_ip_add(struct evdns_base *base,
  273. const char *ip_as_string);
  274. /**
  275. Add a nameserver by sockaddr.
  276. **/
  277. int
  278. evdns_base_nameserver_sockaddr_add(struct evdns_base *base,
  279. const struct sockaddr *sa, ev_socklen_t len, unsigned flags);
  280. struct evdns_request;
  281. /**
  282. Lookup an A record for a given name.
  283. @param base the evdns_base to which to apply this operation
  284. @param name a DNS hostname
  285. @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
  286. @param callback a callback function to invoke when the request is completed
  287. @param ptr an argument to pass to the callback function
  288. @return an evdns_request object if successful, or NULL if an error occurred.
  289. @see evdns_resolve_ipv6(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6(), evdns_cancel_request()
  290. */
  291. struct evdns_request *evdns_base_resolve_ipv4(struct evdns_base *base, const char *name, int flags, evdns_callback_type callback, void *ptr);
  292. /**
  293. Lookup an AAAA record for a given name.
  294. @param base the evdns_base to which to apply this operation
  295. @param name a DNS hostname
  296. @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
  297. @param callback a callback function to invoke when the request is completed
  298. @param ptr an argument to pass to the callback function
  299. @return an evdns_request object if successful, or NULL if an error occurred.
  300. @see evdns_resolve_ipv4(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6(), evdns_cancel_request()
  301. */
  302. struct evdns_request *evdns_base_resolve_ipv6(struct evdns_base *base, const char *name, int flags, evdns_callback_type callback, void *ptr);
  303. struct in_addr;
  304. struct in6_addr;
  305. /**
  306. Lookup a PTR record for a given IP address.
  307. @param base the evdns_base to which to apply this operation
  308. @param in an IPv4 address
  309. @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
  310. @param callback a callback function to invoke when the request is completed
  311. @param ptr an argument to pass to the callback function
  312. @return an evdns_request object if successful, or NULL if an error occurred.
  313. @see evdns_resolve_reverse_ipv6(), evdns_cancel_request()
  314. */
  315. struct evdns_request *evdns_base_resolve_reverse(struct evdns_base *base, const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
  316. /**
  317. Lookup a PTR record for a given IPv6 address.
  318. @param base the evdns_base to which to apply this operation
  319. @param in an IPv6 address
  320. @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
  321. @param callback a callback function to invoke when the request is completed
  322. @param ptr an argument to pass to the callback function
  323. @return an evdns_request object if successful, or NULL if an error occurred.
  324. @see evdns_resolve_reverse_ipv6(), evdns_cancel_request()
  325. */
  326. 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);
  327. /**
  328. Cancels a pending DNS resolution request.
  329. @param base the evdns_base that was used to make the request
  330. @param req the evdns_request that was returned by calling a resolve function
  331. @see evdns_base_resolve_ipv4(), evdns_base_resolve_ipv6, evdns_base_resolve_reverse
  332. */
  333. void evdns_cancel_request(struct evdns_base *base, struct evdns_request *req);
  334. /**
  335. Set the value of a configuration option.
  336. The currently available configuration options are:
  337. ndots, timeout, max-timeouts, max-inflight, attempts, randomize-case,
  338. bind-to, initial-probe-timeout, getaddrinfo-allow-skew.
  339. In versions before Libevent 2.0.3-alpha, the option name needed to end with
  340. a colon.
  341. @param base the evdns_base to which to apply this operation
  342. @param option the name of the configuration option to be modified
  343. @param val the value to be set
  344. @return 0 if successful, or -1 if an error occurred
  345. */
  346. int evdns_base_set_option(struct evdns_base *base, const char *option, const char *val);
  347. /**
  348. Parse a resolv.conf file.
  349. The 'flags' parameter determines what information is parsed from the
  350. resolv.conf file. See the man page for resolv.conf for the format of this
  351. file.
  352. The following directives are not parsed from the file: sortlist, rotate,
  353. no-check-names, inet6, debug.
  354. If this function encounters an error, the possible return values are: 1 =
  355. failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of
  356. memory, 5 = short read from file, 6 = no nameservers listed in the file
  357. @param base the evdns_base to which to apply this operation
  358. @param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC|
  359. DNS_OPTION_HOSTSFILE|DNS_OPTIONS_ALL
  360. @param filename the path to the resolv.conf file
  361. @return 0 if successful, or various positive error codes if an error
  362. occurred (see above)
  363. @see resolv.conf(3), evdns_config_windows_nameservers()
  364. */
  365. int evdns_base_resolv_conf_parse(struct evdns_base *base, int flags, const char *const filename);
  366. /**
  367. Load an /etc/hosts-style file from 'hosts_fname' into 'base'.
  368. If hosts_fname is NULL, add minimal entries for localhost, and nothing
  369. else.
  370. Note that only evdns_getaddrinfo uses the /etc/hosts entries.
  371. Return 0 on success, negative on failure.
  372. */
  373. int evdns_base_load_hosts(struct evdns_base *base, const char *hosts_fname);
  374. /**
  375. Obtain nameserver information using the Windows API.
  376. Attempt to configure a set of nameservers based on platform settings on
  377. a win32 host. Preferentially tries to use GetNetworkParams; if that fails,
  378. looks in the registry.
  379. @return 0 if successful, or -1 if an error occurred
  380. @see evdns_resolv_conf_parse()
  381. */
  382. #ifdef WIN32
  383. int evdns_base_config_windows_nameservers(struct evdns_base *);
  384. #define EVDNS_BASE_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
  385. #endif
  386. /**
  387. Clear the list of search domains.
  388. */
  389. void evdns_base_search_clear(struct evdns_base *base);
  390. /**
  391. Add a domain to the list of search domains
  392. @param domain the domain to be added to the search list
  393. */
  394. void evdns_base_search_add(struct evdns_base *base, const char *domain);
  395. /**
  396. Set the 'ndots' parameter for searches.
  397. Sets the number of dots which, when found in a name, causes
  398. the first query to be without any search domain.
  399. @param ndots the new ndots parameter
  400. */
  401. void evdns_base_search_ndots_set(struct evdns_base *base, const int ndots);
  402. /**
  403. A callback that is invoked when a log message is generated
  404. @param is_warning indicates if the log message is a 'warning'
  405. @param msg the content of the log message
  406. */
  407. typedef void (*evdns_debug_log_fn_type)(int is_warning, const char *msg);
  408. /**
  409. Set the callback function to handle DNS log messages. If this
  410. callback is not set, evdns log messages are handled with the regular
  411. Libevent logging system.
  412. @param fn the callback to be invoked when a log message is generated
  413. */
  414. void evdns_set_log_fn(evdns_debug_log_fn_type fn);
  415. /**
  416. Set a callback that will be invoked to generate transaction IDs. By
  417. default, we pick transaction IDs based on the current clock time, which
  418. is bad for security.
  419. @param fn the new callback, or NULL to use the default.
  420. NOTE: This function has no effect in Libevent 2.0.4-alpha and later,
  421. since Libevent now provides its own secure RNG.
  422. */
  423. void evdns_set_transaction_id_fn(ev_uint16_t (*fn)(void));
  424. /**
  425. Set a callback used to generate random bytes. By default, we use
  426. the same function as passed to evdns_set_transaction_id_fn to generate
  427. bytes two at a time. If a function is provided here, it's also used
  428. to generate transaction IDs.
  429. NOTE: This function has no effect in Libevent 2.0.4-alpha and later,
  430. since Libevent now provides its own secure RNG.
  431. */
  432. void evdns_set_random_bytes_fn(void (*fn)(char *, size_t));
  433. /*
  434. * Functions used to implement a DNS server.
  435. */
  436. struct evdns_server_request;
  437. struct evdns_server_question;
  438. /**
  439. A callback to implement a DNS server. The callback function receives a DNS
  440. request. It should then optionally add a number of answers to the reply
  441. using the evdns_server_request_add_*_reply functions, before calling either
  442. evdns_server_request_respond to send the reply back, or
  443. evdns_server_request_drop to decline to answer the request.
  444. @param req A newly received request
  445. @param user_data A pointer that was passed to
  446. evdns_add_server_port_with_base().
  447. */
  448. typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void *);
  449. #define EVDNS_ANSWER_SECTION 0
  450. #define EVDNS_AUTHORITY_SECTION 1
  451. #define EVDNS_ADDITIONAL_SECTION 2
  452. #define EVDNS_TYPE_A 1
  453. #define EVDNS_TYPE_NS 2
  454. #define EVDNS_TYPE_CNAME 5
  455. #define EVDNS_TYPE_SOA 6
  456. #define EVDNS_TYPE_PTR 12
  457. #define EVDNS_TYPE_MX 15
  458. #define EVDNS_TYPE_TXT 16
  459. #define EVDNS_TYPE_AAAA 28
  460. #define EVDNS_QTYPE_AXFR 252
  461. #define EVDNS_QTYPE_ALL 255
  462. #define EVDNS_CLASS_INET 1
  463. /* flags that can be set in answers; as part of the err parameter */
  464. #define EVDNS_FLAGS_AA 0x400
  465. #define EVDNS_FLAGS_RD 0x080
  466. /** Create a new DNS server port.
  467. @param base The event base to handle events for the server port.
  468. @param socket A UDP socket to accept DNS requests.
  469. @param flags Always 0 for now.
  470. @param callback A function to invoke whenever we get a DNS request
  471. on the socket.
  472. @param user_data Data to pass to the callback.
  473. @return an evdns_server_port structure for this server port.
  474. */
  475. 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);
  476. /** Close down a DNS server port, and free associated structures. */
  477. void evdns_close_server_port(struct evdns_server_port *port);
  478. /** Sets some flags in a reply we're building.
  479. Allows setting of the AA or RD flags
  480. */
  481. void evdns_server_request_set_flags(struct evdns_server_request *req, int flags);
  482. /* Functions to add an answer to an in-progress DNS reply.
  483. */
  484. 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);
  485. int evdns_server_request_add_a_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
  486. int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl);
  487. 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);
  488. int evdns_server_request_add_cname_reply(struct evdns_server_request *req, const char *name, const char *cname, int ttl);
  489. /**
  490. Send back a response to a DNS request, and free the request structure.
  491. */
  492. int evdns_server_request_respond(struct evdns_server_request *req, int err);
  493. /**
  494. Free a DNS request without sending back a reply.
  495. */
  496. int evdns_server_request_drop(struct evdns_server_request *req);
  497. struct sockaddr;
  498. /**
  499. Get the address that made a DNS request.
  500. */
  501. int evdns_server_request_get_requesting_addr(struct evdns_server_request *_req, struct sockaddr *sa, int addr_len);
  502. /** Callback for evdns_getaddrinfo. */
  503. typedef void (*evdns_getaddrinfo_cb)(int result, struct evutil_addrinfo *res, void *arg);
  504. struct evdns_base;
  505. struct evdns_getaddrinfo_request;
  506. /** Make a non-blocking getaddrinfo request using the dns_base in 'dns_base'.
  507. *
  508. * If we can answer the request immediately (with an error or not!), then we
  509. * invoke cb immediately and return NULL. Otherwise we return
  510. * an evdns_getaddrinfo_request and invoke cb later.
  511. *
  512. * When the callback is invoked, we pass as its first argument the error code
  513. * that getaddrinfo would return (or 0 for no error). As its second argument,
  514. * we pass the evutil_addrinfo structures we found (or NULL on error). We
  515. * pass 'arg' as the third argument.
  516. *
  517. * Limitations:
  518. *
  519. * - The AI_V4MAPPED and AI_ALL flags are not currently implemented.
  520. * - For ai_socktype, we only handle SOCKTYPE_STREAM, SOCKTYPE_UDP, and 0.
  521. * - For ai_protocol, we only handle IPPROTO_TCP, IPPROTO_UDP, and 0.
  522. */
  523. struct evdns_getaddrinfo_request *evdns_getaddrinfo(
  524. struct evdns_base *dns_base,
  525. const char *nodename, const char *servname,
  526. const struct evutil_addrinfo *hints_in,
  527. evdns_getaddrinfo_cb cb, void *arg);
  528. /* Cancel an in-progress evdns_getaddrinfo. This MUST NOT be called after the
  529. * getaddrinfo's callback has been invoked. The resolves will be canceled,
  530. * and the callback will be invoked with the error EVUTIL_EAI_CANCEL. */
  531. void evdns_getaddrinfo_cancel(struct evdns_getaddrinfo_request *req);
  532. #ifdef __cplusplus
  533. }
  534. #endif
  535. #endif /* !_EVENT2_DNS_H_ */