external/bsd/libevent/dist/include/event2/dns_compat.h

   1 /*      $NetBSD: dns_compat.h,v 1.1.1.2 2015/01/29 06:38:27 spz Exp $   */
   2 /*      $NetBSD: dns_compat.h,v 1.1.1.2 2015/01/29 06:38:27 spz Exp $   */
   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_
  30 #define _EVENT2_DNS_COMPAT_H_
  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
  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 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 struct 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  */
  98 void 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  */
 114 int 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  */
 131 int 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  */
 145 int 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  */
 160 int 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  */
 175 int 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  */
 191 int 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  */
 203 int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
 204
 205 struct in_addr;
 206 struct 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  */
 222 int 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  */
 238 int 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  */
 256 int 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  */
 283 int 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  */
 292 void 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  */
 303 void 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  */
 317 void 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 */
 327 struct 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
 330 int 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_ */