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