2 * Copyright (c) 2006-2007 Niels Provos <provos@citi.umich.edu>
3 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
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.
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.
27 #ifndef EVENT2_DNS_COMPAT_H_INCLUDED_
28 #define EVENT2_DNS_COMPAT_H_INCLUDED_
30 /** @file event2/dns_compat.h
32 Potentially non-threadsafe versions of the functions in dns.h: provided
33 only for backwards compatibility.
42 #include <event2/event-config.h>
43 #ifdef EVENT__HAVE_SYS_TYPES_H
44 #include <sys/types.h>
46 #ifdef EVENT__HAVE_SYS_TIME_H
51 #include <event2/util.h>
52 #include <event2/visibility.h>
55 Initialize the asynchronous DNS library.
57 This function initializes support for non-blocking name resolution by
58 calling evdns_resolv_conf_parse() on UNIX and
59 evdns_config_windows_nameservers() on Windows.
61 @deprecated This function is deprecated because it always uses the current
62 event base, and is easily confused by multiple calls to event_init(), and
63 so is not safe for multithreaded use. Additionally, it allocates a global
64 structure that only one thread can use. The replacement is
67 @return 0 if successful, or -1 if an error occurred
75 Return the global evdns_base created by event_init() and used by the other
78 @deprecated This function is deprecated because use of the global
79 evdns_base is error-prone.
82 struct evdns_base *evdns_get_global_base(void);
85 Shut down the asynchronous DNS resolver and terminate all active requests.
87 If the 'fail_requests' option is enabled, all active requests will return
88 an empty result with the error flag set to DNS_ERR_SHUTDOWN. Otherwise,
89 the requests will be silently discarded.
91 @deprecated This function is deprecated because it does not allow the
92 caller to specify which evdns_base it applies to. The recommended
93 function is evdns_base_shutdown().
95 @param fail_requests if zero, active requests will be aborted; if non-zero,
96 active requests will return DNS_ERR_SHUTDOWN.
100 void evdns_shutdown(int fail_requests);
105 The address should be an IPv4 address in network byte order.
106 The type of address is chosen so that it matches in_addr.s_addr.
108 @deprecated This function is deprecated because it does not allow the
109 caller to specify which evdns_base it applies to. The recommended
110 function is evdns_base_nameserver_add().
112 @param address an IP address in network byte order
113 @return 0 if successful, or -1 if an error occurred
114 @see evdns_nameserver_ip_add()
117 int evdns_nameserver_add(unsigned long int address);
120 Get the number of configured nameservers.
122 This returns the number of configured nameservers (not necessarily the
123 number of running nameservers). This is useful for double-checking
124 whether our calls to the various nameserver configuration functions
125 have been successful.
127 @deprecated This function is deprecated because it does not allow the
128 caller to specify which evdns_base it applies to. The recommended
129 function is evdns_base_count_nameservers().
131 @return the number of configured nameservers
132 @see evdns_nameserver_add()
135 int evdns_count_nameservers(void);
138 Remove all configured nameservers, and suspend all pending resolves.
140 Resolves will not necessarily be re-attempted until evdns_resume() is called.
142 @deprecated This function is deprecated because it does not allow the
143 caller to specify which evdns_base it applies to. The recommended
144 function is evdns_base_clear_nameservers_and_suspend().
146 @return 0 if successful, or -1 if an error occurred
150 int evdns_clear_nameservers_and_suspend(void);
153 Resume normal operation and continue any suspended resolve requests.
155 Re-attempt resolves left in limbo after an earlier call to
156 evdns_clear_nameservers_and_suspend().
158 @deprecated This function is deprecated because it does not allow the
159 caller to specify which evdns_base it applies to. The recommended
160 function is evdns_base_resume().
162 @return 0 if successful, or -1 if an error occurred
163 @see evdns_clear_nameservers_and_suspend()
166 int evdns_resume(void);
171 This wraps the evdns_nameserver_add() function by parsing a string as an IP
172 address and adds it as a nameserver.
174 @deprecated This function is deprecated because it does not allow the
175 caller to specify which evdns_base it applies to. The recommended
176 function is evdns_base_nameserver_ip_add().
178 @return 0 if successful, or -1 if an error occurred
179 @see evdns_nameserver_add()
182 int evdns_nameserver_ip_add(const char *ip_as_string);
185 Lookup an A record for a given name.
187 @deprecated This function is deprecated because it does not allow the
188 caller to specify which evdns_base it applies to. The recommended
189 function is evdns_base_resolve_ipv4().
191 @param name a DNS hostname
192 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
193 @param callback a callback function to invoke when the request is completed
194 @param ptr an argument to pass to the callback function
195 @return 0 if successful, or -1 if an error occurred
196 @see evdns_resolve_ipv6(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6()
199 int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr);
202 Lookup an AAAA record for a given name.
204 @param name a DNS hostname
205 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
206 @param callback a callback function to invoke when the request is completed
207 @param ptr an argument to pass to the callback function
208 @return 0 if successful, or -1 if an error occurred
209 @see evdns_resolve_ipv4(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6()
212 int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
218 Lookup a PTR record for a given IP address.
220 @deprecated This function is deprecated because it does not allow the
221 caller to specify which evdns_base it applies to. The recommended
222 function is evdns_base_resolve_reverse().
224 @param in an IPv4 address
225 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
226 @param callback a callback function to invoke when the request is completed
227 @param ptr an argument to pass to the callback function
228 @return 0 if successful, or -1 if an error occurred
229 @see evdns_resolve_reverse_ipv6()
232 int evdns_resolve_reverse(const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
235 Lookup a PTR record for a given IPv6 address.
237 @deprecated This function is deprecated because it does not allow the
238 caller to specify which evdns_base it applies to. The recommended
239 function is evdns_base_resolve_reverse_ipv6().
241 @param in an IPv6 address
242 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
243 @param callback a callback function to invoke when the request is completed
244 @param ptr an argument to pass to the callback function
245 @return 0 if successful, or -1 if an error occurred
246 @see evdns_resolve_reverse_ipv6()
249 int evdns_resolve_reverse_ipv6(const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
252 Set the value of a configuration option.
254 The currently available configuration options are:
256 ndots, timeout, max-timeouts, max-inflight, and attempts
258 @deprecated This function is deprecated because it does not allow the
259 caller to specify which evdns_base it applies to. The recommended
260 function is evdns_base_set_option().
262 @param option the name of the configuration option to be modified
263 @param val the value to be set
264 @param flags Ignored.
265 @return 0 if successful, or -1 if an error occurred
268 int evdns_set_option(const char *option, const char *val, int flags);
271 Parse a resolv.conf file.
273 The 'flags' parameter determines what information is parsed from the
274 resolv.conf file. See the man page for resolv.conf for the format of this
277 The following directives are not parsed from the file: sortlist, rotate,
278 no-check-names, inet6, debug.
280 If this function encounters an error, the possible return values are: 1 =
281 failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of
282 memory, 5 = short read from file, 6 = no nameservers listed in the file
284 @deprecated This function is deprecated because it does not allow the
285 caller to specify which evdns_base it applies to. The recommended
286 function is evdns_base_resolv_conf_parse().
288 @param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC|
290 @param filename the path to the resolv.conf file
291 @return 0 if successful, or various positive error codes if an error
293 @see resolv.conf(3), evdns_config_windows_nameservers()
296 int evdns_resolv_conf_parse(int flags, const char *const filename);
299 Clear the list of search domains.
301 @deprecated This function is deprecated because it does not allow the
302 caller to specify which evdns_base it applies to. The recommended
303 function is evdns_base_search_clear().
306 void evdns_search_clear(void);
309 Add a domain to the list of search domains
311 @deprecated This function is deprecated because it does not allow the
312 caller to specify which evdns_base it applies to. The recommended
313 function is evdns_base_search_add().
315 @param domain the domain to be added to the search list
318 void evdns_search_add(const char *domain);
321 Set the 'ndots' parameter for searches.
323 Sets the number of dots which, when found in a name, causes
324 the first query to be without any search domain.
326 @deprecated This function is deprecated because it does not allow the
327 caller to specify which evdns_base it applies to. The recommended
328 function is evdns_base_search_ndots_set().
330 @param ndots the new ndots parameter
333 void evdns_search_ndots_set(const int ndots);
336 As evdns_server_new_with_base.
338 @deprecated This function is deprecated because it does not allow the
339 caller to specify which even_base it uses. The recommended
340 function is evdns_add_server_port_with_base().
344 struct evdns_server_port *
345 evdns_add_server_port(evutil_socket_t socket, int flags,
346 evdns_request_callback_fn_type callback, void *user_data);
350 int evdns_config_windows_nameservers(void);
351 #define EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
358 #endif /* EVENT2_EVENT_COMPAT_H_INCLUDED_ */