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_INCLUDED_
28 #define EVENT2_DNS_COMPAT_H_INCLUDED_
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_INCLUDED_ */
337