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