dns_compat.h (12588B)
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_ */