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