ares.h

   1 /* $Id$ */
   2
   3 /* Copyright 1998, 2009 by the Massachusetts Institute of Technology.
   4  * Copyright (C) 2007-2009 by Daniel Stenberg
   5  *
   6  * Permission to use, copy, modify, and distribute this
   7  * software and its documentation for any purpose and without
   8  * fee is hereby granted, provided that the above copyright
   9  * notice appear in all copies and that both that copyright
  10  * notice and this permission notice appear in supporting
  11  * documentation, and that the name of M.I.T. not be used in
  12  * advertising or publicity pertaining to distribution of the
  13  * software without specific, written prior permission.
  14  * M.I.T. makes no representations about the suitability of
  15  * this software for any purpose.  It is provided "as is"
  16  * without express or implied warranty.
  17  */
  18
  19 #ifndef ARES__H
  20 #define ARES__H
  21
  22 #include "ares_version.h"  /* c-ares version defines   */
  23 #include "ares_build.h"    /* c-ares build definitions */
  24 #include "ares_rules.h"    /* c-ares rules enforcement */
  25
  26 /*
  27  * Define WIN32 when build target is Win32 API
  28  */
  29
  30 #if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32)
  31 #define WIN32
  32 #endif
  33
  34 #include <sys/types.h>
  35
  36 /* HP-UX systems version 9, 10 and 11 lack sys/select.h and so does oldish
  37    libc5-based Linux systems. Only include it on system that are known to
  38    require it! */
  39 #if defined(_AIX) || defined(__NOVELL_LIBC__) || defined(__NetBSD__) || \
  40     defined(__minix) || defined(__SYMBIAN32__) || defined(__INTEGRITY)
  41 #include <sys/select.h>
  42 #endif
  43 #if (defined(NETWARE) && !defined(__NOVELL_LIBC__))
  44 #include <sys/bsdskt.h>
  45 #endif
  46
  47 #if defined(WATT32)
  48   #include <netinet/in.h>
  49   #include <sys/socket.h>
  50   #include <tcp.h>
  51 #elif defined(WIN32)
  52 #  ifndef WIN32_LEAN_AND_MEAN
  53 #    define WIN32_LEAN_AND_MEAN
  54 #  endif
  55 #  include <windows.h>
  56 #  include <winsock2.h>
  57 #  include <ws2tcpip.h>
  58 #else
  59   #include <sys/socket.h>
  60   #include <netinet/in.h>
  61 #endif
  62
  63 #ifdef  __cplusplus
  64 extern "C" {
  65 #endif
  66
  67 #define ARES_SUCCESS            0
  68
  69 /* Server error codes (ARES_ENODATA indicates no relevant answer) */
  70 #define ARES_ENODATA            1
  71 #define ARES_EFORMERR           2
  72 #define ARES_ESERVFAIL          3
  73 #define ARES_ENOTFOUND          4
  74 #define ARES_ENOTIMP            5
  75 #define ARES_EREFUSED           6
  76
  77 /* Locally generated error codes */
  78 #define ARES_EBADQUERY          7
  79 #define ARES_EBADNAME           8
  80 #define ARES_EBADFAMILY         9
  81 #define ARES_EBADRESP           10
  82 #define ARES_ECONNREFUSED       11
  83 #define ARES_ETIMEOUT           12
  84 #define ARES_EOF                13
  85 #define ARES_EFILE              14
  86 #define ARES_ENOMEM             15
  87 #define ARES_EDESTRUCTION       16
  88 #define ARES_EBADSTR            17
  89 #define ARES_ECANCELLED         21
  90
  91 /* ares_getnameinfo error codes */
  92 #define ARES_EBADFLAGS          18
  93
  94 /* ares_getaddrinfo error codes */
  95 #define ARES_ENONAME            19
  96 #define ARES_EBADHINTS          20
  97
  98 /* Uninitialized library error code */
  99 #define ARES_ENOTINITIALIZED    21
 100
 101 /* ares_library_init error codes */
 102 #define ARES_ELOADIPHLPAPI           22
 103 #define ARES_EADDRGETNETWORKPARAMS   23
 104
 105 /* Flag values */
 106 #define ARES_FLAG_USEVC         (1 << 0)
 107 #define ARES_FLAG_PRIMARY       (1 << 1)
 108 #define ARES_FLAG_IGNTC         (1 << 2)
 109 #define ARES_FLAG_NORECURSE     (1 << 3)
 110 #define ARES_FLAG_STAYOPEN      (1 << 4)
 111 #define ARES_FLAG_NOSEARCH      (1 << 5)
 112 #define ARES_FLAG_NOALIASES     (1 << 6)
 113 #define ARES_FLAG_NOCHECKRESP   (1 << 7)
 114
 115 /* Option mask values */
 116 #define ARES_OPT_FLAGS          (1 << 0)
 117 #define ARES_OPT_TIMEOUT        (1 << 1)
 118 #define ARES_OPT_TRIES          (1 << 2)
 119 #define ARES_OPT_NDOTS          (1 << 3)
 120 #define ARES_OPT_UDP_PORT       (1 << 4)
 121 #define ARES_OPT_TCP_PORT       (1 << 5)
 122 #define ARES_OPT_SERVERS        (1 << 6)
 123 #define ARES_OPT_DOMAINS        (1 << 7)
 124 #define ARES_OPT_LOOKUPS        (1 << 8)
 125 #define ARES_OPT_SOCK_STATE_CB  (1 << 9)
 126 #define ARES_OPT_SORTLIST       (1 << 10)
 127 #define ARES_OPT_SOCK_SNDBUF    (1 << 11)
 128 #define ARES_OPT_SOCK_RCVBUF    (1 << 12)
 129 #define ARES_OPT_TIMEOUTMS      (1 << 13)
 130 #define ARES_OPT_ROTATE         (1 << 14)
 131
 132 /* Nameinfo flag values */
 133 #define ARES_NI_NOFQDN                  (1 << 0)
 134 #define ARES_NI_NUMERICHOST             (1 << 1)
 135 #define ARES_NI_NAMEREQD                (1 << 2)
 136 #define ARES_NI_NUMERICSERV             (1 << 3)
 137 #define ARES_NI_DGRAM                   (1 << 4)
 138 #define ARES_NI_TCP                     0
 139 #define ARES_NI_UDP                     ARES_NI_DGRAM
 140 #define ARES_NI_SCTP                    (1 << 5)
 141 #define ARES_NI_DCCP                    (1 << 6)
 142 #define ARES_NI_NUMERICSCOPE            (1 << 7)
 143 #define ARES_NI_LOOKUPHOST              (1 << 8)
 144 #define ARES_NI_LOOKUPSERVICE           (1 << 9)
 145 /* Reserved for future use */
 146 #define ARES_NI_IDN                     (1 << 10)
 147 #define ARES_NI_IDN_ALLOW_UNASSIGNED    (1 << 11)
 148 #define ARES_NI_IDN_USE_STD3_ASCII_RULES (1 << 12)
 149
 150 /* Addrinfo flag values */
 151 #define ARES_AI_CANONNAME               (1 << 0)
 152 #define ARES_AI_NUMERICHOST             (1 << 1)
 153 #define ARES_AI_PASSIVE                 (1 << 2)
 154 #define ARES_AI_NUMERICSERV             (1 << 3)
 155 #define ARES_AI_V4MAPPED                (1 << 4)
 156 #define ARES_AI_ALL                     (1 << 5)
 157 #define ARES_AI_ADDRCONFIG              (1 << 6)
 158 /* Reserved for future use */
 159 #define ARES_AI_IDN                     (1 << 10)
 160 #define ARES_AI_IDN_ALLOW_UNASSIGNED    (1 << 11)
 161 #define ARES_AI_IDN_USE_STD3_ASCII_RULES (1 << 12)
 162 #define ARES_AI_CANONIDN                (1 << 13)
 163
 164 #define ARES_AI_MASK (ARES_AI_CANONNAME|ARES_AI_NUMERICHOST|ARES_AI_PASSIVE| \
 165                       ARES_AI_NUMERICSERV|ARES_AI_V4MAPPED|ARES_AI_ALL| \
 166                       ARES_AI_ADDRCONFIG)
 167 #define ARES_GETSOCK_MAXNUM 16 /* ares_getsock() can return info about this
 168                                   many sockets */
 169 #define ARES_GETSOCK_READABLE(bits,num) (bits & (1<< (num)))
 170 #define ARES_GETSOCK_WRITABLE(bits,num) (bits & (1 << ((num) + \
 171                                          ARES_GETSOCK_MAXNUM)))
 172
 173 /* c-ares library initialization flag values */
 174 #define ARES_LIB_INIT_NONE   (0)
 175 #define ARES_LIB_INIT_WIN32  (1 << 0)
 176 #define ARES_LIB_INIT_ALL    (ARES_LIB_INIT_WIN32)
 177
 178
 179 /*
 180  * Typedef our socket type
 181  */
 182
 183 #ifndef ares_socket_typedef
 184 #ifdef WIN32
 185 typedef SOCKET ares_socket_t;
 186 #define ARES_SOCKET_BAD INVALID_SOCKET
 187 #else
 188 typedef int ares_socket_t;
 189 #define ARES_SOCKET_BAD -1
 190 #endif
 191 #define ares_socket_typedef
 192 #endif /* ares_socket_typedef */
 193
 194 typedef void (*ares_sock_state_cb)(void *data,
 195                                    ares_socket_t socket_fd,
 196                                    int readable,
 197                                    int writable);
 198
 199 struct apattern;
 200
 201 /* NOTE about the ares_options struct to users and developers.
 202
 203    This struct will remain looking like this. It will not be extended nor
 204    shrunk in future releases, but all new options will be set by ares_set_*()
 205    options instead of with the ares_init_options() function.
 206
 207    Eventually (in a galaxy far far away), all options will be settable by
 208    ares_set_*() options and the ares_init_options() function will become
 209    deprecated.
 210
 211    When new options are added to c-ares, they are not added to this
 212    struct. And they are not "saved" with the ares_save_options() function but
 213    instead we encourage the use of the ares_dup() function. Needless to say,
 214    if you add config options to c-ares you need to make sure ares_dup()
 215    duplicates this new option.
 216
 217  */
 218 struct ares_options {
 219   int flags;
 220   int timeout; /* in seconds or milliseconds, depending on options */
 221   int tries;
 222   int ndots;
 223   unsigned short udp_port;
 224   unsigned short tcp_port;
 225   int socket_send_buffer_size;
 226   int socket_receive_buffer_size;
 227   struct in_addr *servers;
 228   int nservers;
 229   char **domains;
 230   int ndomains;
 231   char *lookups;
 232   ares_sock_state_cb sock_state_cb;
 233   void *sock_state_cb_data;
 234   struct apattern *sortlist;
 235   int nsort;
 236 };
 237
 238 struct hostent;
 239 struct timeval;
 240 struct sockaddr;
 241 struct ares_channeldata;
 242 typedef struct ares_channeldata *ares_channel;
 243 typedef void (*ares_callback)(void *arg, int status, int timeouts,
 244                               unsigned char *abuf, int alen);
 245 typedef void (*ares_host_callback)(void *arg, int status, int timeouts,
 246                                    struct hostent *hostent);
 247 typedef void (*ares_nameinfo_callback)(void *arg, int status, int timeouts,
 248                                        char *node, char *service);
 249 typedef int  (*ares_sock_create_callback)(ares_socket_t socket_fd,
 250                                           int type, void *data);
 251
 252 int ares_library_init(int flags);
 253 void ares_library_cleanup(void);
 254 const char *ares_version(int *version);
 255
 256 int ares_init(ares_channel *channelptr);
 257 int ares_init_options(ares_channel *channelptr, struct ares_options *options,
 258                       int optmask);
 259 int ares_save_options(ares_channel channel, struct ares_options *options,
 260                       int *optmask);
 261 void ares_destroy_options(struct ares_options *options);
 262 int ares_dup(ares_channel *dest, ares_channel src);
 263 void ares_destroy(ares_channel channel);
 264 void ares_cancel(ares_channel channel);
 265 void ares_set_socket_callback(ares_channel channel,
 266                               ares_sock_create_callback callback,
 267                               void *user_data);
 268 void ares_send(ares_channel channel, const unsigned char *qbuf, int qlen,
 269                ares_callback callback, void *arg);
 270 void ares_query(ares_channel channel, const char *name, int dnsclass,
 271                 int type, ares_callback callback, void *arg);
 272 void ares_search(ares_channel channel, const char *name, int dnsclass,
 273                  int type, ares_callback callback, void *arg);
 274 void ares_gethostbyname(ares_channel channel, const char *name, int family,
 275                         ares_host_callback callback, void *arg);
 276 int ares_gethostbyname_file(ares_channel channel, const char *name,
 277                             int family, struct hostent **host);
 278 void ares_gethostbyaddr(ares_channel channel, const void *addr, int addrlen,
 279                         int family, ares_host_callback callback, void *arg);
 280 void ares_getnameinfo(ares_channel channel, const struct sockaddr *sa,
 281                       ares_socklen_t salen, int flags,
 282                       ares_nameinfo_callback callback,
 283                       void *arg);
 284 int ares_fds(ares_channel channel, fd_set *read_fds, fd_set *write_fds);
 285 int ares_getsock(ares_channel channel, int *socks, int numsocks);
 286 struct timeval *ares_timeout(ares_channel channel, struct timeval *maxtv,
 287                              struct timeval *tv);
 288 void ares_process(ares_channel channel, fd_set *read_fds, fd_set *write_fds);
 289 void ares_process_fd(ares_channel channel, ares_socket_t read_fd,
 290                      ares_socket_t write_fd);
 291
 292 int ares_mkquery(const char *name, int dnsclass, int type, unsigned short id,
 293                  int rd, unsigned char **buf, int *buflen);
 294 int ares_expand_name(const unsigned char *encoded, const unsigned char *abuf,
 295                      int alen, char **s, long *enclen);
 296 int ares_expand_string(const unsigned char *encoded, const unsigned char *abuf,
 297                      int alen, unsigned char **s, long *enclen);
 298
 299 /*
 300  * NOTE: before c-ares 1.6.1 we would most often use the system in6_addr
 301  * struct below when ares itself was built, but many apps would use this
 302  * private version since the header checked a HAVE_* define for it. Starting
 303  * with 1.6.1 we always declare and use our own to stop relying on the
 304  * system's one.
 305  */
 306 struct ares_in6_addr {
 307   union {
 308     unsigned char _S6_u8[16];
 309   } _S6_un;
 310 };
 311
 312 /*
 313  * TODO: the structs 'addrttl' and 'addr6ttl' really should get their names
 314  * prefixed with ares_ to keep them in our own "name space".
 315  */
 316 struct addrttl {
 317   struct in_addr ipaddr;
 318   int            ttl;
 319 };
 320 struct addr6ttl {
 321   struct ares_in6_addr ip6addr;
 322   int             ttl;
 323 };
 324
 325 struct srv_reply {
 326   unsigned short weight;
 327   unsigned short priority;
 328   unsigned short port;
 329   char *host;
 330 };
 331
 332 /*
 333 ** Parse the buffer, starting at *abuf and of length alen bytes, previously
 334 ** obtained from an ares_search call.  Put the results in *host, if nonnull.
 335 ** Also, if addrttls is nonnull, put up to *naddrttls IPv4 addresses along with
 336 ** their TTLs in that array, and set *naddrttls to the number of addresses
 337 ** so written.
 338 */
 339 int ares_parse_a_reply(const unsigned char *abuf, int alen,
 340                        struct hostent **host,
 341                        struct addrttl *addrttls, int *naddrttls);
 342 int ares_parse_aaaa_reply(const unsigned char *abuf, int alen,
 343                           struct hostent **host,
 344                           struct addr6ttl *addrttls, int *naddrttls);
 345 int ares_parse_ptr_reply(const unsigned char *abuf, int alen, const void *addr,
 346                          int addrlen, int family, struct hostent **host);
 347 int ares_parse_ns_reply(const unsigned char *abuf, int alen,
 348                         struct hostent **host);
 349 int ares_parse_srv_reply(const unsigned char* abuf, int alen,
 350                          struct srv_reply** srv_out, int *nsrvreply);
 351 void ares_free_string(void *str);
 352 void ares_free_hostent(struct hostent *host);
 353 const char *ares_strerror(int code);
 354
 355 #ifdef  __cplusplus
 356 }
 357 #endif
 358
 359 #endif /* ARES__H */