ares.h

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