ares.h

   1
   2 /* Copyright 1998 by the Massachusetts Institute of Technology.
   3  * Copyright (C) 2007-2013 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 #ifdef CARES_STATICLIB
  79 #  define CARES_EXTERN
  80 #elif defined(WIN32) || defined(_WIN32) || defined(__SYMBIAN32__)
  81 #  if defined(CARES_BUILDING_LIBRARY)
  82 #    define CARES_EXTERN  __declspec(dllexport)
  83 #  else
  84 #    define CARES_EXTERN  __declspec(dllimport)
  85 #  endif
  86 #elif defined(CARES_BUILDING_LIBRARY) && defined(CARES_SYMBOL_HIDING)
  87 #  define CARES_EXTERN CARES_SYMBOL_SCOPE_EXTERN
  88 #else
  89 #  define CARES_EXTERN
  90 #endif
  91
  92
  93 #define ARES_SUCCESS            0
  94
  95 /* Server error codes (ARES_ENODATA indicates no relevant answer) */
  96 #define ARES_ENODATA            1
  97 #define ARES_EFORMERR           2
  98 #define ARES_ESERVFAIL          3
  99 #define ARES_ENOTFOUND          4
 100 #define ARES_ENOTIMP            5
 101 #define ARES_EREFUSED           6
 102
 103 /* Locally generated error codes */
 104 #define ARES_EBADQUERY          7
 105 #define ARES_EBADNAME           8
 106 #define ARES_EBADFAMILY         9
 107 #define ARES_EBADRESP           10
 108 #define ARES_ECONNREFUSED       11
 109 #define ARES_ETIMEOUT           12
 110 #define ARES_EOF                13
 111 #define ARES_EFILE              14
 112 #define ARES_ENOMEM             15
 113 #define ARES_EDESTRUCTION       16
 114 #define ARES_EBADSTR            17
 115
 116 /* ares_getnameinfo error codes */
 117 #define ARES_EBADFLAGS          18
 118
 119 /* ares_getaddrinfo error codes */
 120 #define ARES_ENONAME            19
 121 #define ARES_EBADHINTS          20
 122
 123 /* Uninitialized library error code */
 124 #define ARES_ENOTINITIALIZED    21          /* introduced in 1.7.0 */
 125
 126 /* ares_library_init error codes */
 127 #define ARES_ELOADIPHLPAPI           22     /* introduced in 1.7.0 */
 128 #define ARES_EADDRGETNETWORKPARAMS   23     /* introduced in 1.7.0 */
 129
 130 /* More error codes */
 131 #define ARES_ECANCELLED         24          /* introduced in 1.7.0 */
 132
 133 /* Flag values */
 134 #define ARES_FLAG_USEVC         (1 << 0)
 135 #define ARES_FLAG_PRIMARY       (1 << 1)
 136 #define ARES_FLAG_IGNTC         (1 << 2)
 137 #define ARES_FLAG_NORECURSE     (1 << 3)
 138 #define ARES_FLAG_STAYOPEN      (1 << 4)
 139 #define ARES_FLAG_NOSEARCH      (1 << 5)
 140 #define ARES_FLAG_NOALIASES     (1 << 6)
 141 #define ARES_FLAG_NOCHECKRESP   (1 << 7)
 142 #define ARES_FLAG_EDNS          (1 << 8)
 143
 144 /* Option mask values */
 145 #define ARES_OPT_FLAGS          (1 << 0)
 146 #define ARES_OPT_TIMEOUT        (1 << 1)
 147 #define ARES_OPT_TRIES          (1 << 2)
 148 #define ARES_OPT_NDOTS          (1 << 3)
 149 #define ARES_OPT_UDP_PORT       (1 << 4)
 150 #define ARES_OPT_TCP_PORT       (1 << 5)
 151 #define ARES_OPT_SERVERS        (1 << 6)
 152 #define ARES_OPT_DOMAINS        (1 << 7)
 153 #define ARES_OPT_LOOKUPS        (1 << 8)
 154 #define ARES_OPT_SOCK_STATE_CB  (1 << 9)
 155 #define ARES_OPT_SORTLIST       (1 << 10)
 156 #define ARES_OPT_SOCK_SNDBUF    (1 << 11)
 157 #define ARES_OPT_SOCK_RCVBUF    (1 << 12)
 158 #define ARES_OPT_TIMEOUTMS      (1 << 13)
 159 #define ARES_OPT_ROTATE         (1 << 14)
 160 #define ARES_OPT_EDNSPSZ        (1 << 15)
 161
 162 /* Nameinfo flag values */
 163 #define ARES_NI_NOFQDN                  (1 << 0)
 164 #define ARES_NI_NUMERICHOST             (1 << 1)
 165 #define ARES_NI_NAMEREQD                (1 << 2)
 166 #define ARES_NI_NUMERICSERV             (1 << 3)
 167 #define ARES_NI_DGRAM                   (1 << 4)
 168 #define ARES_NI_TCP                     0
 169 #define ARES_NI_UDP                     ARES_NI_DGRAM
 170 #define ARES_NI_SCTP                    (1 << 5)
 171 #define ARES_NI_DCCP                    (1 << 6)
 172 #define ARES_NI_NUMERICSCOPE            (1 << 7)
 173 #define ARES_NI_LOOKUPHOST              (1 << 8)
 174 #define ARES_NI_LOOKUPSERVICE           (1 << 9)
 175 /* Reserved for future use */
 176 #define ARES_NI_IDN                     (1 << 10)
 177 #define ARES_NI_IDN_ALLOW_UNASSIGNED    (1 << 11)
 178 #define ARES_NI_IDN_USE_STD3_ASCII_RULES (1 << 12)
 179
 180 /* Addrinfo flag values */
 181 #define ARES_AI_CANONNAME               (1 << 0)
 182 #define ARES_AI_NUMERICHOST             (1 << 1)
 183 #define ARES_AI_PASSIVE                 (1 << 2)
 184 #define ARES_AI_NUMERICSERV             (1 << 3)
 185 #define ARES_AI_V4MAPPED                (1 << 4)
 186 #define ARES_AI_ALL                     (1 << 5)
 187 #define ARES_AI_ADDRCONFIG              (1 << 6)
 188 /* Reserved for future use */
 189 #define ARES_AI_IDN                     (1 << 10)
 190 #define ARES_AI_IDN_ALLOW_UNASSIGNED    (1 << 11)
 191 #define ARES_AI_IDN_USE_STD3_ASCII_RULES (1 << 12)
 192 #define ARES_AI_CANONIDN                (1 << 13)
 193
 194 #define ARES_AI_MASK (ARES_AI_CANONNAME|ARES_AI_NUMERICHOST|ARES_AI_PASSIVE| \
 195                       ARES_AI_NUMERICSERV|ARES_AI_V4MAPPED|ARES_AI_ALL| \
 196                       ARES_AI_ADDRCONFIG)
 197 #define ARES_GETSOCK_MAXNUM 16 /* ares_getsock() can return info about this
 198                                   many sockets */
 199 #define ARES_GETSOCK_READABLE(bits,num) (bits & (1<< (num)))
 200 #define ARES_GETSOCK_WRITABLE(bits,num) (bits & (1 << ((num) + \
 201                                          ARES_GETSOCK_MAXNUM)))
 202
 203 /* c-ares library initialization flag values */
 204 #define ARES_LIB_INIT_NONE   (0)
 205 #define ARES_LIB_INIT_WIN32  (1 << 0)
 206 #define ARES_LIB_INIT_ALL    (ARES_LIB_INIT_WIN32)
 207
 208
 209 /*
 210  * Typedef our socket type
 211  */
 212
 213 #ifndef ares_socket_typedef
 214 #ifdef WIN32
 215 typedef SOCKET ares_socket_t;
 216 #define ARES_SOCKET_BAD INVALID_SOCKET
 217 #else
 218 typedef int ares_socket_t;
 219 #define ARES_SOCKET_BAD -1
 220 #endif
 221 #define ares_socket_typedef
 222 #endif /* ares_socket_typedef */
 223
 224 typedef void (*ares_sock_state_cb)(void *data,
 225                                    ares_socket_t socket_fd,
 226                                    int readable,
 227                                    int writable);
 228
 229 struct apattern;
 230
 231 /* NOTE about the ares_options struct to users and developers.
 232
 233    This struct will remain looking like this. It will not be extended nor
 234    shrunk in future releases, but all new options will be set by ares_set_*()
 235    options instead of with the ares_init_options() function.
 236
 237    Eventually (in a galaxy far far away), all options will be settable by
 238    ares_set_*() options and the ares_init_options() function will become
 239    deprecated.
 240
 241    When new options are added to c-ares, they are not added to this
 242    struct. And they are not "saved" with the ares_save_options() function but
 243    instead we encourage the use of the ares_dup() function. Needless to say,
 244    if you add config options to c-ares you need to make sure ares_dup()
 245    duplicates this new option.
 246
 247  */
 248 struct ares_options {
 249   int flags;
 250   int timeout; /* in seconds or milliseconds, depending on options */
 251   int tries;
 252   int ndots;
 253   unsigned short udp_port;
 254   unsigned short tcp_port;
 255   int socket_send_buffer_size;
 256   int socket_receive_buffer_size;
 257   struct in_addr *servers;
 258   int nservers;
 259   char **domains;
 260   int ndomains;
 261   char *lookups;
 262   ares_sock_state_cb sock_state_cb;
 263   void *sock_state_cb_data;
 264   struct apattern *sortlist;
 265   int nsort;
 266   int ednspsz;
 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_create_query(const char *name,
 406                                    int dnsclass,
 407                                    int type,
 408                                    unsigned short id,
 409                                    int rd,
 410                                    unsigned char **buf,
 411                                    int *buflen,
 412                                    int max_udp_size);
 413
 414 CARES_EXTERN int ares_mkquery(const char *name,
 415                               int dnsclass,
 416                               int type,
 417                               unsigned short id,
 418                               int rd,
 419                               unsigned char **buf,
 420                               int *buflen);
 421
 422 CARES_EXTERN int ares_expand_name(const unsigned char *encoded,
 423                                   const unsigned char *abuf,
 424                                   int alen,
 425                                   char **s,
 426                                   long *enclen);
 427
 428 CARES_EXTERN int ares_expand_string(const unsigned char *encoded,
 429                                     const unsigned char *abuf,
 430                                     int alen,
 431                                     unsigned char **s,
 432                                     long *enclen);
 433
 434 /*
 435  * NOTE: before c-ares 1.7.0 we would most often use the system in6_addr
 436  * struct below when ares itself was built, but many apps would use this
 437  * private version since the header checked a HAVE_* define for it. Starting
 438  * with 1.7.0 we always declare and use our own to stop relying on the
 439  * system's one.
 440  */
 441 struct ares_in6_addr {
 442   union {
 443     unsigned char _S6_u8[16];
 444   } _S6_un;
 445 };
 446
 447 struct ares_addrttl {
 448   struct in_addr ipaddr;
 449   int            ttl;
 450 };
 451
 452 struct ares_addr6ttl {
 453   struct ares_in6_addr ip6addr;
 454   int             ttl;
 455 };
 456
 457 struct ares_srv_reply {
 458   struct ares_srv_reply  *next;
 459   char                   *host;
 460   unsigned short          priority;
 461   unsigned short          weight;
 462   unsigned short          port;
 463 };
 464
 465 struct ares_mx_reply {
 466   struct ares_mx_reply   *next;
 467   char                   *host;
 468   unsigned short          priority;
 469 };
 470
 471 struct ares_txt_reply {
 472   struct ares_txt_reply  *next;
 473   unsigned char          *txt;
 474   size_t                  length;  /* length excludes null termination */
 475 };
 476
 477 struct ares_naptr_reply {
 478   struct ares_naptr_reply *next;
 479   unsigned char           *flags;
 480   unsigned char           *service;
 481   unsigned char           *regexp;
 482   char                    *replacement;
 483   unsigned short           order;
 484   unsigned short           preference;
 485 };
 486
 487 struct ares_soa_reply {
 488   char        *nsname;
 489   char        *hostmaster;
 490   unsigned int serial;
 491   unsigned int refresh;
 492   unsigned int retry;
 493   unsigned int expire;
 494   unsigned int minttl;
 495 };
 496
 497 /*
 498 ** Parse the buffer, starting at *abuf and of length alen bytes, previously
 499 ** obtained from an ares_search call.  Put the results in *host, if nonnull.
 500 ** Also, if addrttls is nonnull, put up to *naddrttls IPv4 addresses along with
 501 ** their TTLs in that array, and set *naddrttls to the number of addresses
 502 ** so written.
 503 */
 504
 505 CARES_EXTERN int ares_parse_a_reply(const unsigned char *abuf,
 506                                     int alen,
 507                                     struct hostent **host,
 508                                     struct ares_addrttl *addrttls,
 509                                     int *naddrttls);
 510
 511 CARES_EXTERN int ares_parse_aaaa_reply(const unsigned char *abuf,
 512                                        int alen,
 513                                        struct hostent **host,
 514                                        struct ares_addr6ttl *addrttls,
 515                                        int *naddrttls);
 516
 517 CARES_EXTERN int ares_parse_ptr_reply(const unsigned char *abuf,
 518                                       int alen,
 519                                       const void *addr,
 520                                       int addrlen,
 521                                       int family,
 522                                       struct hostent **host);
 523
 524 CARES_EXTERN int ares_parse_ns_reply(const unsigned char *abuf,
 525                                      int alen,
 526                                      struct hostent **host);
 527
 528 CARES_EXTERN int ares_parse_srv_reply(const unsigned char* abuf,
 529                                       int alen,
 530                                       struct ares_srv_reply** srv_out);
 531
 532 CARES_EXTERN int ares_parse_mx_reply(const unsigned char* abuf,
 533                                       int alen,
 534                                       struct ares_mx_reply** mx_out);
 535
 536 CARES_EXTERN int ares_parse_txt_reply(const unsigned char* abuf,
 537                                       int alen,
 538                                       struct ares_txt_reply** txt_out);
 539
 540 CARES_EXTERN int ares_parse_naptr_reply(const unsigned char* abuf,
 541                                         int alen,
 542                                         struct ares_naptr_reply** naptr_out);
 543
 544 CARES_EXTERN int ares_parse_soa_reply(const unsigned char* abuf,
 545                                       int alen,
 546                                       struct ares_soa_reply** soa_out);
 547
 548 CARES_EXTERN void ares_free_string(void *str);
 549
 550 CARES_EXTERN void ares_free_hostent(struct hostent *host);
 551
 552 CARES_EXTERN void ares_free_data(void *dataptr);
 553
 554 CARES_EXTERN const char *ares_strerror(int code);
 555
 556 /* TODO:  Hold port here as well. */
 557 struct ares_addr_node {
 558   struct ares_addr_node *next;
 559   int family;
 560   union {
 561     struct in_addr       addr4;
 562     struct ares_in6_addr addr6;
 563   } addr;
 564 };
 565
 566 CARES_EXTERN int ares_set_servers(ares_channel channel,
 567                                   struct ares_addr_node *servers);
 568
 569 /* Incomming string format: host[:port][,host[:port]]... */
 570 CARES_EXTERN int ares_set_servers_csv(ares_channel channel,
 571                                       const char* servers);
 572
 573 CARES_EXTERN int ares_get_servers(ares_channel channel,
 574                                   struct ares_addr_node **servers);
 575
 576 CARES_EXTERN const char *ares_inet_ntop(int af, const void *src, char *dst,
 577                                         ares_socklen_t size);
 578
 579 CARES_EXTERN int ares_inet_pton(int af, const char *src, void *dst);
 580
 581
 582 #ifdef  __cplusplus
 583 }
 584 #endif
 585
 586 #endif /* ARES__H */