libevent/include/event2/dns_compat.h

   1 /*
   2  * Copyright (c) 2006-2007 Niels Provos <provos@citi.umich.edu>
   3  * Copyright (c) 2007-2010 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_
  28 #define _EVENT2_DNS_COMPAT_H_
  29
  30 /** @file 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 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 #include <event2/event-config.h>
  42 #ifdef _EVENT_HAVE_SYS_TYPES_H
  43 #include <sys/types.h>
  44 #endif
  45 #ifdef _EVENT_HAVE_SYS_TIME_H
  46 #include <sys/time.h>
  47 #endif
  48
  49 /* For int types. */
  50 #include <event2/util.h>
  51
  52 /**
  53   Initialize the asynchronous DNS library.
  54
  55   This function initializes support for non-blocking name resolution by
  56   calling evdns_resolv_conf_parse() on UNIX and
  57   evdns_config_windows_nameservers() on Windows.
  58
  59   @deprecated This function is deprecated because it always uses the current
  60     event base, and is easily confused by multiple calls to event_init(), and
  61     so is not safe for multithreaded use.  Additionally, it allocates a global
  62     structure that only one thread can use. The replacement is
  63     evdns_base_new().
  64
  65   @return 0 if successful, or -1 if an error occurred
  66   @see evdns_shutdown()
  67  */
  68 int evdns_init(void);
  69
  70 struct evdns_base;
  71 /**
  72    Return the global evdns_base created by event_init() and used by the other
  73    deprecated functions.
  74
  75    @deprecated This function is deprecated because use of the global
  76      evdns_base is error-prone.
  77  */
  78 struct evdns_base *evdns_get_global_base(void);
  79
  80 /**
  81   Shut down the asynchronous DNS resolver and terminate all active requests.
  82
  83   If the 'fail_requests' option is enabled, all active requests will return
  84   an empty result with the error flag set to DNS_ERR_SHUTDOWN. Otherwise,
  85   the requests will be silently discarded.
  86
  87   @deprecated This function is deprecated because it does not allow the
  88     caller to specify which evdns_base it applies to.  The recommended
  89     function is evdns_base_shutdown().
  90
  91   @param fail_requests if zero, active requests will be aborted; if non-zero,
  92                 active requests will return DNS_ERR_SHUTDOWN.
  93   @see evdns_init()
  94  */
  95 void evdns_shutdown(int fail_requests);
  96
  97 /**
  98   Add a nameserver.
  99
 100   The address should be an IPv4 address in network byte order.
 101   The type of address is chosen so that it matches in_addr.s_addr.
 102
 103   @deprecated This function is deprecated because it does not allow the
 104     caller to specify which evdns_base it applies to.  The recommended
 105     function is evdns_base_nameserver_add().
 106
 107   @param address an IP address in network byte order
 108   @return 0 if successful, or -1 if an error occurred
 109   @see evdns_nameserver_ip_add()
 110  */
 111 int evdns_nameserver_add(unsigned long int address);
 112
 113 /**
 114   Get the number of configured nameservers.
 115
 116   This returns the number of configured nameservers (not necessarily the
 117   number of running nameservers).  This is useful for double-checking
 118   whether our calls to the various nameserver configuration functions
 119   have been successful.
 120
 121   @deprecated This function is deprecated because it does not allow the
 122     caller to specify which evdns_base it applies to.  The recommended
 123     function is evdns_base_count_nameservers().
 124
 125   @return the number of configured nameservers
 126   @see evdns_nameserver_add()
 127  */
 128 int evdns_count_nameservers(void);
 129
 130 /**
 131   Remove all configured nameservers, and suspend all pending resolves.
 132
 133   Resolves will not necessarily be re-attempted until evdns_resume() is called.
 134
 135   @deprecated This function is deprecated because it does not allow the
 136     caller to specify which evdns_base it applies to.  The recommended
 137     function is evdns_base_clear_nameservers_and_suspend().
 138
 139   @return 0 if successful, or -1 if an error occurred
 140   @see evdns_resume()
 141  */
 142 int evdns_clear_nameservers_and_suspend(void);
 143
 144 /**
 145   Resume normal operation and continue any suspended resolve requests.
 146
 147   Re-attempt resolves left in limbo after an earlier call to
 148   evdns_clear_nameservers_and_suspend().
 149
 150   @deprecated This function is deprecated because it does not allow the
 151     caller to specify which evdns_base it applies to.  The recommended
 152     function is evdns_base_resume().
 153
 154   @return 0 if successful, or -1 if an error occurred
 155   @see evdns_clear_nameservers_and_suspend()
 156  */
 157 int evdns_resume(void);
 158
 159 /**
 160   Add a nameserver.
 161
 162   This wraps the evdns_nameserver_add() function by parsing a string as an IP
 163   address and adds it as a nameserver.
 164
 165   @deprecated This function is deprecated because it does not allow the
 166     caller to specify which evdns_base it applies to.  The recommended
 167     function is evdns_base_nameserver_ip_add().
 168
 169   @return 0 if successful, or -1 if an error occurred
 170   @see evdns_nameserver_add()
 171  */
 172 int evdns_nameserver_ip_add(const char *ip_as_string);
 173
 174 /**
 175   Lookup an A record for a given name.
 176
 177   @deprecated This function is deprecated because it does not allow the
 178     caller to specify which evdns_base it applies to.  The recommended
 179     function is evdns_base_resolve_ipv4().
 180
 181   @param name a DNS hostname
 182   @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
 183   @param callback a callback function to invoke when the request is completed
 184   @param ptr an argument to pass to the callback function
 185   @return 0 if successful, or -1 if an error occurred
 186   @see evdns_resolve_ipv6(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6()
 187  */
 188 int evdns_resolve_ipv4(const char *name, int flags, evdns_callback_type callback, void *ptr);
 189
 190 /**
 191   Lookup an AAAA record for a given name.
 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_ipv4(), evdns_resolve_reverse(), evdns_resolve_reverse_ipv6()
 199  */
 200 int evdns_resolve_ipv6(const char *name, int flags, evdns_callback_type callback, void *ptr);
 201
 202 struct in_addr;
 203 struct in6_addr;
 204
 205 /**
 206   Lookup a PTR record for a given IP address.
 207
 208   @deprecated This function is deprecated because it does not allow the
 209     caller to specify which evdns_base it applies to.  The recommended
 210     function is evdns_base_resolve_reverse().
 211
 212   @param in an IPv4 address
 213   @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
 214   @param callback a callback function to invoke when the request is completed
 215   @param ptr an argument to pass to the callback function
 216   @return 0 if successful, or -1 if an error occurred
 217   @see evdns_resolve_reverse_ipv6()
 218  */
 219 int evdns_resolve_reverse(const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr);
 220
 221 /**
 222   Lookup a PTR record for a given IPv6 address.
 223
 224   @deprecated This function is deprecated because it does not allow the
 225     caller to specify which evdns_base it applies to.  The recommended
 226     function is evdns_base_resolve_reverse_ipv6().
 227
 228   @param in an IPv6 address
 229   @param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
 230   @param callback a callback function to invoke when the request is completed
 231   @param ptr an argument to pass to the callback function
 232   @return 0 if successful, or -1 if an error occurred
 233   @see evdns_resolve_reverse_ipv6()
 234  */
 235 int evdns_resolve_reverse_ipv6(const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr);
 236
 237 /**
 238   Set the value of a configuration option.
 239
 240   The currently available configuration options are:
 241
 242     ndots, timeout, max-timeouts, max-inflight, and attempts
 243
 244   @deprecated This function is deprecated because it does not allow the
 245     caller to specify which evdns_base it applies to.  The recommended
 246     function is evdns_base_set_option().
 247
 248   @param option the name of the configuration option to be modified
 249   @param val the value to be set
 250   @param flags Ignored.
 251   @return 0 if successful, or -1 if an error occurred
 252  */
 253 int evdns_set_option(const char *option, const char *val, int flags);
 254
 255 /**
 256   Parse a resolv.conf file.
 257
 258   The 'flags' parameter determines what information is parsed from the
 259   resolv.conf file. See the man page for resolv.conf for the format of this
 260   file.
 261
 262   The following directives are not parsed from the file: sortlist, rotate,
 263   no-check-names, inet6, debug.
 264
 265   If this function encounters an error, the possible return values are: 1 =
 266   failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of
 267   memory, 5 = short read from file, 6 = no nameservers listed in the file
 268
 269   @deprecated This function is deprecated because it does not allow the
 270     caller to specify which evdns_base it applies to.  The recommended
 271     function is evdns_base_resolv_conf_parse().
 272
 273   @param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC|
 274     DNS_OPTIONS_ALL
 275   @param filename the path to the resolv.conf file
 276   @return 0 if successful, or various positive error codes if an error
 277     occurred (see above)
 278   @see resolv.conf(3), evdns_config_windows_nameservers()
 279  */
 280 int evdns_resolv_conf_parse(int flags, const char *const filename);
 281
 282 /**
 283   Clear the list of search domains.
 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_search_clear().
 288  */
 289 void evdns_search_clear(void);
 290
 291 /**
 292   Add a domain to the list of search domains
 293
 294   @deprecated This function is deprecated because it does not allow the
 295     caller to specify which evdns_base it applies to.  The recommended
 296     function is evdns_base_search_add().
 297
 298   @param domain the domain to be added to the search list
 299  */
 300 void evdns_search_add(const char *domain);
 301
 302 /**
 303   Set the 'ndots' parameter for searches.
 304
 305   Sets the number of dots which, when found in a name, causes
 306   the first query to be without any search domain.
 307
 308   @deprecated This function is deprecated because it does not allow the
 309     caller to specify which evdns_base it applies to.  The recommended
 310     function is evdns_base_search_ndots_set().
 311
 312   @param ndots the new ndots parameter
 313  */
 314 void evdns_search_ndots_set(const int ndots);
 315
 316 /**
 317    As evdns_server_new_with_base.
 318
 319   @deprecated This function is deprecated because it does not allow the
 320     caller to specify which even_base it uses.  The recommended
 321     function is evdns_add_server_port_with_base().
 322
 323 */
 324 struct evdns_server_port *evdns_add_server_port(evutil_socket_t socket, int flags, evdns_request_callback_fn_type callback, void *user_data);
 325
 326 #ifdef WIN32
 327 int evdns_config_windows_nameservers(void);
 328 #define EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED
 329 #endif
 330
 331 #ifdef __cplusplus
 332 }
 333 #endif
 334
 335 #endif /* _EVENT2_EVENT_COMPAT_H_ */