1 /* $NetBSD: dns_compat.h,v 1.1.1.4 2021/04/07 02:43:14 christos Exp $ */ 2 /* 3 * Copyright (c) 2006-2007 Niels Provos <provos@citi.umich.edu> 4 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 1. Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 3. The name of the author may not be used to endorse or promote products 15 * derived from this software without specific prior written permission. 16 * 17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 */ 28 #ifndef EVENT2_DNS_COMPAT_H_INCLUDED_ 29 #define EVENT2_DNS_COMPAT_H_INCLUDED_ 30 31 /** @file event2/dns_compat.h 32 33 Potentially non-threadsafe versions of the functions in dns.h: provided 34 only for backwards compatibility. 35 36 37 */ 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 #include <event2/event-config.h> 44 #ifdef EVENT__HAVE_SYS_TYPES_H 45 #include <sys/types.h> 46 #endif 47 #ifdef EVENT__HAVE_SYS_TIME_H 48 #include <sys/time.h> 49 #endif 50 51 /* For int types. */ 52 #include <event2/util.h> 53 #include <event2/visibility.h> 54 55 /** 56 Initialize the asynchronous DNS library. 57 58 This function initializes support for non-blocking name resolution by 59 calling evdns_resolv_conf_parse() on UNIX and 60 evdns_config_windows_nameservers() on Windows. 61 62 @deprecated This function is deprecated because it always uses the current 63 event base, and is easily confused by multiple calls to event_init(), and 64 so is not safe for multithreaded use. Additionally, it allocates a global 65 structure that only one thread can use. The replacement is 66 evdns_base_new(). 67 68 @return 0 if successful, or -1 if an error occurred 69 @see evdns_shutdown() 70 */ 71 EVENT2_EXPORT_SYMBOL 72 int evdns_init(void); 73 74 struct evdns_base; 75 /** 76 Return the global evdns_base created by event_init() and used by the other 77 deprecated functions. 78 79 @deprecated This function is deprecated because use of the global 80 evdns_base is error-prone. 81 */ 82 EVENT2_EXPORT_SYMBOL 83 struct evdns_base *evdns_get_global_base(void); 84 85 /** 86 Shut down the asynchronous DNS resolver and terminate all active requests. 87 88 If the 'fail_requests' option is enabled, all active requests will return 89 an empty result with the error flag set to DNS_ERR_SHUTDOWN. Otherwise, 90 the requests will be silently discarded. 91 92 @deprecated This function is deprecated because it does not allow the 93 caller to specify which evdns_base it applies to. The recommended 94 function is evdns_base_shutdown(). 95 96 @param fail_requests if zero, active requests will be aborted; if non-zero, 97 active requests will return DNS_ERR_SHUTDOWN. 98 @see evdns_init() 99 */ 100 EVENT2_EXPORT_SYMBOL 101 void evdns_shutdown(int fail_requests); 102 103 /** 104 Add a nameserver. 105 106 The address should be an IPv4 address in network byte order. 107 The type of address is chosen so that it matches in_addr.s_addr. 108 109 @deprecated This function is deprecated because it does not allow the 110 caller to specify which evdns_base it applies to. The recommended 111 function is evdns_base_nameserver_add(). 112 113 @param address an IP address in network byte order 114 @return 0 if successful, or -1 if an error occurred 115 @see evdns_nameserver_ip_add() 116 */ 117 EVENT2_EXPORT_SYMBOL 118 int evdns_nameserver_add(unsigned long int address); 119 120 /** 121 Get the number of configured nameservers. 122 123 This returns the number of configured nameservers (not necessarily the 124 number of running nameservers). This is useful for double-checking 125 whether our calls to the various nameserver configuration functions 126 have been successful. 127 128 @deprecated This function is deprecated because it does not allow the 129 caller to specify which evdns_base it applies to. The recommended 130 function is evdns_base_count_nameservers(). 131 132 @return the number of configured nameservers 133 @see evdns_nameserver_add() 134 */ 135 EVENT2_EXPORT_SYMBOL 136 int evdns_count_nameservers(void); 137 138 /** 139 Remove all configured nameservers, and suspend all pending resolves. 140 141 Resolves will not necessarily be re-attempted until evdns_resume() is called. 142 143 @deprecated This function is deprecated because it does not allow the 144 caller to specify which evdns_base it applies to. The recommended 145 function is evdns_base_clear_nameservers_and_suspend(). 146 147 @return 0 if successful, or -1 if an error occurred 148 @see evdns_resume() 149 */ 150 EVENT2_EXPORT_SYMBOL 151 int evdns_clear_nameservers_and_suspend(void); 152 153 /** 154 Resume normal operation and continue any suspended resolve requests. 155 156 Re-attempt resolves left in limbo after an earlier call to 157 evdns_clear_nameservers_and_suspend(). 158 159 @deprecated This function is deprecated because it does not allow the 160 caller to specify which evdns_base it applies to. The recommended 161 function is evdns_base_resume(). 162 163 @return 0 if successful, or -1 if an error occurred 164 @see evdns_clear_nameservers_and_suspend() 165 */ 166 EVENT2_EXPORT_SYMBOL 167 int evdns_resume(void); 168 169 /** 170 Add a nameserver. 171 172 This wraps the evdns_nameserver_add() function by parsing a string as an IP 173 address and adds it as a nameserver. 174 175 @deprecated This function is deprecated because it does not allow the 176 caller to specify which evdns_base it applies to. The recommended 177 function is evdns_base_nameserver_ip_add(). 178 179 @return 0 if successful, or -1 if an error occurred 180 @see evdns_nameserver_add() 181 */ 182 EVENT2_EXPORT_SYMBOL 183 int evdns_nameserver_ip_add(const char *ip_as_string); 184 185 /** 186 Lookup an A record for a given name. 187 188 @deprecated This function is deprecated because it does not allow the 189 caller to specify which evdns_base it applies to. The recommended 190 function is evdns_base_resolve_ipv4(). 191 192 @param name a DNS hostname 193 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query. 194 @param callback a callback function to invoke when the request is completed 195 @param ptr an argument to pass to the callback function 196 @return 0 if successful, or -1 if an error occurred 197 @see evdns_resolve_ipv6(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6() 198 */ 199 EVENT2_EXPORT_SYMBOL 200 int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr); 201 202 /** 203 Lookup an AAAA record for a given name. 204 205 @param name a DNS hostname 206 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query. 207 @param callback a callback function to invoke when the request is completed 208 @param ptr an argument to pass to the callback function 209 @return 0 if successful, or -1 if an error occurred 210 @see evdns_resolve_ipv4(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6() 211 */ 212 EVENT2_EXPORT_SYMBOL 213 int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr); 214 215 struct in_addr; 216 struct in6_addr; 217 218 /** 219 Lookup a PTR record for a given IP address. 220 221 @deprecated This function is deprecated because it does not allow the 222 caller to specify which evdns_base it applies to. The recommended 223 function is evdns_base_resolve_reverse(). 224 225 @param in an IPv4 address 226 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query. 227 @param callback a callback function to invoke when the request is completed 228 @param ptr an argument to pass to the callback function 229 @return 0 if successful, or -1 if an error occurred 230 @see evdns_resolve_reverse_ipv6() 231 */ 232 EVENT2_EXPORT_SYMBOL 233 int evdns_resolve_reverse(const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr); 234 235 /** 236 Lookup a PTR record for a given IPv6 address. 237 238 @deprecated This function is deprecated because it does not allow the 239 caller to specify which evdns_base it applies to. The recommended 240 function is evdns_base_resolve_reverse_ipv6(). 241 242 @param in an IPv6 address 243 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query. 244 @param callback a callback function to invoke when the request is completed 245 @param ptr an argument to pass to the callback function 246 @return 0 if successful, or -1 if an error occurred 247 @see evdns_resolve_reverse_ipv6() 248 */ 249 EVENT2_EXPORT_SYMBOL 250 int evdns_resolve_reverse_ipv6(const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr); 251 252 /** 253 Set the value of a configuration option. 254 255 The currently available configuration options are: 256 257 ndots, timeout, max-timeouts, max-inflight, and attempts 258 259 @deprecated This function is deprecated because it does not allow the 260 caller to specify which evdns_base it applies to. The recommended 261 function is evdns_base_set_option(). 262 263 @param option the name of the configuration option to be modified 264 @param val the value to be set 265 @param flags Ignored. 266 @return 0 if successful, or -1 if an error occurred 267 */ 268 EVENT2_EXPORT_SYMBOL 269 int evdns_set_option(const char *option, const char *val, int flags); 270 271 /** 272 Parse a resolv.conf file. 273 274 The 'flags' parameter determines what information is parsed from the 275 resolv.conf file. See the man page for resolv.conf for the format of this 276 file. 277 278 The following directives are not parsed from the file: sortlist, rotate, 279 no-check-names, inet6, debug. 280 281 If this function encounters an error, the possible return values are: 1 = 282 failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of 283 memory, 5 = short read from file, 6 = no nameservers listed in the file 284 285 @deprecated This function is deprecated because it does not allow the 286 caller to specify which evdns_base it applies to. The recommended 287 function is evdns_base_resolv_conf_parse(). 288 289 @param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC| 290 DNS_OPTIONS_ALL 291 @param filename the path to the resolv.conf file 292 @return 0 if successful, or various positive error codes if an error 293 occurred (see above) 294 @see resolv.conf(3), evdns_config_windows_nameservers() 295 */ 296 EVENT2_EXPORT_SYMBOL 297 int evdns_resolv_conf_parse(int flags, const char *const filename); 298 299 /** 300 Clear the list of search domains. 301 302 @deprecated This function is deprecated because it does not allow the 303 caller to specify which evdns_base it applies to. The recommended 304 function is evdns_base_search_clear(). 305 */ 306 EVENT2_EXPORT_SYMBOL 307 void evdns_search_clear(void); 308 309 /** 310 Add a domain to the list of search domains 311 312 @deprecated This function is deprecated because it does not allow the 313 caller to specify which evdns_base it applies to. The recommended 314 function is evdns_base_search_add(). 315 316 @param domain the domain to be added to the search list 317 */ 318 EVENT2_EXPORT_SYMBOL 319 void evdns_search_add(const char *domain); 320 321 /** 322 Set the 'ndots' parameter for searches. 323 324 Sets the number of dots which, when found in a name, causes 325 the first query to be without any search domain. 326 327 @deprecated This function is deprecated because it does not allow the 328 caller to specify which evdns_base it applies to. The recommended 329 function is evdns_base_search_ndots_set(). 330 331 @param ndots the new ndots parameter 332 */ 333 EVENT2_EXPORT_SYMBOL 334 void evdns_search_ndots_set(const int ndots); 335 336 /** 337 As evdns_server_new_with_base. 338 339 @deprecated This function is deprecated because it does not allow the 340 caller to specify which even_base it uses. The recommended 341 function is evdns_add_server_port_with_base(). 342 343 */ 344 EVENT2_EXPORT_SYMBOL 345 struct evdns_server_port * 346 evdns_add_server_port(evutil_socket_t socket, int flags, 347 evdns_request_callback_fn_type callback, void *user_data); 348 349 #ifdef _WIN32 350 EVENT2_EXPORT_SYMBOL 351 int evdns_config_windows_nameservers(void); 352 #define EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED 353 #endif 354 355 #ifdef __cplusplus 356 } 357 #endif 358 359 #endif /* EVENT2_EVENT_COMPAT_H_INCLUDED_ */ 360