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 #ifndef _EVENT2_DNS_COMPAT_H_
28 #define _EVENT2_DNS_COMPAT_H_
29
30 /** @file event2/dns_compat.h
31
32 Potentially non-threadsafe versions of the functions in dns.h: provided
33 only for backwards compatibility.
34
35
36 */
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 #include <event2/event-config.h>
43 #ifdef _EVENT_HAVE_SYS_TYPES_H
44 #include <sys/types.h>
45 #endif
46 #ifdef _EVENT_HAVE_SYS_TIME_H
47 #include <sys/time.h>
48 #endif
49
50 /* For int types. */
51 #include <event2/util.h>
52
53 /**
54 Initialize the asynchronous DNS library.
55
56 This function initializes support for non-blocking name resolution by
57 calling evdns_resolv_conf_parse() on UNIX and
58 evdns_config_windows_nameservers() on Windows.
59
60 @deprecated This function is deprecated because it always uses the current
61 event base, and is easily confused by multiple calls to event_init(), and
62 so is not safe for multithreaded use. Additionally, it allocates a global
63 structure that only one thread can use. The replacement is
64 evdns_base_new().
65
66 @return 0 if successful, or -1 if an error occurred
67 @see evdns_shutdown()
68 */
69 int evdns_init(void);
70
71 struct evdns_base;
72 /**
73 Return the global evdns_base created by event_init() and used by the other
74 deprecated functions.
75
76 @deprecated This function is deprecated because use of the global
77 evdns_base is error-prone.
78 */
79 struct evdns_base *evdns_get_global_base(void);
80
81 /**
82 Shut down the asynchronous DNS resolver and terminate all active requests.
83
84 If the 'fail_requests' option is enabled, all active requests will return
85 an empty result with the error flag set to DNS_ERR_SHUTDOWN. Otherwise,
86 the requests will be silently discarded.
87
88 @deprecated This function is deprecated because it does not allow the
89 caller to specify which evdns_base it applies to. The recommended
90 function is evdns_base_shutdown().
91
92 @param fail_requests if zero, active requests will be aborted; if non-zero,
93 active requests will return DNS_ERR_SHUTDOWN.
94 @see evdns_init()
95 */
96 void evdns_shutdown(int fail_requests);
97
98 /**
99 Add a nameserver.
100
101 The address should be an IPv4 address in network byte order.
102 The type of address is chosen so that it matches in_addr.s_addr.
103
104 @deprecated This function is deprecated because it does not allow the
105 caller to specify which evdns_base it applies to. The recommended
106 function is evdns_base_nameserver_add().
107
108 @param address an IP address in network byte order
109 @return 0 if successful, or -1 if an error occurred
110 @see evdns_nameserver_ip_add()
111 */
112 int evdns_nameserver_add(unsigned long int address);
113
114 /**
115 Get the number of configured nameservers.
116
117 This returns the number of configured nameservers (not necessarily the
118 number of running nameservers). This is useful for double-checking
119 whether our calls to the various nameserver configuration functions
120 have been successful.
121
122 @deprecated This function is deprecated because it does not allow the
123 caller to specify which evdns_base it applies to. The recommended
124 function is evdns_base_count_nameservers().
125
126 @return the number of configured nameservers
127 @see evdns_nameserver_add()
128 */
129 int evdns_count_nameservers(void);
130
131 /**
132 Remove all configured nameservers, and suspend all pending resolves.
133
134 Resolves will not necessarily be re-attempted until evdns_resume() is called.
135
136 @deprecated This function is deprecated because it does not allow the
137 caller to specify which evdns_base it applies to. The recommended
138 function is evdns_base_clear_nameservers_and_suspend().
139
140 @return 0 if successful, or -1 if an error occurred
141 @see evdns_resume()
142 */
143 int evdns_clear_nameservers_and_suspend(void);
144
145 /**
146 Resume normal operation and continue any suspended resolve requests.
147
148 Re-attempt resolves left in limbo after an earlier call to
149 evdns_clear_nameservers_and_suspend().
150
151 @deprecated This function is deprecated because it does not allow the
152 caller to specify which evdns_base it applies to. The recommended
153 function is evdns_base_resume().
154
155 @return 0 if successful, or -1 if an error occurred
156 @see evdns_clear_nameservers_and_suspend()
157 */
158 int evdns_resume(void);
159
160 /**
161 Add a nameserver.
162
163 This wraps the evdns_nameserver_add() function by parsing a string as an IP
164 address and adds it as a nameserver.
165
166 @deprecated This function is deprecated because it does not allow the
167 caller to specify which evdns_base it applies to. The recommended
168 function is evdns_base_nameserver_ip_add().
169
170 @return 0 if successful, or -1 if an error occurred
171 @see evdns_nameserver_add()
172 */
173 int evdns_nameserver_ip_add(const char *ip_as_string);
174
175 /**
176 Lookup an A record for a given name.
177
178 @deprecated This function is deprecated because it does not allow the
179 caller to specify which evdns_base it applies to. The recommended
180 function is evdns_base_resolve_ipv4().
181
182 @param name a DNS hostname
183 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
184 @param callback a callback function to invoke when the request is completed
185 @param ptr an argument to pass to the callback function
186 @return 0 if successful, or -1 if an error occurred
187 @see evdns_resolve_ipv6(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6()
188 */
189 int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr);
190
191 /**
192 Lookup an AAAA record for a given name.
193
194 @param name a DNS hostname
195 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
196 @param callback a callback function to invoke when the request is completed
197 @param ptr an argument to pass to the callback function
198 @return 0 if successful, or -1 if an error occurred
199 @see evdns_resolve_ipv4(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6()
200 */
201 int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
202
203 struct in_addr;
204 struct in6_addr;
205
206 /**
207 Lookup a PTR record for a given IP address.
208
209 @deprecated This function is deprecated because it does not allow the
210 caller to specify which evdns_base it applies to. The recommended
211 function is evdns_base_resolve_reverse().
212
213 @param in an IPv4 address
214 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
215 @param callback a callback function to invoke when the request is completed
216 @param ptr an argument to pass to the callback function
217 @return 0 if successful, or -1 if an error occurred
218 @see evdns_resolve_reverse_ipv6()
219 */
220 int evdns_resolve_reverse(const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
221
222 /**
223 Lookup a PTR record for a given IPv6 address.
224
225 @deprecated This function is deprecated because it does not allow the
226 caller to specify which evdns_base it applies to. The recommended
227 function is evdns_base_resolve_reverse_ipv6().
228
229 @param in an IPv6 address
230 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
231 @param callback a callback function to invoke when the request is completed
232 @param ptr an argument to pass to the callback function
233 @return 0 if successful, or -1 if an error occurred
234 @see evdns_resolve_reverse_ipv6()
235 */
236 int evdns_resolve_reverse_ipv6(const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
237
238 /**
239 Set the value of a configuration option.
240
241 The currently available configuration options are:
242
243 ndots, timeout, max-timeouts, max-inflight, and attempts
244
245 @deprecated This function is deprecated because it does not allow the
246 caller to specify which evdns_base it applies to. The recommended
247 function is evdns_base_set_option().
248
249 @param option the name of the configuration option to be modified
250 @param val the value to be set
251 @param flags Ignored.
252 @return 0 if successful, or -1 if an error occurred
253 */
254 int evdns_set_option(const char *option, const char *val, int flags);
255
256 /**
257 Parse a resolv.conf file.
258
259 The 'flags' parameter determines what information is parsed from the
260 resolv.conf file. See the man page for resolv.conf for the format of this
261 file.
262
263 The following directives are not parsed from the file: sortlist, rotate,
264 no-check-names, inet6, debug.
265
266 If this function encounters an error, the possible return values are: 1 =
267 failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of
268 memory, 5 = short read from file, 6 = no nameservers listed in the file
269
270 @deprecated This function is deprecated because it does not allow the
271 caller to specify which evdns_base it applies to. The recommended
272 function is evdns_base_resolv_conf_parse().
273
274 @param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC|
275 DNS_OPTIONS_ALL
276 @param filename the path to the resolv.conf file
277 @return 0 if successful, or various positive error codes if an error
278 occurred (see above)
279 @see resolv.conf(3), evdns_config_windows_nameservers()
280 */
281 int evdns_resolv_conf_parse(int flags, const char *const filename);
282
283 /**
284 Clear the list of search domains.
285
286 @deprecated This function is deprecated because it does not allow the
287 caller to specify which evdns_base it applies to. The recommended
288 function is evdns_base_search_clear().
289 */
290 void evdns_search_clear(void);
291
292 /**
293 Add a domain to the list of search domains
294
295 @deprecated This function is deprecated because it does not allow the
296 caller to specify which evdns_base it applies to. The recommended
297 function is evdns_base_search_add().
298
299 @param domain the domain to be added to the search list
300 */
301 void evdns_search_add(const char *domain);
302
303 /**
304 Set the 'ndots' parameter for searches.
305
306 Sets the number of dots which, when found in a name, causes
307 the first query to be without any search domain.
308
309 @deprecated This function is deprecated because it does not allow the
310 caller to specify which evdns_base it applies to. The recommended
311 function is evdns_base_search_ndots_set().
312
313 @param ndots the new ndots parameter
314 */
315 void evdns_search_ndots_set(const int ndots);
316
317 /**
318 As evdns_server_new_with_base.
319
320 @deprecated This function is deprecated because it does not allow the
321 caller to specify which even_base it uses. The recommended
322 function is evdns_add_server_port_with_base().
323
324 */
325 struct evdns_server_port *evdns_add_server_port(evutil_socket_t socket, int flags, evdns_request_callback_fn_type callback, void *user_data);
326
327 #ifdef WIN32
328 int evdns_config_windows_nameservers(void);
329 #define EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
330 #endif
331
332 #ifdef __cplusplus
333 }
334 #endif
335
336 #endif /* _EVENT2_EVENT_COMPAT_H_ */