ares.h

   1
   2 /* Copyright 1998, 2009 by the Massachusetts Institute of Technology.
   3  * Copyright (C) 2007-2011 by Daniel Stenberg
   4  *
   5  * Permission to use, copy, modify, and distribute this
   6  * software and its documentation for any purpose and without
   7  * fee is hereby granted, provided that the above copyright
   8  * notice appear in all copies and that both that copyright
   9  * notice and this permission notice appear in supporting
  10  * documentation, and that the name of M.I.T. not be used in
  11  * advertising or publicity pertaining to distribution of the
  12  * software without specific, written prior permission.
  13  * M.I.T. makes no representations about the suitability of
  14  * this software for any purpose.  It is provided "as is"
  15  * without express or implied warranty.
  16  */
  17
  18 #ifndef ARES__H
  19 #define ARES__H
  20
  21 #include "ares_version.h"  /* c-ares version defines   */
  22 #include "ares_build.h"    /* c-ares build definitions */
  23 #include "ares_rules.h"    /* c-ares rules enforcement */
  24
  25 /*
  26  * Define WIN32 when build target is Win32 API
  27  */
  28
  29 #if (defined(_WIN32) || defined(__WIN32__)) && \
  30    !defined(WIN32) && !defined(__SYMBIAN32__)
  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_WCE)
  52 #  ifndef WIN32_LEAN_AND_MEAN
  53 #    define WIN32_LEAN_AND_MEAN
  54 #  endif
  55 #  include <windows.h>
  56 #  include <winsock.h>
  57 #elif defined(WIN32)
  58 #  ifndef WIN32_LEAN_AND_MEAN
  59 #    define WIN32_LEAN_AND_MEAN
  60 #  endif
  61 #  include <windows.h>
  62 #  include <winsock2.h>
  63 #  include <ws2tcpip.h>
  64 #else
  65 #  include <sys/socket.h>
  66 #  include <netinet/in.h>
  67 #endif
  68
  69 #ifdef  __cplusplus
  70 extern "C" {
  71 #endif
  72
  73 /*
  74 ** c-ares external API function linkage decorations.
  75 */
  76
  77 #if !defined(CARES_STATICLIB) && \
  78    (defined(WIN32) || defined(_WIN32) || defined(__SYMBIAN32__))
  79    /* __declspec function decoration for Win32 and Symbian DLL's */
  80 #  if defined(CARES_BUILDING_LIBRARY)
  81 #    define CARES_EXTERN  __declspec(dllexport)
  82 #  else
  83 #    define CARES_EXTERN  __declspec(dllimport)
  84 #  endif
  85 #else
  86    /* visibility function decoration for other cases */
  87 #  if !defined(CARES_SYMBOL_HIDING) || \
  88      defined(WIN32) || defined(_WIN32) || defined(__SYMBIAN32__)
  89 #    define CARES_EXTERN
  90 #  else
  91 #    define CARES_EXTERN CARES_SYMBOL_SCOPE_EXTERN
  92 #  endif
  93 #endif
  94
  95
  96 #define ARES_SUCCESS            0
  97
  98 /* Server error codes (ARES_ENODATA indicates no relevant answer) */
  99 #define ARES_ENODATA            1
 100 #define ARES_EFORMERR           2
 101 #define ARES_ESERVFAIL          3
 102 #define ARES_ENOTFOUND          4
 103 #define ARES_ENOTIMP            5
 104 #define ARES_EREFUSED           6
 105
 106 /* Locally generated error codes */
 107 #define ARES_EBADQUERY          7
 108 #define ARES_EBADNAME           8
 109 #define ARES_EBADFAMILY         9
 110 #define ARES_EBADRESP           10
 111 #define ARES_ECONNREFUSED       11
 112 #define ARES_ETIMEOUT           12
 113 #define ARES_EOF                13
 114 #define ARES_EFILE              14
 115 #define ARES_ENOMEM             15
 116 #define ARES_EDESTRUCTION       16
 117 #define ARES_EBADSTR            17
 118
 119 /* ares_getnameinfo error codes */
 120 #define ARES_EBADFLAGS          18
 121
 122 /* ares_getaddrinfo error codes */
 123 #define ARES_ENONAME            19
 124 #define ARES_EBADHINTS          20
 125
 126 /* Uninitialized library error code */
 127 #define ARES_ENOTINITIALIZED    21          /* introduced in 1.7.0 */
 128
 129 /* ares_library_init error codes */
 130 #define ARES_ELOADIPHLPAPI           22     /* introduced in 1.7.0 */
 131 #define ARES_EADDRGETNETWORKPARAMS   23     /* introduced in 1.7.0 */
 132
 133 /* More error codes */
 134 #define ARES_ECANCELLED         24          /* introduced in 1.7.0 */
 135
 136 /* Flag values */
 137 #define ARES_FLAG_USEVC         (1 << 0)
 138 #define ARES_FLAG_PRIMARY       (1 << 1)
 139 #define ARES_FLAG_IGNTC         (1 << 2)
 140 #define ARES_FLAG_NORECURSE     (1 << 3)
 141 #define ARES_FLAG_STAYOPEN      (1 << 4)
 142 #define ARES_FLAG_NOSEARCH      (1 << 5)
 143 #define ARES_FLAG_NOALIASES     (1 << 6)
 144 #define ARES_FLAG_NOCHECKRESP   (1 << 7)
 145
 146 /* Option mask values */
 147 #define ARES_OPT_FLAGS          (1 << 0)
 148 #define ARES_OPT_TIMEOUT        (1 << 1)
 149 #define ARES_OPT_TRIES          (1 << 2)
 150 #define ARES_OPT_NDOTS          (1 << 3)
 151 #define ARES_OPT_UDP_PORT       (1 << 4)
 152 #define ARES_OPT_TCP_PORT       (1 << 5)
 153 #define ARES_OPT_SERVERS        (1 << 6)
 154 #define ARES_OPT_DOMAINS        (1 << 7)
 155 #define ARES_OPT_LOOKUPS        (1 << 8)
 156 #define ARES_OPT_SOCK_STATE_CB  (1 << 9)
 157 #define ARES_OPT_SORTLIST       (1 << 10)
 158 #define ARES_OPT_SOCK_SNDBUF    (1 << 11)
 159 #define ARES_OPT_SOCK_RCVBUF    (1 << 12)
 160 #define ARES_OPT_TIMEOUTMS      (1 << 13)
 161 #define ARES_OPT_ROTATE         (1 << 14)
 162
 163 /* Nameinfo flag values */
 164 #define ARES_NI_NOFQDN                  (1 << 0)
 165 #define ARES_NI_NUMERICHOST             (1 << 1)
 166 #define ARES_NI_NAMEREQD                (1 << 2)
 167 #define ARES_NI_NUMERICSERV             (1 << 3)
 168 #define ARES_NI_DGRAM                   (1 << 4)
 169 #define ARES_NI_TCP                     0
 170 #define ARES_NI_UDP                     ARES_NI_DGRAM
 171 #define ARES_NI_SCTP                    (1 << 5)
 172 #define ARES_NI_DCCP                    (1 << 6)
 173 #define ARES_NI_NUMERICSCOPE            (1 << 7)
 174 #define ARES_NI_LOOKUPHOST              (1 << 8)
 175 #define ARES_NI_LOOKUPSERVICE           (1 << 9)
 176 /* Reserved for future use */
 177 #define ARES_NI_IDN                     (1 << 10)
 178 #define ARES_NI_IDN_ALLOW_UNASSIGNED    (1 << 11)
 179 #define ARES_NI_IDN_USE_STD3_ASCII_RULES (1 << 12)
 180
 181 /* Addrinfo flag values */
 182 #define ARES_AI_CANONNAME               (1 << 0)
 183 #define ARES_AI_NUMERICHOST             (1 << 1)
 184 #define ARES_AI_PASSIVE                 (1 << 2)
 185 #define ARES_AI_NUMERICSERV             (1 << 3)
 186 #define ARES_AI_V4MAPPED                (1 << 4)
 187 #define ARES_AI_ALL                     (1 << 5)
 188 #define ARES_AI_ADDRCONFIG              (1 << 6)
 189 /* Reserved for future use */
 190 #define ARES_AI_IDN                     (1 << 10)
 191 #define ARES_AI_IDN_ALLOW_UNASSIGNED    (1 << 11)
 192 #define ARES_AI_IDN_USE_STD3_ASCII_RULES (1 << 12)
 193 #define ARES_AI_CANONIDN                (1 << 13)
 194
 195 #define ARES_AI_MASK (ARES_AI_CANONNAME|ARES_AI_NUMERICHOST|ARES_AI_PASSIVE| \
 196                       ARES_AI_NUMERICSERV|ARES_AI_V4MAPPED|ARES_AI_ALL| \
 197                       ARES_AI_ADDRCONFIG)
 198 #define ARES_GETSOCK_MAXNUM 16 /* ares_getsock() can return info about this
 199                                   many sockets */
 200 #define ARES_GETSOCK_READABLE(bits,num) (bits & (1<< (num)))
 201 #define ARES_GETSOCK_WRITABLE(bits,num) (bits & (1 << ((num) + \
 202                                          ARES_GETSOCK_MAXNUM)))
 203
 204 /* c-ares library initialization flag values */
 205 #define ARES_LIB_INIT_NONE   (0)
 206 #define ARES_LIB_INIT_WIN32  (1 << 0)
 207 #define ARES_LIB_INIT_ALL    (ARES_LIB_INIT_WIN32)
 208
 209
 210 /*
 211  * Typedef our socket type
 212  */
 213
 214 #ifndef ares_socket_typedef
 215 #ifdef WIN32
 216 typedef SOCKET ares_socket_t;
 217 #define ARES_SOCKET_BAD INVALID_SOCKET
 218 #else
 219 typedef int ares_socket_t;
 220 #define ARES_SOCKET_BAD -1
 221 #endif
 222 #define ares_socket_typedef
 223 #endif /* ares_socket_typedef */
 224
 225 typedef void (*ares_sock_state_cb)(void *data,
 226                                    ares_socket_t socket_fd,
 227                                    int readable,
 228                                    int writable);
 229
 230 struct apattern;
 231
 232 /* NOTE about the ares_options struct to users and developers.
 233
 234    This struct will remain looking like this. It will not be extended nor
 235    shrunk in future releases, but all new options will be set by ares_set_*()
 236    options instead of with the ares_init_options() function.
 237
 238    Eventually (in a galaxy far far away), all options will be settable by
 239    ares_set_*() options and the ares_init_options() function will become
 240    deprecated.
 241
 242    When new options are added to c-ares, they are not added to this
 243    struct. And they are not "saved" with the ares_save_options() function but
 244    instead we encourage the use of the ares_dup() function. Needless to say,
 245    if you add config options to c-ares you need to make sure ares_dup()
 246    duplicates this new option.
 247
 248  */
 249 struct ares_options {
 250   int flags;
 251   int timeout; /* in seconds or milliseconds, depending on options */
 252   int tries;
 253   int ndots;
 254   unsigned short udp_port;
 255   unsigned short tcp_port;
 256   int socket_send_buffer_size;
 257   int socket_receive_buffer_size;
 258   struct in_addr *servers;
 259   int nservers;
 260   char **domains;
 261   int ndomains;
 262   char *lookups;
 263   ares_sock_state_cb sock_state_cb;
 264   void *sock_state_cb_data;
 265   struct apattern *sortlist;
 266   int nsort;
 267 };
 268
 269 struct hostent;
 270 struct timeval;
 271 struct sockaddr;
 272 struct ares_channeldata;
 273
 274 typedef struct ares_channeldata *ares_channel;
 275
 276 typedef void (*ares_callback)(void *arg,
 277                               int status,
 278                               int timeouts,
 279                               unsigned char *abuf,
 280                               int alen);
 281
 282 typedef void (*ares_host_callback)(void *arg,
 283                                    int status,
 284                                    int timeouts,
 285                                    struct hostent *hostent);
 286
 287 typedef void (*ares_nameinfo_callback)(void *arg,
 288                                        int status,
 289                                        int timeouts,
 290                                        char *node,
 291                                        char *service);
 292
 293 typedef int  (*ares_sock_create_callback)(ares_socket_t socket_fd,
 294                                           int type,
 295                                           void *data);
 296
 297 CARES_EXTERN int ares_library_init(int flags);
 298
 299 CARES_EXTERN void ares_library_cleanup(void);
 300
 301 CARES_EXTERN const char *ares_version(int *version);
 302
 303 CARES_EXTERN int ares_init(ares_channel *channelptr);
 304
 305 CARES_EXTERN int ares_init_options(ares_channel *channelptr,
 306                                    struct ares_options *options,
 307                                    int optmask);
 308
 309 CARES_EXTERN int ares_save_options(ares_channel channel,
 310                                    struct ares_options *options,
 311                                    int *optmask);
 312
 313 CARES_EXTERN void ares_destroy_options(struct ares_options *options);
 314
 315 CARES_EXTERN int ares_dup(ares_channel *dest,
 316                           ares_channel src);
 317
 318 CARES_EXTERN void ares_destroy(ares_channel channel);
 319
 320 CARES_EXTERN void ares_cancel(ares_channel channel);
 321
 322 /* These next 3 configure local binding for the out-going socket
 323  * connection.  Use these to specify source IP and/or network device
 324  * on multi-homed systems.
 325  */
 326 CARES_EXTERN void ares_set_local_ip4(ares_channel channel, unsigned int local_ip);
 327
 328 /* local_ip6 should be 16 bytes in length */
 329 CARES_EXTERN void ares_set_local_ip6(ares_channel channel,
 330                                      const unsigned char* local_ip6);
 331
 332 /* local_dev_name should be null terminated. */
 333 CARES_EXTERN void ares_set_local_dev(ares_channel channel,
 334                                      const char* local_dev_name);
 335
 336 CARES_EXTERN void ares_set_socket_callback(ares_channel channel,
 337                                            ares_sock_create_callback callback,
 338                                            void *user_data);
 339
 340 CARES_EXTERN void ares_send(ares_channel channel,
 341                             const unsigned char *qbuf,
 342                             int qlen,
 343                             ares_callback callback,
 344                             void *arg);
 345
 346 CARES_EXTERN void ares_query(ares_channel channel,
 347                              const char *name,
 348                              int dnsclass,
 349                              int type,
 350                              ares_callback callback,
 351                              void *arg);
 352
 353 CARES_EXTERN void ares_search(ares_channel channel,
 354                               const char *name,
 355                               int dnsclass,
 356                               int type,
 357                               ares_callback callback,
 358                               void *arg);
 359
 360 CARES_EXTERN void ares_gethostbyname(ares_channel channel,
 361                                      const char *name,
 362                                      int family,
 363                                      ares_host_callback callback,
 364                                      void *arg);
 365
 366 CARES_EXTERN int ares_gethostbyname_file(ares_channel channel,
 367                                          const char *name,
 368                                          int family,
 369                                          struct hostent **host);
 370
 371 CARES_EXTERN void ares_gethostbyaddr(ares_channel channel,
 372                                      const void *addr,
 373                                      int addrlen,
 374                                      int family,
 375                                      ares_host_callback callback,
 376                                      void *arg);
 377
 378 CARES_EXTERN void ares_getnameinfo(ares_channel channel,
 379                                    const struct sockaddr *sa,
 380                                    ares_socklen_t salen,
 381                                    int flags,
 382                                    ares_nameinfo_callback callback,
 383                                    void *arg);
 384
 385 CARES_EXTERN int ares_fds(ares_channel channel,
 386                           fd_set *read_fds,
 387                           fd_set *write_fds);
 388
 389 CARES_EXTERN int ares_getsock(ares_channel channel,
 390                               ares_socket_t *socks,
 391                               int numsocks);
 392
 393 CARES_EXTERN struct timeval *ares_timeout(ares_channel channel,
 394                                           struct timeval *maxtv,
 395                                           struct timeval *tv);
 396
 397 CARES_EXTERN void ares_process(ares_channel channel,
 398                                fd_set *read_fds,
 399                                fd_set *write_fds);
 400
 401 CARES_EXTERN void ares_process_fd(ares_channel channel,
 402                                   ares_socket_t read_fd,
 403                                   ares_socket_t write_fd);
 404
 405 CARES_EXTERN int ares_mkquery(const char *name,
 406                               int dnsclass,
 407                               int type,
 408                               unsigned short id,
 409                               int rd,
 410                               unsigned char **buf,
 411                               int *buflen);
 412
 413 CARES_EXTERN int ares_expand_name(const unsigned char *encoded,
 414                                   const unsigned char *abuf,
 415                                   int alen,
 416                                   char **s,
 417                                   long *enclen);
 418
 419 CARES_EXTERN int ares_expand_string(const unsigned char *encoded,
 420                                     const unsigned char *abuf,
 421                                     int alen,
 422                                     unsigned char **s,
 423                                     long *enclen);
 424
 425 /*
 426  * NOTE: before c-ares 1.7.0 we would most often use the system in6_addr
 427  * struct below when ares itself was built, but many apps would use this
 428  * private version since the header checked a HAVE_* define for it. Starting
 429  * with 1.7.0 we always declare and use our own to stop relying on the
 430  * system's one.
 431  */
 432 struct ares_in6_addr {
 433   union {
 434     unsigned char _S6_u8[16];
 435   } _S6_un;
 436 };
 437
 438 struct ares_addrttl {
 439   struct in_addr ipaddr;
 440   int            ttl;
 441 };
 442
 443 struct ares_addr6ttl {
 444   struct ares_in6_addr ip6addr;
 445   int             ttl;
 446 };
 447
 448 struct ares_srv_reply {
 449   struct ares_srv_reply  *next;
 450   char                   *host;
 451   unsigned short          priority;
 452   unsigned short          weight;
 453   unsigned short          port;
 454 };
 455
 456 struct ares_mx_reply {
 457   struct ares_mx_reply   *next;
 458   char                   *host;
 459   unsigned short          priority;
 460 };
 461
 462 struct ares_txt_reply {
 463   struct ares_txt_reply  *next;
 464   unsigned char          *txt;
 465   size_t                  length;  /* length excludes null termination */
 466 };
 467
 468 /*
 469 ** Parse the buffer, starting at *abuf and of length alen bytes, previously
 470 ** obtained from an ares_search call.  Put the results in *host, if nonnull.
 471 ** Also, if addrttls is nonnull, put up to *naddrttls IPv4 addresses along with
 472 ** their TTLs in that array, and set *naddrttls to the number of addresses
 473 ** so written.
 474 */
 475
 476 CARES_EXTERN int ares_parse_a_reply(const unsigned char *abuf,
 477                                     int alen,
 478                                     struct hostent **host,
 479                                     struct ares_addrttl *addrttls,
 480                                     int *naddrttls);
 481
 482 CARES_EXTERN int ares_parse_aaaa_reply(const unsigned char *abuf,
 483                                        int alen,
 484                                        struct hostent **host,
 485                                        struct ares_addr6ttl *addrttls,
 486                                        int *naddrttls);
 487
 488 CARES_EXTERN int ares_parse_ptr_reply(const unsigned char *abuf,
 489                                       int alen,
 490                                       const void *addr,
 491                                       int addrlen,
 492                                       int family,
 493                                       struct hostent **host);
 494
 495 CARES_EXTERN int ares_parse_ns_reply(const unsigned char *abuf,
 496                                      int alen,
 497                                      struct hostent **host);
 498
 499 CARES_EXTERN int ares_parse_srv_reply(const unsigned char* abuf,
 500                                       int alen,
 501                                       struct ares_srv_reply** srv_out);
 502
 503 CARES_EXTERN int ares_parse_mx_reply(const unsigned char* abuf,
 504                                       int alen,
 505                                       struct ares_mx_reply** mx_out);
 506
 507 CARES_EXTERN int ares_parse_txt_reply(const unsigned char* abuf,
 508                                       int alen,
 509                                       struct ares_txt_reply** txt_out);
 510
 511 CARES_EXTERN void ares_free_string(void *str);
 512
 513 CARES_EXTERN void ares_free_hostent(struct hostent *host);
 514
 515 CARES_EXTERN void ares_free_data(void *dataptr);
 516
 517 CARES_EXTERN const char *ares_strerror(int code);
 518
 519 /* TODO:  Hold port here as well. */
 520 struct ares_addr_node {
 521   struct ares_addr_node *next;
 522   int family;
 523   union {
 524     struct in_addr       addr4;
 525     struct ares_in6_addr addr6;
 526   } addr;
 527 };
 528
 529 CARES_EXTERN int ares_set_servers(ares_channel channel,
 530                                   struct ares_addr_node *servers);
 531
 532 /* Incomming string format: host[:port][,host[:port]]... */
 533 CARES_EXTERN int ares_set_servers_csv(ares_channel channel,
 534                                       const char* servers);
 535
 536 CARES_EXTERN int ares_get_servers(ares_channel channel,
 537                                   struct ares_addr_node **servers);
 538
 539 #ifdef  __cplusplus
 540 }
 541 #endif
 542
 543 #endif /* ARES__H */