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