Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/ares.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 /* MIT License
jpayne@69 2 *
jpayne@69 3 * Copyright (c) Massachusetts Institute of Technology
jpayne@69 4 * Copyright (c) Daniel Stenberg
jpayne@69 5 *
jpayne@69 6 * Permission is hereby granted, free of charge, to any person obtaining a copy
jpayne@69 7 * of this software and associated documentation files (the "Software"), to deal
jpayne@69 8 * in the Software without restriction, including without limitation the rights
jpayne@69 9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
jpayne@69 10 * copies of the Software, and to permit persons to whom the Software is
jpayne@69 11 * furnished to do so, subject to the following conditions:
jpayne@69 12 *
jpayne@69 13 * The above copyright notice and this permission notice (including the next
jpayne@69 14 * paragraph) shall be included in all copies or substantial portions of the
jpayne@69 15 * Software.
jpayne@69 16 *
jpayne@69 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
jpayne@69 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
jpayne@69 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
jpayne@69 20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
jpayne@69 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
jpayne@69 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
jpayne@69 23 * SOFTWARE.
jpayne@69 24 *
jpayne@69 25 * SPDX-License-Identifier: MIT
jpayne@69 26 */
jpayne@69 27
jpayne@69 28 #ifndef ARES__H
jpayne@69 29 #define ARES__H
jpayne@69 30
jpayne@69 31 #include "ares_version.h" /* c-ares version defines */
jpayne@69 32 #include "ares_build.h" /* c-ares build definitions */
jpayne@69 33
jpayne@69 34 #if defined(_WIN32)
jpayne@69 35 # ifndef WIN32_LEAN_AND_MEAN
jpayne@69 36 # define WIN32_LEAN_AND_MEAN
jpayne@69 37 # endif
jpayne@69 38 #endif
jpayne@69 39
jpayne@69 40 #ifdef CARES_HAVE_SYS_TYPES_H
jpayne@69 41 # include <sys/types.h>
jpayne@69 42 #endif
jpayne@69 43
jpayne@69 44 #ifdef CARES_HAVE_SYS_SOCKET_H
jpayne@69 45 # include <sys/socket.h>
jpayne@69 46 #endif
jpayne@69 47
jpayne@69 48 #ifdef CARES_HAVE_SYS_SELECT_H
jpayne@69 49 # include <sys/select.h>
jpayne@69 50 #endif
jpayne@69 51
jpayne@69 52 #ifdef CARES_HAVE_WINSOCK2_H
jpayne@69 53 # include <winsock2.h>
jpayne@69 54 /* To aid with linking against a static c-ares build, lets tell the microsoft
jpayne@69 55 * compiler to pull in needed dependencies */
jpayne@69 56 # ifdef _MSC_VER
jpayne@69 57 # pragma comment(lib, "ws2_32")
jpayne@69 58 # pragma comment(lib, "advapi32")
jpayne@69 59 # pragma comment(lib, "iphlpapi")
jpayne@69 60 # endif
jpayne@69 61 #endif
jpayne@69 62
jpayne@69 63 #ifdef CARES_HAVE_WS2TCPIP_H
jpayne@69 64 # include <ws2tcpip.h>
jpayne@69 65 #endif
jpayne@69 66
jpayne@69 67 #ifdef CARES_HAVE_WINDOWS_H
jpayne@69 68 # include <windows.h>
jpayne@69 69 #endif
jpayne@69 70
jpayne@69 71 /* HP-UX systems version 9, 10 and 11 lack sys/select.h and so does oldish
jpayne@69 72 libc5-based Linux systems. Only include it on system that are known to
jpayne@69 73 require it! */
jpayne@69 74 #if defined(_AIX) || defined(__NOVELL_LIBC__) || defined(__NetBSD__) || \
jpayne@69 75 defined(__minix) || defined(__SYMBIAN32__) || defined(__INTEGRITY) || \
jpayne@69 76 defined(ANDROID) || defined(__ANDROID__) || defined(__OpenBSD__) || \
jpayne@69 77 defined(__QNX__) || defined(__MVS__) || defined(__HAIKU__)
jpayne@69 78 # include <sys/select.h>
jpayne@69 79 #endif
jpayne@69 80
jpayne@69 81 #if (defined(NETWARE) && !defined(__NOVELL_LIBC__))
jpayne@69 82 # include <sys/bsdskt.h>
jpayne@69 83 #endif
jpayne@69 84
jpayne@69 85 #if !defined(_WIN32)
jpayne@69 86 # include <netinet/in.h>
jpayne@69 87 #endif
jpayne@69 88
jpayne@69 89 #ifdef WATT32
jpayne@69 90 # include <tcp.h>
jpayne@69 91 #endif
jpayne@69 92
jpayne@69 93 #if defined(ANDROID) || defined(__ANDROID__)
jpayne@69 94 # include <jni.h>
jpayne@69 95 #endif
jpayne@69 96
jpayne@69 97 typedef CARES_TYPEOF_ARES_SOCKLEN_T ares_socklen_t;
jpayne@69 98 typedef CARES_TYPEOF_ARES_SSIZE_T ares_ssize_t;
jpayne@69 99
jpayne@69 100 #ifdef __cplusplus
jpayne@69 101 extern "C" {
jpayne@69 102 #endif
jpayne@69 103
jpayne@69 104 /*
jpayne@69 105 ** c-ares external API function linkage decorations.
jpayne@69 106 */
jpayne@69 107
jpayne@69 108 #if defined(_WIN32) || defined(__CYGWIN__) || defined(__SYMBIAN32__)
jpayne@69 109 # ifdef CARES_STATICLIB
jpayne@69 110 # define CARES_EXTERN
jpayne@69 111 # else
jpayne@69 112 # ifdef CARES_BUILDING_LIBRARY
jpayne@69 113 # define CARES_EXTERN __declspec(dllexport)
jpayne@69 114 # else
jpayne@69 115 # define CARES_EXTERN __declspec(dllimport)
jpayne@69 116 # endif
jpayne@69 117 # endif
jpayne@69 118 #else
jpayne@69 119 # if defined(__GNUC__) && __GNUC__ >= 4
jpayne@69 120 # define CARES_EXTERN __attribute__((visibility("default")))
jpayne@69 121 # elif defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 900
jpayne@69 122 # define CARES_EXTERN __attribute__((visibility("default")))
jpayne@69 123 # elif defined(__SUNPRO_C)
jpayne@69 124 # define CARES_EXTERN _global
jpayne@69 125 # else
jpayne@69 126 # define CARES_EXTERN
jpayne@69 127 # endif
jpayne@69 128 #endif
jpayne@69 129
jpayne@69 130 #ifdef __GNUC__
jpayne@69 131 # define CARES_GCC_VERSION \
jpayne@69 132 (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__)
jpayne@69 133 #else
jpayne@69 134 # define CARES_GCC_VERSION 0
jpayne@69 135 #endif
jpayne@69 136
jpayne@69 137 #ifndef __has_attribute
jpayne@69 138 # define __has_attribute(x) 0
jpayne@69 139 #endif
jpayne@69 140
jpayne@69 141 #ifdef CARES_NO_DEPRECATED
jpayne@69 142 # define CARES_DEPRECATED
jpayne@69 143 # define CARES_DEPRECATED_FOR(f)
jpayne@69 144 #else
jpayne@69 145 # if CARES_GCC_VERSION >= 30200 || __has_attribute(__deprecated__)
jpayne@69 146 # define CARES_DEPRECATED __attribute__((__deprecated__))
jpayne@69 147 # else
jpayne@69 148 # define CARES_DEPRECATED
jpayne@69 149 # endif
jpayne@69 150
jpayne@69 151 # if CARES_GCC_VERSION >= 40500 || defined(__clang__)
jpayne@69 152 # define CARES_DEPRECATED_FOR(f) \
jpayne@69 153 __attribute__((deprecated("Use " #f " instead")))
jpayne@69 154 # elif defined(_MSC_VER)
jpayne@69 155 # define CARES_DEPRECATED_FOR(f) __declspec(deprecated("Use " #f " instead"))
jpayne@69 156 # else
jpayne@69 157 # define CARES_DEPRECATED_FOR(f) CARES_DEPRECATED
jpayne@69 158 # endif
jpayne@69 159 #endif
jpayne@69 160
jpayne@69 161 typedef enum {
jpayne@69 162 ARES_SUCCESS = 0,
jpayne@69 163
jpayne@69 164 /* Server error codes (ARES_ENODATA indicates no relevant answer) */
jpayne@69 165 ARES_ENODATA = 1,
jpayne@69 166 ARES_EFORMERR = 2,
jpayne@69 167 ARES_ESERVFAIL = 3,
jpayne@69 168 ARES_ENOTFOUND = 4,
jpayne@69 169 ARES_ENOTIMP = 5,
jpayne@69 170 ARES_EREFUSED = 6,
jpayne@69 171
jpayne@69 172 /* Locally generated error codes */
jpayne@69 173 ARES_EBADQUERY = 7,
jpayne@69 174 ARES_EBADNAME = 8,
jpayne@69 175 ARES_EBADFAMILY = 9,
jpayne@69 176 ARES_EBADRESP = 10,
jpayne@69 177 ARES_ECONNREFUSED = 11,
jpayne@69 178 ARES_ETIMEOUT = 12,
jpayne@69 179 ARES_EOF = 13,
jpayne@69 180 ARES_EFILE = 14,
jpayne@69 181 ARES_ENOMEM = 15,
jpayne@69 182 ARES_EDESTRUCTION = 16,
jpayne@69 183 ARES_EBADSTR = 17,
jpayne@69 184
jpayne@69 185 /* ares_getnameinfo error codes */
jpayne@69 186 ARES_EBADFLAGS = 18,
jpayne@69 187
jpayne@69 188 /* ares_getaddrinfo error codes */
jpayne@69 189 ARES_ENONAME = 19,
jpayne@69 190 ARES_EBADHINTS = 20,
jpayne@69 191
jpayne@69 192 /* Uninitialized library error code */
jpayne@69 193 ARES_ENOTINITIALIZED = 21, /* introduced in 1.7.0 */
jpayne@69 194
jpayne@69 195 /* ares_library_init error codes */
jpayne@69 196 ARES_ELOADIPHLPAPI = 22, /* introduced in 1.7.0 */
jpayne@69 197 ARES_EADDRGETNETWORKPARAMS = 23, /* introduced in 1.7.0 */
jpayne@69 198
jpayne@69 199 /* More error codes */
jpayne@69 200 ARES_ECANCELLED = 24, /* introduced in 1.7.0 */
jpayne@69 201
jpayne@69 202 /* More ares_getaddrinfo error codes */
jpayne@69 203 ARES_ESERVICE = 25, /* ares_getaddrinfo() was passed a text service name that
jpayne@69 204 * is not recognized. introduced in 1.16.0 */
jpayne@69 205
jpayne@69 206 ARES_ENOSERVER = 26 /* No DNS servers were configured */
jpayne@69 207 } ares_status_t;
jpayne@69 208
jpayne@69 209 typedef enum {
jpayne@69 210 ARES_FALSE = 0,
jpayne@69 211 ARES_TRUE = 1
jpayne@69 212 } ares_bool_t;
jpayne@69 213
jpayne@69 214 /*! Values for ARES_OPT_EVENT_THREAD */
jpayne@69 215 typedef enum {
jpayne@69 216 /*! Default (best choice) event system */
jpayne@69 217 ARES_EVSYS_DEFAULT = 0,
jpayne@69 218 /*! Win32 IOCP/AFD_POLL event system */
jpayne@69 219 ARES_EVSYS_WIN32 = 1,
jpayne@69 220 /*! Linux epoll */
jpayne@69 221 ARES_EVSYS_EPOLL = 2,
jpayne@69 222 /*! BSD/MacOS kqueue */
jpayne@69 223 ARES_EVSYS_KQUEUE = 3,
jpayne@69 224 /*! POSIX poll() */
jpayne@69 225 ARES_EVSYS_POLL = 4,
jpayne@69 226 /*! last fallback on Unix-like systems, select() */
jpayne@69 227 ARES_EVSYS_SELECT = 5
jpayne@69 228 } ares_evsys_t;
jpayne@69 229
jpayne@69 230 /* Flag values */
jpayne@69 231 #define ARES_FLAG_USEVC (1 << 0)
jpayne@69 232 #define ARES_FLAG_PRIMARY (1 << 1)
jpayne@69 233 #define ARES_FLAG_IGNTC (1 << 2)
jpayne@69 234 #define ARES_FLAG_NORECURSE (1 << 3)
jpayne@69 235 #define ARES_FLAG_STAYOPEN (1 << 4)
jpayne@69 236 #define ARES_FLAG_NOSEARCH (1 << 5)
jpayne@69 237 #define ARES_FLAG_NOALIASES (1 << 6)
jpayne@69 238 #define ARES_FLAG_NOCHECKRESP (1 << 7)
jpayne@69 239 #define ARES_FLAG_EDNS (1 << 8)
jpayne@69 240 #define ARES_FLAG_NO_DFLT_SVR (1 << 9)
jpayne@69 241 #define ARES_FLAG_DNS0x20 (1 << 10)
jpayne@69 242
jpayne@69 243 /* Option mask values */
jpayne@69 244 #define ARES_OPT_FLAGS (1 << 0)
jpayne@69 245 #define ARES_OPT_TIMEOUT (1 << 1)
jpayne@69 246 #define ARES_OPT_TRIES (1 << 2)
jpayne@69 247 #define ARES_OPT_NDOTS (1 << 3)
jpayne@69 248 #define ARES_OPT_UDP_PORT (1 << 4)
jpayne@69 249 #define ARES_OPT_TCP_PORT (1 << 5)
jpayne@69 250 #define ARES_OPT_SERVERS (1 << 6)
jpayne@69 251 #define ARES_OPT_DOMAINS (1 << 7)
jpayne@69 252 #define ARES_OPT_LOOKUPS (1 << 8)
jpayne@69 253 #define ARES_OPT_SOCK_STATE_CB (1 << 9)
jpayne@69 254 #define ARES_OPT_SORTLIST (1 << 10)
jpayne@69 255 #define ARES_OPT_SOCK_SNDBUF (1 << 11)
jpayne@69 256 #define ARES_OPT_SOCK_RCVBUF (1 << 12)
jpayne@69 257 #define ARES_OPT_TIMEOUTMS (1 << 13)
jpayne@69 258 #define ARES_OPT_ROTATE (1 << 14)
jpayne@69 259 #define ARES_OPT_EDNSPSZ (1 << 15)
jpayne@69 260 #define ARES_OPT_NOROTATE (1 << 16)
jpayne@69 261 #define ARES_OPT_RESOLVCONF (1 << 17)
jpayne@69 262 #define ARES_OPT_HOSTS_FILE (1 << 18)
jpayne@69 263 #define ARES_OPT_UDP_MAX_QUERIES (1 << 19)
jpayne@69 264 #define ARES_OPT_MAXTIMEOUTMS (1 << 20)
jpayne@69 265 #define ARES_OPT_QUERY_CACHE (1 << 21)
jpayne@69 266 #define ARES_OPT_EVENT_THREAD (1 << 22)
jpayne@69 267 #define ARES_OPT_SERVER_FAILOVER (1 << 23)
jpayne@69 268
jpayne@69 269 /* Nameinfo flag values */
jpayne@69 270 #define ARES_NI_NOFQDN (1 << 0)
jpayne@69 271 #define ARES_NI_NUMERICHOST (1 << 1)
jpayne@69 272 #define ARES_NI_NAMEREQD (1 << 2)
jpayne@69 273 #define ARES_NI_NUMERICSERV (1 << 3)
jpayne@69 274 #define ARES_NI_DGRAM (1 << 4)
jpayne@69 275 #define ARES_NI_TCP 0
jpayne@69 276 #define ARES_NI_UDP ARES_NI_DGRAM
jpayne@69 277 #define ARES_NI_SCTP (1 << 5)
jpayne@69 278 #define ARES_NI_DCCP (1 << 6)
jpayne@69 279 #define ARES_NI_NUMERICSCOPE (1 << 7)
jpayne@69 280 #define ARES_NI_LOOKUPHOST (1 << 8)
jpayne@69 281 #define ARES_NI_LOOKUPSERVICE (1 << 9)
jpayne@69 282 /* Reserved for future use */
jpayne@69 283 #define ARES_NI_IDN (1 << 10)
jpayne@69 284 #define ARES_NI_IDN_ALLOW_UNASSIGNED (1 << 11)
jpayne@69 285 #define ARES_NI_IDN_USE_STD3_ASCII_RULES (1 << 12)
jpayne@69 286
jpayne@69 287 /* Addrinfo flag values */
jpayne@69 288 #define ARES_AI_CANONNAME (1 << 0)
jpayne@69 289 #define ARES_AI_NUMERICHOST (1 << 1)
jpayne@69 290 #define ARES_AI_PASSIVE (1 << 2)
jpayne@69 291 #define ARES_AI_NUMERICSERV (1 << 3)
jpayne@69 292 #define ARES_AI_V4MAPPED (1 << 4)
jpayne@69 293 #define ARES_AI_ALL (1 << 5)
jpayne@69 294 #define ARES_AI_ADDRCONFIG (1 << 6)
jpayne@69 295 #define ARES_AI_NOSORT (1 << 7)
jpayne@69 296 #define ARES_AI_ENVHOSTS (1 << 8)
jpayne@69 297 /* Reserved for future use */
jpayne@69 298 #define ARES_AI_IDN (1 << 10)
jpayne@69 299 #define ARES_AI_IDN_ALLOW_UNASSIGNED (1 << 11)
jpayne@69 300 #define ARES_AI_IDN_USE_STD3_ASCII_RULES (1 << 12)
jpayne@69 301 #define ARES_AI_CANONIDN (1 << 13)
jpayne@69 302
jpayne@69 303 #define ARES_AI_MASK \
jpayne@69 304 (ARES_AI_CANONNAME | ARES_AI_NUMERICHOST | ARES_AI_PASSIVE | \
jpayne@69 305 ARES_AI_NUMERICSERV | ARES_AI_V4MAPPED | ARES_AI_ALL | ARES_AI_ADDRCONFIG)
jpayne@69 306 #define ARES_GETSOCK_MAXNUM \
jpayne@69 307 16 /* ares_getsock() can return info about this \
jpayne@69 308 many sockets */
jpayne@69 309 #define ARES_GETSOCK_READABLE(bits, num) (bits & (1 << (num)))
jpayne@69 310 #define ARES_GETSOCK_WRITABLE(bits, num) \
jpayne@69 311 (bits & (1 << ((num) + ARES_GETSOCK_MAXNUM)))
jpayne@69 312
jpayne@69 313 /* c-ares library initialization flag values */
jpayne@69 314 #define ARES_LIB_INIT_NONE (0)
jpayne@69 315 #define ARES_LIB_INIT_WIN32 (1 << 0)
jpayne@69 316 #define ARES_LIB_INIT_ALL (ARES_LIB_INIT_WIN32)
jpayne@69 317
jpayne@69 318 /* Server state callback flag values */
jpayne@69 319 #define ARES_SERV_STATE_UDP (1 << 0) /* Query used UDP */
jpayne@69 320 #define ARES_SERV_STATE_TCP (1 << 1) /* Query used TCP */
jpayne@69 321
jpayne@69 322 /*
jpayne@69 323 * Typedef our socket type
jpayne@69 324 */
jpayne@69 325
jpayne@69 326 #ifndef ares_socket_typedef
jpayne@69 327 # if defined(_WIN32) && !defined(WATT32)
jpayne@69 328 typedef SOCKET ares_socket_t;
jpayne@69 329 # define ARES_SOCKET_BAD INVALID_SOCKET
jpayne@69 330 # else
jpayne@69 331 typedef int ares_socket_t;
jpayne@69 332 # define ARES_SOCKET_BAD -1
jpayne@69 333 # endif
jpayne@69 334 # define ares_socket_typedef
jpayne@69 335 #endif /* ares_socket_typedef */
jpayne@69 336
jpayne@69 337 typedef void (*ares_sock_state_cb)(void *data, ares_socket_t socket_fd,
jpayne@69 338 int readable, int writable);
jpayne@69 339
jpayne@69 340 struct apattern;
jpayne@69 341
jpayne@69 342 /* Options controlling server failover behavior.
jpayne@69 343 * The retry chance is the probability (1/N) by which we will retry a failed
jpayne@69 344 * server instead of the best server when selecting a server to send queries
jpayne@69 345 * to.
jpayne@69 346 * The retry delay is the minimum time in milliseconds to wait between doing
jpayne@69 347 * such retries (applied per-server).
jpayne@69 348 */
jpayne@69 349 struct ares_server_failover_options {
jpayne@69 350 unsigned short retry_chance;
jpayne@69 351 size_t retry_delay;
jpayne@69 352 };
jpayne@69 353
jpayne@69 354 /* NOTE about the ares_options struct to users and developers.
jpayne@69 355
jpayne@69 356 This struct will remain looking like this. It will not be extended nor
jpayne@69 357 shrunk in future releases, but all new options will be set by ares_set_*()
jpayne@69 358 options instead of with the ares_init_options() function.
jpayne@69 359
jpayne@69 360 Eventually (in a galaxy far far away), all options will be settable by
jpayne@69 361 ares_set_*() options and the ares_init_options() function will become
jpayne@69 362 deprecated.
jpayne@69 363
jpayne@69 364 When new options are added to c-ares, they are not added to this
jpayne@69 365 struct. And they are not "saved" with the ares_save_options() function but
jpayne@69 366 instead we encourage the use of the ares_dup() function. Needless to say,
jpayne@69 367 if you add config options to c-ares you need to make sure ares_dup()
jpayne@69 368 duplicates this new option.
jpayne@69 369
jpayne@69 370 */
jpayne@69 371 struct ares_options {
jpayne@69 372 int flags;
jpayne@69 373 int timeout; /* in seconds or milliseconds, depending on options */
jpayne@69 374 int tries;
jpayne@69 375 int ndots;
jpayne@69 376 unsigned short udp_port; /* host byte order */
jpayne@69 377 unsigned short tcp_port; /* host byte order */
jpayne@69 378 int socket_send_buffer_size;
jpayne@69 379 int socket_receive_buffer_size;
jpayne@69 380 struct in_addr *servers;
jpayne@69 381 int nservers;
jpayne@69 382 char **domains;
jpayne@69 383 int ndomains;
jpayne@69 384 char *lookups;
jpayne@69 385 ares_sock_state_cb sock_state_cb;
jpayne@69 386 void *sock_state_cb_data;
jpayne@69 387 struct apattern *sortlist;
jpayne@69 388 int nsort;
jpayne@69 389 int ednspsz;
jpayne@69 390 char *resolvconf_path;
jpayne@69 391 char *hosts_path;
jpayne@69 392 int udp_max_queries;
jpayne@69 393 int maxtimeout; /* in milliseconds */
jpayne@69 394 unsigned int qcache_max_ttl; /* Maximum TTL for query cache, 0=disabled */
jpayne@69 395 ares_evsys_t evsys;
jpayne@69 396 struct ares_server_failover_options server_failover_opts;
jpayne@69 397 };
jpayne@69 398
jpayne@69 399 struct hostent;
jpayne@69 400 struct timeval;
jpayne@69 401 struct sockaddr;
jpayne@69 402 struct ares_channeldata;
jpayne@69 403 struct ares_addrinfo;
jpayne@69 404 struct ares_addrinfo_hints;
jpayne@69 405
jpayne@69 406 /* Legacy typedef, don't use, you can't specify "const" */
jpayne@69 407 typedef struct ares_channeldata *ares_channel;
jpayne@69 408
jpayne@69 409 /* Current main channel typedef */
jpayne@69 410 typedef struct ares_channeldata ares_channel_t;
jpayne@69 411
jpayne@69 412 /*
jpayne@69 413 * NOTE: before c-ares 1.7.0 we would most often use the system in6_addr
jpayne@69 414 * struct below when ares itself was built, but many apps would use this
jpayne@69 415 * private version since the header checked a HAVE_* define for it. Starting
jpayne@69 416 * with 1.7.0 we always declare and use our own to stop relying on the
jpayne@69 417 * system's one.
jpayne@69 418 */
jpayne@69 419 struct ares_in6_addr {
jpayne@69 420 union {
jpayne@69 421 unsigned char _S6_u8[16];
jpayne@69 422 } _S6_un;
jpayne@69 423 };
jpayne@69 424
jpayne@69 425 struct ares_addr {
jpayne@69 426 int family;
jpayne@69 427
jpayne@69 428 union {
jpayne@69 429 struct in_addr addr4;
jpayne@69 430 struct ares_in6_addr addr6;
jpayne@69 431 } addr;
jpayne@69 432 };
jpayne@69 433
jpayne@69 434 /* DNS record parser, writer, and helpers */
jpayne@69 435 #include "ares_dns_record.h"
jpayne@69 436
jpayne@69 437 typedef void (*ares_callback)(void *arg, int status, int timeouts,
jpayne@69 438 unsigned char *abuf, int alen);
jpayne@69 439
jpayne@69 440 typedef void (*ares_callback_dnsrec)(void *arg, ares_status_t status,
jpayne@69 441 size_t timeouts,
jpayne@69 442 const ares_dns_record_t *dnsrec);
jpayne@69 443
jpayne@69 444 typedef void (*ares_host_callback)(void *arg, int status, int timeouts,
jpayne@69 445 struct hostent *hostent);
jpayne@69 446
jpayne@69 447 typedef void (*ares_nameinfo_callback)(void *arg, int status, int timeouts,
jpayne@69 448 char *node, char *service);
jpayne@69 449
jpayne@69 450 typedef int (*ares_sock_create_callback)(ares_socket_t socket_fd, int type,
jpayne@69 451 void *data);
jpayne@69 452
jpayne@69 453 typedef int (*ares_sock_config_callback)(ares_socket_t socket_fd, int type,
jpayne@69 454 void *data);
jpayne@69 455
jpayne@69 456 typedef void (*ares_addrinfo_callback)(void *arg, int status, int timeouts,
jpayne@69 457 struct ares_addrinfo *res);
jpayne@69 458
jpayne@69 459 typedef void (*ares_server_state_callback)(const char *server_string,
jpayne@69 460 ares_bool_t success, int flags,
jpayne@69 461 void *data);
jpayne@69 462
jpayne@69 463 typedef void (*ares_pending_write_cb)(void *data);
jpayne@69 464
jpayne@69 465 CARES_EXTERN int ares_library_init(int flags);
jpayne@69 466
jpayne@69 467 CARES_EXTERN int ares_library_init_mem(int flags, void *(*amalloc)(size_t size),
jpayne@69 468 void (*afree)(void *ptr),
jpayne@69 469 void *(*arealloc)(void *ptr,
jpayne@69 470 size_t size));
jpayne@69 471
jpayne@69 472 #if defined(ANDROID) || defined(__ANDROID__)
jpayne@69 473 CARES_EXTERN void ares_library_init_jvm(JavaVM *jvm);
jpayne@69 474 CARES_EXTERN int ares_library_init_android(jobject connectivity_manager);
jpayne@69 475 CARES_EXTERN int ares_library_android_initialized(void);
jpayne@69 476 #endif
jpayne@69 477
jpayne@69 478 #define CARES_HAVE_ARES_LIBRARY_INIT 1
jpayne@69 479 #define CARES_HAVE_ARES_LIBRARY_CLEANUP 1
jpayne@69 480
jpayne@69 481 CARES_EXTERN int ares_library_initialized(void);
jpayne@69 482
jpayne@69 483 CARES_EXTERN void ares_library_cleanup(void);
jpayne@69 484
jpayne@69 485 CARES_EXTERN const char *ares_version(int *version);
jpayne@69 486
jpayne@69 487 CARES_EXTERN CARES_DEPRECATED_FOR(ares_init_options) int ares_init(
jpayne@69 488 ares_channel_t **channelptr);
jpayne@69 489
jpayne@69 490 CARES_EXTERN int ares_init_options(ares_channel_t **channelptr,
jpayne@69 491 const struct ares_options *options,
jpayne@69 492 int optmask);
jpayne@69 493
jpayne@69 494 CARES_EXTERN int ares_save_options(const ares_channel_t *channel,
jpayne@69 495 struct ares_options *options, int *optmask);
jpayne@69 496
jpayne@69 497 CARES_EXTERN void ares_destroy_options(struct ares_options *options);
jpayne@69 498
jpayne@69 499 CARES_EXTERN int ares_dup(ares_channel_t **dest, const ares_channel_t *src);
jpayne@69 500
jpayne@69 501 CARES_EXTERN ares_status_t ares_reinit(ares_channel_t *channel);
jpayne@69 502
jpayne@69 503 CARES_EXTERN void ares_destroy(ares_channel_t *channel);
jpayne@69 504
jpayne@69 505 CARES_EXTERN void ares_cancel(ares_channel_t *channel);
jpayne@69 506
jpayne@69 507 /* These next 3 configure local binding for the out-going socket
jpayne@69 508 * connection. Use these to specify source IP and/or network device
jpayne@69 509 * on multi-homed systems.
jpayne@69 510 */
jpayne@69 511 CARES_EXTERN void ares_set_local_ip4(ares_channel_t *channel,
jpayne@69 512 unsigned int local_ip);
jpayne@69 513
jpayne@69 514 /* local_ip6 should be 16 bytes in length */
jpayne@69 515 CARES_EXTERN void ares_set_local_ip6(ares_channel_t *channel,
jpayne@69 516 const unsigned char *local_ip6);
jpayne@69 517
jpayne@69 518 /* local_dev_name should be null terminated. */
jpayne@69 519 CARES_EXTERN void ares_set_local_dev(ares_channel_t *channel,
jpayne@69 520 const char *local_dev_name);
jpayne@69 521
jpayne@69 522 CARES_EXTERN void ares_set_socket_callback(ares_channel_t *channel,
jpayne@69 523 ares_sock_create_callback callback,
jpayne@69 524 void *user_data);
jpayne@69 525
jpayne@69 526 CARES_EXTERN void ares_set_socket_configure_callback(
jpayne@69 527 ares_channel_t *channel, ares_sock_config_callback callback, void *user_data);
jpayne@69 528
jpayne@69 529 CARES_EXTERN void
jpayne@69 530 ares_set_server_state_callback(ares_channel_t *channel,
jpayne@69 531 ares_server_state_callback callback,
jpayne@69 532 void *user_data);
jpayne@69 533
jpayne@69 534 CARES_EXTERN void ares_set_pending_write_cb(ares_channel_t *channel,
jpayne@69 535 ares_pending_write_cb callback,
jpayne@69 536 void *user_data);
jpayne@69 537
jpayne@69 538 CARES_EXTERN void ares_process_pending_write(ares_channel_t *channel);
jpayne@69 539
jpayne@69 540 CARES_EXTERN int ares_set_sortlist(ares_channel_t *channel,
jpayne@69 541 const char *sortstr);
jpayne@69 542
jpayne@69 543 CARES_EXTERN void ares_getaddrinfo(ares_channel_t *channel, const char *node,
jpayne@69 544 const char *service,
jpayne@69 545 const struct ares_addrinfo_hints *hints,
jpayne@69 546 ares_addrinfo_callback callback, void *arg);
jpayne@69 547
jpayne@69 548 CARES_EXTERN void ares_freeaddrinfo(struct ares_addrinfo *ai);
jpayne@69 549
jpayne@69 550 /*
jpayne@69 551 * Virtual function set to have user-managed socket IO.
jpayne@69 552 * Note that all functions need to be defined, and when
jpayne@69 553 * set, the library will not do any bind nor set any
jpayne@69 554 * socket options, assuming the client handles these
jpayne@69 555 * through either socket creation or the
jpayne@69 556 * ares_sock_config_callback call.
jpayne@69 557 */
jpayne@69 558 struct iovec;
jpayne@69 559
jpayne@69 560 struct ares_socket_functions {
jpayne@69 561 ares_socket_t (*asocket)(int, int, int, void *);
jpayne@69 562 int (*aclose)(ares_socket_t, void *);
jpayne@69 563 int (*aconnect)(ares_socket_t, const struct sockaddr *, ares_socklen_t,
jpayne@69 564 void *);
jpayne@69 565 ares_ssize_t (*arecvfrom)(ares_socket_t, void *, size_t, int,
jpayne@69 566 struct sockaddr *, ares_socklen_t *, void *);
jpayne@69 567 ares_ssize_t (*asendv)(ares_socket_t, const struct iovec *, int, void *);
jpayne@69 568 };
jpayne@69 569
jpayne@69 570 CARES_EXTERN CARES_DEPRECATED_FOR(
jpayne@69 571 ares_set_socket_functions_ex) void ares_set_socket_functions(ares_channel_t
jpayne@69 572 *channel,
jpayne@69 573 const struct
jpayne@69 574 ares_socket_functions
jpayne@69 575 *funcs,
jpayne@69 576 void *user_data);
jpayne@69 577
jpayne@69 578 /*! Flags defining behavior of socket functions */
jpayne@69 579 typedef enum {
jpayne@69 580 /*! Strongly recommended to create sockets as non-blocking and set this
jpayne@69 581 * flag */
jpayne@69 582 ARES_SOCKFUNC_FLAG_NONBLOCKING = 1 << 0
jpayne@69 583 } ares_sockfunc_flags_t;
jpayne@69 584
jpayne@69 585 /*! Socket options in request to asetsockopt() in struct
jpayne@69 586 * ares_socket_functions_ex */
jpayne@69 587 typedef enum {
jpayne@69 588 /*! Set the send buffer size. Value is a pointer to an int. (SO_SNDBUF) */
jpayne@69 589 ARES_SOCKET_OPT_SENDBUF_SIZE,
jpayne@69 590 /*! Set the recv buffer size. Value is a pointer to an int. (SO_RCVBUF) */
jpayne@69 591 ARES_SOCKET_OPT_RECVBUF_SIZE,
jpayne@69 592 /*! Set the network interface to use as the source for communication.
jpayne@69 593 * Value is a C string. (SO_BINDTODEVICE) */
jpayne@69 594 ARES_SOCKET_OPT_BIND_DEVICE,
jpayne@69 595 /*! Enable TCP Fast Open. Value is a pointer to an ares_bool_t. On some
jpayne@69 596 * systems this could be a no-op if it is known it is on by default and
jpayne@69 597 * return success. Other systems may be a no-op if known the system does
jpayne@69 598 * not support the feature and returns failure with errno set to ENOSYS or
jpayne@69 599 * WSASetLastError(WSAEOPNOTSUPP).
jpayne@69 600 */
jpayne@69 601 ARES_SOCKET_OPT_TCP_FASTOPEN
jpayne@69 602 } ares_socket_opt_t;
jpayne@69 603
jpayne@69 604 /*! Flags for behavior during connect */
jpayne@69 605 typedef enum {
jpayne@69 606 /*! Connect using TCP Fast Open */
jpayne@69 607 ARES_SOCKET_CONN_TCP_FASTOPEN = 1 << 0
jpayne@69 608 } ares_socket_connect_flags_t;
jpayne@69 609
jpayne@69 610 /*! Flags for behavior during bind */
jpayne@69 611 typedef enum {
jpayne@69 612 /*! Bind is for a TCP connection */
jpayne@69 613 ARES_SOCKET_BIND_TCP = 1 << 0,
jpayne@69 614 /*! Bind is for a client connection, not server */
jpayne@69 615 ARES_SOCKET_BIND_CLIENT = 1 << 1
jpayne@69 616 } ares_socket_bind_flags_t;
jpayne@69 617
jpayne@69 618 /*! Socket functions to call rather than using OS-native functions */
jpayne@69 619 struct ares_socket_functions_ex {
jpayne@69 620 /*! ABI Version: must be "1" */
jpayne@69 621 unsigned int version;
jpayne@69 622
jpayne@69 623 /*! Flags indicating behavior of the subsystem. One or more
jpayne@69 624 * ares_sockfunc_flags_t */
jpayne@69 625 unsigned int flags;
jpayne@69 626
jpayne@69 627 /*! REQUIRED. Create a new socket file descriptor. The file descriptor must
jpayne@69 628 * be opened in non-blocking mode (so that reads and writes never block).
jpayne@69 629 * Recommended other options would be to disable signals on write errors
jpayne@69 630 * (SO_NOSIGPIPE), Disable the Nagle algorithm on SOCK_STREAM (TCP_NODELAY),
jpayne@69 631 * and to automatically close file descriptors on exec (FD_CLOEXEC).
jpayne@69 632 *
jpayne@69 633 * \param[in] domain Socket domain. Valid values are AF_INET, AF_INET6.
jpayne@69 634 * \param[in] type Socket type. Valid values are SOCK_STREAM (tcp) and
jpayne@69 635 * SOCK_DGRAM (udp).
jpayne@69 636 * \param[in] protocol In general this should be ignored, may be passed as
jpayne@69 637 * 0 (use as default for type), or may be IPPROTO_UDP
jpayne@69 638 * or IPPROTO_TCP.
jpayne@69 639 * \param[in] user_data Pointer provided to ares_set_socket_functions_ex().
jpayne@69 640 * \return ARES_SOCKET_BAD on error, or socket file descriptor on success.
jpayne@69 641 * On error, it is expected to set errno (or WSASetLastError()) to an
jpayne@69 642 * appropriate reason code such as EAFNOSUPPORT / WSAAFNOSUPPORT. */
jpayne@69 643 ares_socket_t (*asocket)(int domain, int type, int protocol, void *user_data);
jpayne@69 644
jpayne@69 645 /*! REQUIRED. Close a socket file descriptor.
jpayne@69 646 * \param[in] sock Socket file descriptor returned from asocket.
jpayne@69 647 * \param[in] user_data Pointer provided to ares_set_socket_functions_ex().
jpayne@69 648 * \return 0 on success. On failure, should set errno (or WSASetLastError)
jpayne@69 649 * to an appropriate code such as EBADF / WSAEBADF */
jpayne@69 650 int (*aclose)(ares_socket_t sock, void *user_data);
jpayne@69 651
jpayne@69 652
jpayne@69 653 /*! REQUIRED. Set socket option. This shares a similar syntax to the BSD
jpayne@69 654 * setsockopt() call, however we use our own options. The value is typically
jpayne@69 655 * a pointer to the desired value and each option has its own data type it
jpayne@69 656 * will express in the documentation.
jpayne@69 657 *
jpayne@69 658 * \param[in] sock Socket file descriptor returned from asocket.
jpayne@69 659 * \param[in] opt Option to set.
jpayne@69 660 * \param[in] val Pointer to value for option.
jpayne@69 661 * \param[in] val_size Size of value.
jpayne@69 662 * \param[in] user_data Pointer provided to
jpayne@69 663 * ares_set_socket_functions_ex().
jpayne@69 664 * \return Return 0 on success, otherwise -1 should be returned with an
jpayne@69 665 * appropriate errno (or WSASetLastError()) set. If error is ENOSYS /
jpayne@69 666 * WSAEOPNOTSUPP an error will not be propagated as it will take it
jpayne@69 667 * to mean it is an intentional decision to not support the feature.
jpayne@69 668 */
jpayne@69 669 int (*asetsockopt)(ares_socket_t sock, ares_socket_opt_t opt, const void *val,
jpayne@69 670 ares_socklen_t val_size, void *user_data);
jpayne@69 671
jpayne@69 672 /*! REQUIRED. Connect to the remote using the supplied address. For UDP
jpayne@69 673 * sockets this will bind the file descriptor to only send and receive packets
jpayne@69 674 * from the remote address provided.
jpayne@69 675 *
jpayne@69 676 * \param[in] sock Socket file descriptor returned from asocket.
jpayne@69 677 * \param[in] address Address to connect to
jpayne@69 678 * \param[in] address_len Size of address structure passed
jpayne@69 679 * \param[in] flags One or more ares_socket_connect_flags_t
jpayne@69 680 * \param[in] user_data Pointer provided to
jpayne@69 681 * ares_set_socket_functions_ex().
jpayne@69 682 * \return Return 0 upon successful establishement, otherwise -1 should be
jpayne@69 683 * returned with an appropriate errno (or WSASetLastError()) set. It
jpayne@69 684 * is generally expected that most TCP connections (not using TCP Fast Open)
jpayne@69 685 * will return -1 with an error of EINPROGRESS / WSAEINPROGRESS due to the
jpayne@69 686 * non-blocking nature of the connection. It is then the responsibility of
jpayne@69 687 * the implementation to notify of writability on the socket to indicate the
jpayne@69 688 * connection has succeeded (or readability on failure to retrieve the
jpayne@69 689 * appropriate error).
jpayne@69 690 */
jpayne@69 691 int (*aconnect)(ares_socket_t sock, const struct sockaddr *address,
jpayne@69 692 ares_socklen_t address_len, unsigned int flags,
jpayne@69 693 void *user_data);
jpayne@69 694
jpayne@69 695 /*! REQUIRED. Attempt to read data from the remote.
jpayne@69 696 *
jpayne@69 697 * \param[in] sock Socket file descriptor returned from asocket.
jpayne@69 698 * \param[in,out] buffer Allocated buffer to place data read from
jpayne@69 699 * socket.
jpayne@69 700 * \param[in] length Size of buffer
jpayne@69 701 * \param[in] flags Unused, always 0.
jpayne@69 702 * \param[in,out] address Buffer to hold address data was received from.
jpayne@69 703 * May be NULL if address not desired.
jpayne@69 704 * \param[in,out] address_len Input size of address buffer, output actual
jpayne@69 705 * written size. Must be NULL if address is NULL.
jpayne@69 706 * \param[in] user_data Pointer provided to
jpayne@69 707 * ares_set_socket_functions_ex().
jpayne@69 708 * \return -1 on error with appropriate errno (or WSASetLastError()) set,
jpayne@69 709 * such as EWOULDBLOCK / EAGAIN / WSAEWOULDBLOCK, or ECONNRESET /
jpayne@69 710 * WSAECONNRESET.
jpayne@69 711 */
jpayne@69 712 ares_ssize_t (*arecvfrom)(ares_socket_t sock, void *buffer, size_t length,
jpayne@69 713 int flags, struct sockaddr *address,
jpayne@69 714 ares_socklen_t *address_len, void *user_data);
jpayne@69 715
jpayne@69 716 /*! REQUIRED. Attempt to send data to the remote. Optional address may be
jpayne@69 717 * specified which may be useful on unbound UDP sockets (though currently not
jpayne@69 718 * used), and TCP FastOpen where the connection is delayed until first write.
jpayne@69 719 *
jpayne@69 720 * \param[in] sock Socket file descriptor returned from asocket.
jpayne@69 721 * \param[in] buffer Containing data to place onto wire.
jpayne@69 722 * \param[in] length Size of buffer
jpayne@69 723 * \param[in] flags Flags for writing. Currently only used flag is
jpayne@69 724 * MSG_NOSIGNAL if the host OS has such a flag. In
jpayne@69 725 * general flags can be ignored.
jpayne@69 726 * \param[in] address Buffer containing address to send data to. May
jpayne@69 727 * be NULL.
jpayne@69 728 * \param[in,out] address_len Size of address buffer. Must be 0 if address
jpayne@69 729 * is NULL.
jpayne@69 730 * \param[in] user_data Pointer provided to
jpayne@69 731 * ares_set_socket_functions_ex().
jpayne@69 732 * \return Number of bytes written. -1 on error with appropriate errno (or
jpayne@69 733 * WSASetLastError()) set.
jpayne@69 734 */
jpayne@69 735 ares_ssize_t (*asendto)(ares_socket_t sock, const void *buffer, size_t length,
jpayne@69 736 int flags, const struct sockaddr *address,
jpayne@69 737 ares_socklen_t address_len, void *user_data);
jpayne@69 738
jpayne@69 739 /*! Optional. Retrieve the local address of the socket.
jpayne@69 740 *
jpayne@69 741 * \param[in] sock Socket file descriptor returned from asocket
jpayne@69 742 * \param[in,out] address Buffer to hold address
jpayne@69 743 * \param[in,out] address_len Size of address buffer on input, written size
jpayne@69 744 * on output.
jpayne@69 745 * \param[in] user_data Pointer provided to
jpayne@69 746 * ares_set_socket_functions_ex().
jpayne@69 747 * \return 0 on success. -1 on error with an appropriate errno (or
jpayne@69 748 * WSASetLastError()) set.
jpayne@69 749 */
jpayne@69 750 int (*agetsockname)(ares_socket_t sock, struct sockaddr *address,
jpayne@69 751 ares_socklen_t *address_len, void *user_data);
jpayne@69 752
jpayne@69 753 /*! Optional. Bind the socket to an address. This can be used for client
jpayne@69 754 * connections to bind the source address for packets before connect, or
jpayne@69 755 * for server connections to bind to an address and port before listening.
jpayne@69 756 * Currently c-ares only supports client connections.
jpayne@69 757 *
jpayne@69 758 * \param[in] sock Socket file descriptor returned from asocket
jpayne@69 759 * \param[in] flags ares_socket_bind_flags_t flags.
jpayne@69 760 * \param[in] address Buffer containing address.
jpayne@69 761 * \param[in] address_len Size of address buffer.
jpayne@69 762 * \param[in] user_data Pointer provided to
jpayne@69 763 * ares_set_socket_functions_ex().
jpayne@69 764 * \return 0 on success. -1 on error with an appropriate errno (or
jpayne@69 765 * WSASetLastError()) set.
jpayne@69 766 */
jpayne@69 767 int (*abind)(ares_socket_t sock, unsigned int flags,
jpayne@69 768 const struct sockaddr *address, socklen_t address_len,
jpayne@69 769 void *user_data);
jpayne@69 770
jpayne@69 771 /* Optional. Convert an interface name into the interface index. If this
jpayne@69 772 * callback is not specified, then IPv6 Link-Local DNS servers cannot be used.
jpayne@69 773 *
jpayne@69 774 * \param[in] ifname Interface Name as NULL-terminated string.
jpayne@69 775 * \param[in] user_data Pointer provided to
jpayne@69 776 * ares_set_socket_functions_ex().
jpayne@69 777 * \return 0 on failure, otherwise interface index.
jpayne@69 778 */
jpayne@69 779 unsigned int (*aif_nametoindex)(const char *ifname, void *user_data);
jpayne@69 780
jpayne@69 781 /* Optional. Convert an interface index into the interface name. If this
jpayne@69 782 * callback is not specified, then IPv6 Link-Local DNS servers cannot be used.
jpayne@69 783 *
jpayne@69 784 * \param[in] ifindex Interface index, must be > 0
jpayne@69 785 * \param[in] ifname_buf Buffer to hold interface name. Must be at least
jpayne@69 786 * IFNAMSIZ in length or 32 bytes if IFNAMSIZ isn't
jpayne@69 787 * defined.
jpayne@69 788 * \param[in] ifname_buf_len Size of ifname_buf for verification.
jpayne@69 789 * \param[in] user_data Pointer provided to
jpayne@69 790 * ares_set_socket_functions_ex().
jpayne@69 791 * \return NULL on failure, otherwise pointer to provided ifname_buf
jpayne@69 792 */
jpayne@69 793 const char *(*aif_indextoname)(unsigned int ifindex, char *ifname_buf,
jpayne@69 794 size_t ifname_buf_len, void *user_data);
jpayne@69 795 };
jpayne@69 796
jpayne@69 797 /*! Override the native socket functions for the OS with the provided set.
jpayne@69 798 * An optional user data thunk may be specified which will be passed to
jpayne@69 799 * each registered callback. Replaces ares_set_socket_functions().
jpayne@69 800 *
jpayne@69 801 * \param[in] channel An initialized c-ares channel.
jpayne@69 802 * \param[in] funcs Structure registering the implementations for the
jpayne@69 803 * various functions. See the structure definition.
jpayne@69 804 * This will be duplicated and does not need to exist
jpayne@69 805 * past the life of this call.
jpayne@69 806 * \param[in] user_data User data thunk which will be passed to each call of
jpayne@69 807 * the registered callbacks.
jpayne@69 808 * \return ARES_SUCCESS on success, or another error code such as ARES_EFORMERR
jpayne@69 809 * on misuse.
jpayne@69 810 */
jpayne@69 811 CARES_EXTERN ares_status_t ares_set_socket_functions_ex(
jpayne@69 812 ares_channel_t *channel, const struct ares_socket_functions_ex *funcs,
jpayne@69 813 void *user_data);
jpayne@69 814
jpayne@69 815
jpayne@69 816 CARES_EXTERN CARES_DEPRECATED_FOR(ares_send_dnsrec) void ares_send(
jpayne@69 817 ares_channel_t *channel, const unsigned char *qbuf, int qlen,
jpayne@69 818 ares_callback callback, void *arg);
jpayne@69 819
jpayne@69 820 /*! Send a DNS query as an ares_dns_record_t with a callback containing the
jpayne@69 821 * parsed DNS record.
jpayne@69 822 *
jpayne@69 823 * \param[in] channel Pointer to channel on which queries will be sent.
jpayne@69 824 * \param[in] dnsrec DNS Record to send
jpayne@69 825 * \param[in] callback Callback function invoked on completion or failure of
jpayne@69 826 * the query sequence.
jpayne@69 827 * \param[in] arg Additional argument passed to the callback function.
jpayne@69 828 * \param[out] qid Query ID
jpayne@69 829 * \return One of the c-ares status codes.
jpayne@69 830 */
jpayne@69 831 CARES_EXTERN ares_status_t ares_send_dnsrec(ares_channel_t *channel,
jpayne@69 832 const ares_dns_record_t *dnsrec,
jpayne@69 833 ares_callback_dnsrec callback,
jpayne@69 834 void *arg, unsigned short *qid);
jpayne@69 835
jpayne@69 836 CARES_EXTERN CARES_DEPRECATED_FOR(ares_query_dnsrec) void ares_query(
jpayne@69 837 ares_channel_t *channel, const char *name, int dnsclass, int type,
jpayne@69 838 ares_callback callback, void *arg);
jpayne@69 839
jpayne@69 840 /*! Perform a DNS query with a callback containing the parsed DNS record.
jpayne@69 841 *
jpayne@69 842 * \param[in] channel Pointer to channel on which queries will be sent.
jpayne@69 843 * \param[in] name Query name
jpayne@69 844 * \param[in] dnsclass DNS Class
jpayne@69 845 * \param[in] type DNS Record Type
jpayne@69 846 * \param[in] callback Callback function invoked on completion or failure of
jpayne@69 847 * the query sequence.
jpayne@69 848 * \param[in] arg Additional argument passed to the callback function.
jpayne@69 849 * \param[out] qid Query ID
jpayne@69 850 * \return One of the c-ares status codes.
jpayne@69 851 */
jpayne@69 852 CARES_EXTERN ares_status_t ares_query_dnsrec(ares_channel_t *channel,
jpayne@69 853 const char *name,
jpayne@69 854 ares_dns_class_t dnsclass,
jpayne@69 855 ares_dns_rec_type_t type,
jpayne@69 856 ares_callback_dnsrec callback,
jpayne@69 857 void *arg, unsigned short *qid);
jpayne@69 858
jpayne@69 859 CARES_EXTERN CARES_DEPRECATED_FOR(ares_search_dnsrec) void ares_search(
jpayne@69 860 ares_channel_t *channel, const char *name, int dnsclass, int type,
jpayne@69 861 ares_callback callback, void *arg);
jpayne@69 862
jpayne@69 863 /*! Search for a complete DNS message.
jpayne@69 864 *
jpayne@69 865 * \param[in] channel Pointer to channel on which queries will be sent.
jpayne@69 866 * \param[in] dnsrec Pointer to initialized and filled DNS record object.
jpayne@69 867 * \param[in] callback Callback function invoked on completion or failure of
jpayne@69 868 * the query sequence.
jpayne@69 869 * \param[in] arg Additional argument passed to the callback function.
jpayne@69 870 * \return One of the c-ares status codes. In all cases, except
jpayne@69 871 * ARES_EFORMERR due to misuse, this error code will also be sent
jpayne@69 872 * to the provided callback.
jpayne@69 873 */
jpayne@69 874 CARES_EXTERN ares_status_t ares_search_dnsrec(ares_channel_t *channel,
jpayne@69 875 const ares_dns_record_t *dnsrec,
jpayne@69 876 ares_callback_dnsrec callback,
jpayne@69 877 void *arg);
jpayne@69 878
jpayne@69 879 CARES_EXTERN CARES_DEPRECATED_FOR(ares_getaddrinfo) void ares_gethostbyname(
jpayne@69 880 ares_channel_t *channel, const char *name, int family,
jpayne@69 881 ares_host_callback callback, void *arg);
jpayne@69 882
jpayne@69 883 CARES_EXTERN int ares_gethostbyname_file(ares_channel_t *channel,
jpayne@69 884 const char *name, int family,
jpayne@69 885 struct hostent **host);
jpayne@69 886
jpayne@69 887 CARES_EXTERN void ares_gethostbyaddr(ares_channel_t *channel, const void *addr,
jpayne@69 888 int addrlen, int family,
jpayne@69 889 ares_host_callback callback, void *arg);
jpayne@69 890
jpayne@69 891 CARES_EXTERN void ares_getnameinfo(ares_channel_t *channel,
jpayne@69 892 const struct sockaddr *sa,
jpayne@69 893 ares_socklen_t salen, int flags,
jpayne@69 894 ares_nameinfo_callback callback, void *arg);
jpayne@69 895
jpayne@69 896 CARES_EXTERN CARES_DEPRECATED_FOR(
jpayne@69 897 ARES_OPT_EVENT_THREAD or
jpayne@69 898 ARES_OPT_SOCK_STATE_CB) int ares_fds(const ares_channel_t *channel,
jpayne@69 899 fd_set *read_fds, fd_set *write_fds);
jpayne@69 900
jpayne@69 901 CARES_EXTERN CARES_DEPRECATED_FOR(
jpayne@69 902 ARES_OPT_EVENT_THREAD or
jpayne@69 903 ARES_OPT_SOCK_STATE_CB) int ares_getsock(const ares_channel_t *channel,
jpayne@69 904 ares_socket_t *socks, int numsocks);
jpayne@69 905
jpayne@69 906 CARES_EXTERN struct timeval *ares_timeout(const ares_channel_t *channel,
jpayne@69 907 struct timeval *maxtv,
jpayne@69 908 struct timeval *tv);
jpayne@69 909
jpayne@69 910 CARES_EXTERN CARES_DEPRECATED_FOR(ares_process_fds) void ares_process(
jpayne@69 911 ares_channel_t *channel, fd_set *read_fds, fd_set *write_fds);
jpayne@69 912
jpayne@69 913 /*! Events used by ares_fd_events_t */
jpayne@69 914 typedef enum {
jpayne@69 915 ARES_FD_EVENT_NONE = 0, /*!< No events */
jpayne@69 916 ARES_FD_EVENT_READ = 1 << 0, /*!< Read event (including disconnect/error) */
jpayne@69 917 ARES_FD_EVENT_WRITE = 1 << 1 /*!< Write event */
jpayne@69 918 } ares_fd_eventflag_t;
jpayne@69 919
jpayne@69 920 /*! Type holding a file descriptor and mask of events, used by
jpayne@69 921 * ares_process_fds() */
jpayne@69 922 typedef struct {
jpayne@69 923 ares_socket_t fd; /*!< File descriptor */
jpayne@69 924 unsigned int events; /*!< Mask of ares_fd_eventflag_t */
jpayne@69 925 } ares_fd_events_t;
jpayne@69 926
jpayne@69 927 /*! Flags used by ares_process_fds() */
jpayne@69 928 typedef enum {
jpayne@69 929 ARES_PROCESS_FLAG_NONE = 0, /*!< No flag value */
jpayne@69 930 ARES_PROCESS_FLAG_SKIP_NON_FD = 1 << 0 /*!< skip any processing unrelated to
jpayne@69 931 * the file descriptor events passed
jpayne@69 932 * in */
jpayne@69 933 } ares_process_flag_t;
jpayne@69 934
jpayne@69 935 /*! Process events on multiple file descriptors based on the event mask
jpayne@69 936 * associated with each file descriptor. Recommended over calling
jpayne@69 937 * ares_process_fd() multiple times since it would trigger additional logic
jpayne@69 938 * such as timeout processing on each call.
jpayne@69 939 *
jpayne@69 940 * \param[in] channel Initialized ares channel
jpayne@69 941 * \param[in] events Array of file descriptors with events. May be NULL if
jpayne@69 942 * no events, but may have timeouts to process.
jpayne@69 943 * \param[in] nevents Number of elements in the events array. May be 0 if
jpayne@69 944 * no events, but may have timeouts to process.
jpayne@69 945 * \param[in] flags Flags to alter behavior of the process command.
jpayne@69 946 * \return ARES_ENOMEM on out of memory, ARES_EFORMERR on misuse,
jpayne@69 947 * otherwise ARES_SUCCESS
jpayne@69 948 */
jpayne@69 949 CARES_EXTERN ares_status_t ares_process_fds(ares_channel_t *channel,
jpayne@69 950 const ares_fd_events_t *events,
jpayne@69 951 size_t nevents, unsigned int flags);
jpayne@69 952
jpayne@69 953 CARES_EXTERN void ares_process_fd(ares_channel_t *channel,
jpayne@69 954 ares_socket_t read_fd,
jpayne@69 955 ares_socket_t write_fd);
jpayne@69 956
jpayne@69 957 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_record_create) int ares_create_query(
jpayne@69 958 const char *name, int dnsclass, int type, unsigned short id, int rd,
jpayne@69 959 unsigned char **buf, int *buflen, int max_udp_size);
jpayne@69 960
jpayne@69 961 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_record_create) int ares_mkquery(
jpayne@69 962 const char *name, int dnsclass, int type, unsigned short id, int rd,
jpayne@69 963 unsigned char **buf, int *buflen);
jpayne@69 964
jpayne@69 965 CARES_EXTERN int ares_expand_name(const unsigned char *encoded,
jpayne@69 966 const unsigned char *abuf, int alen, char **s,
jpayne@69 967 long *enclen);
jpayne@69 968
jpayne@69 969 CARES_EXTERN int ares_expand_string(const unsigned char *encoded,
jpayne@69 970 const unsigned char *abuf, int alen,
jpayne@69 971 unsigned char **s, long *enclen);
jpayne@69 972
jpayne@69 973 struct ares_addrttl {
jpayne@69 974 struct in_addr ipaddr;
jpayne@69 975 int ttl;
jpayne@69 976 };
jpayne@69 977
jpayne@69 978 struct ares_addr6ttl {
jpayne@69 979 struct ares_in6_addr ip6addr;
jpayne@69 980 int ttl;
jpayne@69 981 };
jpayne@69 982
jpayne@69 983 struct ares_caa_reply {
jpayne@69 984 struct ares_caa_reply *next;
jpayne@69 985 int critical;
jpayne@69 986 unsigned char *property;
jpayne@69 987 size_t plength; /* plength excludes null termination */
jpayne@69 988 unsigned char *value;
jpayne@69 989 size_t length; /* length excludes null termination */
jpayne@69 990 };
jpayne@69 991
jpayne@69 992 struct ares_srv_reply {
jpayne@69 993 struct ares_srv_reply *next;
jpayne@69 994 char *host;
jpayne@69 995 unsigned short priority;
jpayne@69 996 unsigned short weight;
jpayne@69 997 unsigned short port;
jpayne@69 998 };
jpayne@69 999
jpayne@69 1000 struct ares_mx_reply {
jpayne@69 1001 struct ares_mx_reply *next;
jpayne@69 1002 char *host;
jpayne@69 1003 unsigned short priority;
jpayne@69 1004 };
jpayne@69 1005
jpayne@69 1006 struct ares_txt_reply {
jpayne@69 1007 struct ares_txt_reply *next;
jpayne@69 1008 unsigned char *txt;
jpayne@69 1009 size_t length; /* length excludes null termination */
jpayne@69 1010 };
jpayne@69 1011
jpayne@69 1012 /* NOTE: This structure is a superset of ares_txt_reply
jpayne@69 1013 */
jpayne@69 1014 struct ares_txt_ext {
jpayne@69 1015 struct ares_txt_ext *next;
jpayne@69 1016 unsigned char *txt;
jpayne@69 1017 size_t length;
jpayne@69 1018 /* 1 - if start of new record
jpayne@69 1019 * 0 - if a chunk in the same record */
jpayne@69 1020 unsigned char record_start;
jpayne@69 1021 };
jpayne@69 1022
jpayne@69 1023 struct ares_naptr_reply {
jpayne@69 1024 struct ares_naptr_reply *next;
jpayne@69 1025 unsigned char *flags;
jpayne@69 1026 unsigned char *service;
jpayne@69 1027 unsigned char *regexp;
jpayne@69 1028 char *replacement;
jpayne@69 1029 unsigned short order;
jpayne@69 1030 unsigned short preference;
jpayne@69 1031 };
jpayne@69 1032
jpayne@69 1033 struct ares_soa_reply {
jpayne@69 1034 char *nsname;
jpayne@69 1035 char *hostmaster;
jpayne@69 1036 unsigned int serial;
jpayne@69 1037 unsigned int refresh;
jpayne@69 1038 unsigned int retry;
jpayne@69 1039 unsigned int expire;
jpayne@69 1040 unsigned int minttl;
jpayne@69 1041 };
jpayne@69 1042
jpayne@69 1043 struct ares_uri_reply {
jpayne@69 1044 struct ares_uri_reply *next;
jpayne@69 1045 unsigned short priority;
jpayne@69 1046 unsigned short weight;
jpayne@69 1047 char *uri;
jpayne@69 1048 int ttl;
jpayne@69 1049 };
jpayne@69 1050
jpayne@69 1051 /*
jpayne@69 1052 * Similar to addrinfo, but with extra ttl and missing canonname.
jpayne@69 1053 */
jpayne@69 1054 struct ares_addrinfo_node {
jpayne@69 1055 int ai_ttl;
jpayne@69 1056 int ai_flags;
jpayne@69 1057 int ai_family;
jpayne@69 1058 int ai_socktype;
jpayne@69 1059 int ai_protocol;
jpayne@69 1060 ares_socklen_t ai_addrlen;
jpayne@69 1061 struct sockaddr *ai_addr;
jpayne@69 1062 struct ares_addrinfo_node *ai_next;
jpayne@69 1063 };
jpayne@69 1064
jpayne@69 1065 /*
jpayne@69 1066 * alias - label of the resource record.
jpayne@69 1067 * name - value (canonical name) of the resource record.
jpayne@69 1068 * See RFC2181 10.1.1. CNAME terminology.
jpayne@69 1069 */
jpayne@69 1070 struct ares_addrinfo_cname {
jpayne@69 1071 int ttl;
jpayne@69 1072 char *alias;
jpayne@69 1073 char *name;
jpayne@69 1074 struct ares_addrinfo_cname *next;
jpayne@69 1075 };
jpayne@69 1076
jpayne@69 1077 struct ares_addrinfo {
jpayne@69 1078 struct ares_addrinfo_cname *cnames;
jpayne@69 1079 struct ares_addrinfo_node *nodes;
jpayne@69 1080 char *name;
jpayne@69 1081 };
jpayne@69 1082
jpayne@69 1083 struct ares_addrinfo_hints {
jpayne@69 1084 int ai_flags;
jpayne@69 1085 int ai_family;
jpayne@69 1086 int ai_socktype;
jpayne@69 1087 int ai_protocol;
jpayne@69 1088 };
jpayne@69 1089
jpayne@69 1090 /*
jpayne@69 1091 ** Parse the buffer, starting at *abuf and of length alen bytes, previously
jpayne@69 1092 ** obtained from an ares_search call. Put the results in *host, if nonnull.
jpayne@69 1093 ** Also, if addrttls is nonnull, put up to *naddrttls IPv4 addresses along with
jpayne@69 1094 ** their TTLs in that array, and set *naddrttls to the number of addresses
jpayne@69 1095 ** so written.
jpayne@69 1096 */
jpayne@69 1097
jpayne@69 1098 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_a_reply(
jpayne@69 1099 const unsigned char *abuf, int alen, struct hostent **host,
jpayne@69 1100 struct ares_addrttl *addrttls, int *naddrttls);
jpayne@69 1101
jpayne@69 1102 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_aaaa_reply(
jpayne@69 1103 const unsigned char *abuf, int alen, struct hostent **host,
jpayne@69 1104 struct ares_addr6ttl *addrttls, int *naddrttls);
jpayne@69 1105
jpayne@69 1106 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_caa_reply(
jpayne@69 1107 const unsigned char *abuf, int alen, struct ares_caa_reply **caa_out);
jpayne@69 1108
jpayne@69 1109 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_ptr_reply(
jpayne@69 1110 const unsigned char *abuf, int alen, const void *addr, int addrlen,
jpayne@69 1111 int family, struct hostent **host);
jpayne@69 1112
jpayne@69 1113 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_ns_reply(
jpayne@69 1114 const unsigned char *abuf, int alen, struct hostent **host);
jpayne@69 1115
jpayne@69 1116 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_srv_reply(
jpayne@69 1117 const unsigned char *abuf, int alen, struct ares_srv_reply **srv_out);
jpayne@69 1118
jpayne@69 1119 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_mx_reply(
jpayne@69 1120 const unsigned char *abuf, int alen, struct ares_mx_reply **mx_out);
jpayne@69 1121
jpayne@69 1122 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_txt_reply(
jpayne@69 1123 const unsigned char *abuf, int alen, struct ares_txt_reply **txt_out);
jpayne@69 1124
jpayne@69 1125 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_txt_reply_ext(
jpayne@69 1126 const unsigned char *abuf, int alen, struct ares_txt_ext **txt_out);
jpayne@69 1127
jpayne@69 1128 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_naptr_reply(
jpayne@69 1129 const unsigned char *abuf, int alen, struct ares_naptr_reply **naptr_out);
jpayne@69 1130
jpayne@69 1131 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_soa_reply(
jpayne@69 1132 const unsigned char *abuf, int alen, struct ares_soa_reply **soa_out);
jpayne@69 1133
jpayne@69 1134 CARES_EXTERN CARES_DEPRECATED_FOR(ares_dns_parse) int ares_parse_uri_reply(
jpayne@69 1135 const unsigned char *abuf, int alen, struct ares_uri_reply **uri_out);
jpayne@69 1136
jpayne@69 1137 CARES_EXTERN void ares_free_string(void *str);
jpayne@69 1138
jpayne@69 1139 CARES_EXTERN void ares_free_hostent(struct hostent *host);
jpayne@69 1140
jpayne@69 1141 CARES_EXTERN void ares_free_data(void *dataptr);
jpayne@69 1142
jpayne@69 1143 CARES_EXTERN const char *ares_strerror(int code);
jpayne@69 1144
jpayne@69 1145 struct ares_addr_node {
jpayne@69 1146 struct ares_addr_node *next;
jpayne@69 1147 int family;
jpayne@69 1148
jpayne@69 1149 union {
jpayne@69 1150 struct in_addr addr4;
jpayne@69 1151 struct ares_in6_addr addr6;
jpayne@69 1152 } addr;
jpayne@69 1153 };
jpayne@69 1154
jpayne@69 1155 struct ares_addr_port_node {
jpayne@69 1156 struct ares_addr_port_node *next;
jpayne@69 1157 int family;
jpayne@69 1158
jpayne@69 1159 union {
jpayne@69 1160 struct in_addr addr4;
jpayne@69 1161 struct ares_in6_addr addr6;
jpayne@69 1162 } addr;
jpayne@69 1163
jpayne@69 1164 int udp_port;
jpayne@69 1165 int tcp_port;
jpayne@69 1166 };
jpayne@69 1167
jpayne@69 1168 CARES_EXTERN CARES_DEPRECATED_FOR(ares_set_servers_csv) int ares_set_servers(
jpayne@69 1169 ares_channel_t *channel, const struct ares_addr_node *servers);
jpayne@69 1170
jpayne@69 1171 CARES_EXTERN
jpayne@69 1172 CARES_DEPRECATED_FOR(ares_set_servers_ports_csv)
jpayne@69 1173 int ares_set_servers_ports(ares_channel_t *channel,
jpayne@69 1174 const struct ares_addr_port_node *servers);
jpayne@69 1175
jpayne@69 1176 /* Incoming string format: host[:port][,host[:port]]... */
jpayne@69 1177 CARES_EXTERN int ares_set_servers_csv(ares_channel_t *channel,
jpayne@69 1178 const char *servers);
jpayne@69 1179 CARES_EXTERN int ares_set_servers_ports_csv(ares_channel_t *channel,
jpayne@69 1180 const char *servers);
jpayne@69 1181 CARES_EXTERN char *ares_get_servers_csv(const ares_channel_t *channel);
jpayne@69 1182
jpayne@69 1183 CARES_EXTERN CARES_DEPRECATED_FOR(ares_get_servers_csv) int ares_get_servers(
jpayne@69 1184 const ares_channel_t *channel, struct ares_addr_node **servers);
jpayne@69 1185
jpayne@69 1186 CARES_EXTERN
jpayne@69 1187 CARES_DEPRECATED_FOR(ares_get_servers_csv)
jpayne@69 1188 int ares_get_servers_ports(const ares_channel_t *channel,
jpayne@69 1189 struct ares_addr_port_node **servers);
jpayne@69 1190
jpayne@69 1191 CARES_EXTERN const char *ares_inet_ntop(int af, const void *src, char *dst,
jpayne@69 1192 ares_socklen_t size);
jpayne@69 1193
jpayne@69 1194 CARES_EXTERN int ares_inet_pton(int af, const char *src, void *dst);
jpayne@69 1195
jpayne@69 1196 /*! Whether or not the c-ares library was built with threadsafety
jpayne@69 1197 *
jpayne@69 1198 * \return ARES_TRUE if built with threadsafety, ARES_FALSE if not
jpayne@69 1199 */
jpayne@69 1200 CARES_EXTERN ares_bool_t ares_threadsafety(void);
jpayne@69 1201
jpayne@69 1202
jpayne@69 1203 /*! Block until notified that there are no longer any queries in queue, or
jpayne@69 1204 * the specified timeout has expired.
jpayne@69 1205 *
jpayne@69 1206 * \param[in] channel Initialized ares channel
jpayne@69 1207 * \param[in] timeout_ms Number of milliseconds to wait for the queue to be
jpayne@69 1208 * empty. -1 for Infinite.
jpayne@69 1209 * \return ARES_ENOTIMP if not built with threading support, ARES_ETIMEOUT
jpayne@69 1210 * if requested timeout expires, ARES_SUCCESS when queue is empty.
jpayne@69 1211 */
jpayne@69 1212 CARES_EXTERN ares_status_t ares_queue_wait_empty(ares_channel_t *channel,
jpayne@69 1213 int timeout_ms);
jpayne@69 1214
jpayne@69 1215
jpayne@69 1216 /*! Retrieve the total number of active queries pending answers from servers.
jpayne@69 1217 * Some c-ares requests may spawn multiple queries, such as ares_getaddrinfo()
jpayne@69 1218 * when using AF_UNSPEC, which will be reflected in this number.
jpayne@69 1219 *
jpayne@69 1220 * \param[in] channel Initialized ares channel
jpayne@69 1221 * \return Number of active queries to servers
jpayne@69 1222 */
jpayne@69 1223 CARES_EXTERN size_t ares_queue_active_queries(const ares_channel_t *channel);
jpayne@69 1224
jpayne@69 1225 #ifdef __cplusplus
jpayne@69 1226 }
jpayne@69 1227 #endif
jpayne@69 1228
jpayne@69 1229 #endif /* ARES__H */