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