libevent (2.1.12)
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 #include <event2/visibility.h>
53
54 /**
55 Initialize the asynchronous DNS library.
56
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.
60
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
65 evdns_base_new().
66
67 @return 0 if successful, or -1 if an error occurred
68 @see evdns_shutdown()
69 */
70 EVENT2_EXPORT_SYMBOL
71 int evdns_init(void);
72
73 struct evdns_base;
74 /**
75 Return the global evdns_base created by event_init() and used by the other
76 deprecated functions.
77
78 @deprecated This function is deprecated because use of the global
79 evdns_base is error-prone.
80 */
81 EVENT2_EXPORT_SYMBOL
82 struct evdns_base *evdns_get_global_base(void);
83
84 /**
85 Shut down the asynchronous DNS resolver and terminate all active requests.
86
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.
90
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().
94
95 @param fail_requests if zero, active requests will be aborted; if non-zero,
96 active requests will return DNS_ERR_SHUTDOWN.
97 @see evdns_init()
98 */
99 EVENT2_EXPORT_SYMBOL
100 void evdns_shutdown(int fail_requests);
101
102 /**
103 Add a nameserver.
104
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.
107
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().
111
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()
115 */
116 EVENT2_EXPORT_SYMBOL
117 int evdns_nameserver_add(unsigned long int address);
118
119 /**
120 Get the number of configured nameservers.
121
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.
126
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().
130
131 @return the number of configured nameservers
132 @see evdns_nameserver_add()
133 */
134 EVENT2_EXPORT_SYMBOL
135 int evdns_count_nameservers(void);
136
137 /**
138 Remove all configured nameservers, and suspend all pending resolves.
139
140 Resolves will not necessarily be re-attempted until evdns_resume() is called.
141
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().
145
146 @return 0 if successful, or -1 if an error occurred
147 @see evdns_resume()
148 */
149 EVENT2_EXPORT_SYMBOL
150 int evdns_clear_nameservers_and_suspend(void);
151
152 /**
153 Resume normal operation and continue any suspended resolve requests.
154
155 Re-attempt resolves left in limbo after an earlier call to
156 evdns_clear_nameservers_and_suspend().
157
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().
161
162 @return 0 if successful, or -1 if an error occurred
163 @see evdns_clear_nameservers_and_suspend()
164 */
165 EVENT2_EXPORT_SYMBOL
166 int evdns_resume(void);
167
168 /**
169 Add a nameserver.
170
171 This wraps the evdns_nameserver_add() function by parsing a string as an IP
172 address and adds it as a nameserver.
173
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().
177
178 @return 0 if successful, or -1 if an error occurred
179 @see evdns_nameserver_add()
180 */
181 EVENT2_EXPORT_SYMBOL
182 int evdns_nameserver_ip_add(const char *ip_as_string);
183
184 /**
185 Lookup an A record for a given name.
186
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().
190
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()
197 */
198 EVENT2_EXPORT_SYMBOL
199 int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr);
200
201 /**
202 Lookup an AAAA record for a given name.
203
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()
210 */
211 EVENT2_EXPORT_SYMBOL
212 int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
213
214 struct in_addr;
215 struct in6_addr;
216
217 /**
218 Lookup a PTR record for a given IP address.
219
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().
223
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()
230 */
231 EVENT2_EXPORT_SYMBOL
232 int evdns_resolve_reverse(const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
233
234 /**
235 Lookup a PTR record for a given IPv6 address.
236
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().
240
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()
247 */
248 EVENT2_EXPORT_SYMBOL
249 int evdns_resolve_reverse_ipv6(const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
250
251 /**
252 Set the value of a configuration option.
253
254 The currently available configuration options are:
255
256 ndots, timeout, max-timeouts, max-inflight, and attempts
257
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().
261
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
266 */
267 EVENT2_EXPORT_SYMBOL
268 int evdns_set_option(const char *option, const char *val, int flags);
269
270 /**
271 Parse a resolv.conf file.
272
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
275 file.
276
277 The following directives are not parsed from the file: sortlist, rotate,
278 no-check-names, inet6, debug.
279
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
283
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().
287
288 @param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC|
289 DNS_OPTIONS_ALL
290 @param filename the path to the resolv.conf file
291 @return 0 if successful, or various positive error codes if an error
292 occurred (see above)
293 @see resolv.conf(3), evdns_config_windows_nameservers()
294 */
295 EVENT2_EXPORT_SYMBOL
296 int evdns_resolv_conf_parse(int flags, const char *const filename);
297
298 /**
299 Clear the list of search domains.
300
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().
304 */
305 EVENT2_EXPORT_SYMBOL
306 void evdns_search_clear(void);
307
308 /**
309 Add a domain to the list of search domains
310
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().
314
315 @param domain the domain to be added to the search list
316 */
317 EVENT2_EXPORT_SYMBOL
318 void evdns_search_add(const char *domain);
319
320 /**
321 Set the 'ndots' parameter for searches.
322
323 Sets the number of dots which, when found in a name, causes
324 the first query to be without any search domain.
325
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().
329
330 @param ndots the new ndots parameter
331 */
332 EVENT2_EXPORT_SYMBOL
333 void evdns_search_ndots_set(const int ndots);
334
335 /**
336 As evdns_server_new_with_base.
337
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().
341
342 */
343 EVENT2_EXPORT_SYMBOL
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);
347
348 #ifdef _WIN32
349 EVENT2_EXPORT_SYMBOL
350 int evdns_config_windows_nameservers(void);
351 #define EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
352 #endif
353
354 #ifdef __cplusplus
355 }
356 #endif
357
358 #endif /* EVENT2_EVENT_COMPAT_H_INCLUDED_ */
Browse
Usage
Versions