dns_compat.h revision 1.4
1/* $NetBSD: dns_compat.h,v 1.4 2016/01/08 21:35:41 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 41extern "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 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 */ 71int evdns_init(void); 72 73struct 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 */ 81struct evdns_base *evdns_get_global_base(void); 82 83/** 84 Shut down the asynchronous DNS resolver and terminate all active requests. 85 86 If the 'fail_requests' option is enabled, all active requests will return 87 an empty result with the error flag set to DNS_ERR_SHUTDOWN. Otherwise, 88 the requests will be silently discarded. 89 90 @deprecated This function is deprecated because it does not allow the 91 caller to specify which evdns_base it applies to. The recommended 92 function is evdns_base_shutdown(). 93 94 @param fail_requests if zero, active requests will be aborted; if non-zero, 95 active requests will return DNS_ERR_SHUTDOWN. 96 @see evdns_init() 97 */ 98void evdns_shutdown(int fail_requests); 99 100/** 101 Add a nameserver. 102 103 The address should be an IPv4 address in network byte order. 104 The type of address is chosen so that it matches in_addr.s_addr. 105 106 @deprecated This function is deprecated because it does not allow the 107 caller to specify which evdns_base it applies to. The recommended 108 function is evdns_base_nameserver_add(). 109 110 @param address an IP address in network byte order 111 @return 0 if successful, or -1 if an error occurred 112 @see evdns_nameserver_ip_add() 113 */ 114int evdns_nameserver_add(unsigned long int address); 115 116/** 117 Get the number of configured nameservers. 118 119 This returns the number of configured nameservers (not necessarily the 120 number of running nameservers). This is useful for double-checking 121 whether our calls to the various nameserver configuration functions 122 have been successful. 123 124 @deprecated This function is deprecated because it does not allow the 125 caller to specify which evdns_base it applies to. The recommended 126 function is evdns_base_count_nameservers(). 127 128 @return the number of configured nameservers 129 @see evdns_nameserver_add() 130 */ 131int evdns_count_nameservers(void); 132 133/** 134 Remove all configured nameservers, and suspend all pending resolves. 135 136 Resolves will not necessarily be re-attempted until evdns_resume() is called. 137 138 @deprecated This function is deprecated because it does not allow the 139 caller to specify which evdns_base it applies to. The recommended 140 function is evdns_base_clear_nameservers_and_suspend(). 141 142 @return 0 if successful, or -1 if an error occurred 143 @see evdns_resume() 144 */ 145int evdns_clear_nameservers_and_suspend(void); 146 147/** 148 Resume normal operation and continue any suspended resolve requests. 149 150 Re-attempt resolves left in limbo after an earlier call to 151 evdns_clear_nameservers_and_suspend(). 152 153 @deprecated This function is deprecated because it does not allow the 154 caller to specify which evdns_base it applies to. The recommended 155 function is evdns_base_resume(). 156 157 @return 0 if successful, or -1 if an error occurred 158 @see evdns_clear_nameservers_and_suspend() 159 */ 160int evdns_resume(void); 161 162/** 163 Add a nameserver. 164 165 This wraps the evdns_nameserver_add() function by parsing a string as an IP 166 address and adds it as a nameserver. 167 168 @deprecated This function is deprecated because it does not allow the 169 caller to specify which evdns_base it applies to. The recommended 170 function is evdns_base_nameserver_ip_add(). 171 172 @return 0 if successful, or -1 if an error occurred 173 @see evdns_nameserver_add() 174 */ 175int evdns_nameserver_ip_add(const char *ip_as_string); 176 177/** 178 Lookup an A record for a given name. 179 180 @deprecated This function is deprecated because it does not allow the 181 caller to specify which evdns_base it applies to. The recommended 182 function is evdns_base_resolve_ipv4(). 183 184 @param name a DNS hostname 185 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query. 186 @param callback a callback function to invoke when the request is completed 187 @param ptr an argument to pass to the callback function 188 @return 0 if successful, or -1 if an error occurred 189 @see evdns_resolve_ipv6(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6() 190 */ 191int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr); 192 193/** 194 Lookup an AAAA record for a given name. 195 196 @param name a DNS hostname 197 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query. 198 @param callback a callback function to invoke when the request is completed 199 @param ptr an argument to pass to the callback function 200 @return 0 if successful, or -1 if an error occurred 201 @see evdns_resolve_ipv4(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6() 202 */ 203int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr); 204 205struct in_addr; 206struct in6_addr; 207 208/** 209 Lookup a PTR record for a given IP address. 210 211 @deprecated This function is deprecated because it does not allow the 212 caller to specify which evdns_base it applies to. The recommended 213 function is evdns_base_resolve_reverse(). 214 215 @param in an IPv4 address 216 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query. 217 @param callback a callback function to invoke when the request is completed 218 @param ptr an argument to pass to the callback function 219 @return 0 if successful, or -1 if an error occurred 220 @see evdns_resolve_reverse_ipv6() 221 */ 222int evdns_resolve_reverse(const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr); 223 224/** 225 Lookup a PTR record for a given IPv6 address. 226 227 @deprecated This function is deprecated because it does not allow the 228 caller to specify which evdns_base it applies to. The recommended 229 function is evdns_base_resolve_reverse_ipv6(). 230 231 @param in an IPv6 address 232 @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query. 233 @param callback a callback function to invoke when the request is completed 234 @param ptr an argument to pass to the callback function 235 @return 0 if successful, or -1 if an error occurred 236 @see evdns_resolve_reverse_ipv6() 237 */ 238int evdns_resolve_reverse_ipv6(const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr); 239 240/** 241 Set the value of a configuration option. 242 243 The currently available configuration options are: 244 245 ndots, timeout, max-timeouts, max-inflight, and attempts 246 247 @deprecated This function is deprecated because it does not allow the 248 caller to specify which evdns_base it applies to. The recommended 249 function is evdns_base_set_option(). 250 251 @param option the name of the configuration option to be modified 252 @param val the value to be set 253 @param flags Ignored. 254 @return 0 if successful, or -1 if an error occurred 255 */ 256int evdns_set_option(const char *option, const char *val, int flags); 257 258/** 259 Parse a resolv.conf file. 260 261 The 'flags' parameter determines what information is parsed from the 262 resolv.conf file. See the man page for resolv.conf for the format of this 263 file. 264 265 The following directives are not parsed from the file: sortlist, rotate, 266 no-check-names, inet6, debug. 267 268 If this function encounters an error, the possible return values are: 1 = 269 failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of 270 memory, 5 = short read from file, 6 = no nameservers listed in the file 271 272 @deprecated This function is deprecated because it does not allow the 273 caller to specify which evdns_base it applies to. The recommended 274 function is evdns_base_resolv_conf_parse(). 275 276 @param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC| 277 DNS_OPTIONS_ALL 278 @param filename the path to the resolv.conf file 279 @return 0 if successful, or various positive error codes if an error 280 occurred (see above) 281 @see resolv.conf(3), evdns_config_windows_nameservers() 282 */ 283int evdns_resolv_conf_parse(int flags, const char *const filename); 284 285/** 286 Clear the list of search domains. 287 288 @deprecated This function is deprecated because it does not allow the 289 caller to specify which evdns_base it applies to. The recommended 290 function is evdns_base_search_clear(). 291 */ 292void evdns_search_clear(void); 293 294/** 295 Add a domain to the list of search domains 296 297 @deprecated This function is deprecated because it does not allow the 298 caller to specify which evdns_base it applies to. The recommended 299 function is evdns_base_search_add(). 300 301 @param domain the domain to be added to the search list 302 */ 303void evdns_search_add(const char *domain); 304 305/** 306 Set the 'ndots' parameter for searches. 307 308 Sets the number of dots which, when found in a name, causes 309 the first query to be without any search domain. 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_ndots_set(). 314 315 @param ndots the new ndots parameter 316 */ 317void evdns_search_ndots_set(const int ndots); 318 319/** 320 As evdns_server_new_with_base. 321 322 @deprecated This function is deprecated because it does not allow the 323 caller to specify which even_base it uses. The recommended 324 function is evdns_add_server_port_with_base(). 325 326*/ 327struct evdns_server_port *evdns_add_server_port(evutil_socket_t socket, int flags, evdns_request_callback_fn_type callback, void *user_data); 328 329#ifdef _WIN32 330int evdns_config_windows_nameservers(void); 331#define EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED 332#endif 333 334#ifdef __cplusplus 335} 336#endif 337 338#endif /* EVENT2_EVENT_COMPAT_H_INCLUDED_ */ 339