contrib/ntp/sntp/libevent/include/event2/dns_compat.h

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