Make the query callbacks return the number of timeouts that happened during the execu...
[platform/upstream/c-ares.git] / ares.h
1 /* $Id$ */
2
3 /* Copyright 1998 by the Massachusetts Institute of Technology.
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 <sys/types.h>
22
23 #if defined(_AIX) || (defined(NETWARE) && defined(__NOVELL_LIBC__))
24 /* HP-UX systems version 9, 10 and 11 lack sys/select.h and so does oldish
25    libc5-based Linux systems. Only include it on system that are known to
26    require it! */
27 #include <sys/select.h>
28 #endif
29 #if (defined(NETWARE) && !defined(__NOVELL_LIBC__))
30 #include <sys/bsdskt.h>
31 #endif
32
33 #if defined(WATT32)
34   #include <netinet/in.h>
35   #include <sys/socket.h>
36   #include <tcp.h>
37 #elif defined(WIN32)
38   #include <winsock2.h>
39   #include <windows.h>
40 #else
41   #include <netinet/in.h>
42   #include <sys/socket.h>
43 #endif
44
45 #ifdef  __cplusplus
46 extern "C" {
47 #endif
48
49 #define ARES_SUCCESS            0
50
51 /* Server error codes (ARES_ENODATA indicates no relevant answer) */
52 #define ARES_ENODATA            1
53 #define ARES_EFORMERR           2
54 #define ARES_ESERVFAIL          3
55 #define ARES_ENOTFOUND          4
56 #define ARES_ENOTIMP            5
57 #define ARES_EREFUSED           6
58
59 /* Locally generated error codes */
60 #define ARES_EBADQUERY          7
61 #define ARES_EBADNAME           8
62 #define ARES_EBADFAMILY         9
63 #define ARES_EBADRESP           10
64 #define ARES_ECONNREFUSED       11
65 #define ARES_ETIMEOUT           12
66 #define ARES_EOF                13
67 #define ARES_EFILE              14
68 #define ARES_ENOMEM             15
69 #define ARES_EDESTRUCTION       16
70 #define ARES_EBADSTR            17
71
72 /* ares_getnameinfo error codes */
73 #define ARES_EBADFLAGS          18
74
75 /* ares_getaddrinfo error codes */
76 #define ARES_ENONAME            19
77 #define ARES_EBADHINTS          20
78
79 /* Flag values */
80 #define ARES_FLAG_USEVC         (1 << 0)
81 #define ARES_FLAG_PRIMARY       (1 << 1)
82 #define ARES_FLAG_IGNTC         (1 << 2)
83 #define ARES_FLAG_NORECURSE     (1 << 3)
84 #define ARES_FLAG_STAYOPEN      (1 << 4)
85 #define ARES_FLAG_NOSEARCH      (1 << 5)
86 #define ARES_FLAG_NOALIASES     (1 << 6)
87 #define ARES_FLAG_NOCHECKRESP   (1 << 7)
88
89 /* Option mask values */
90 #define ARES_OPT_FLAGS          (1 << 0)
91 #define ARES_OPT_TIMEOUT        (1 << 1)
92 #define ARES_OPT_TRIES          (1 << 2)
93 #define ARES_OPT_NDOTS          (1 << 3)
94 #define ARES_OPT_UDP_PORT       (1 << 4)
95 #define ARES_OPT_TCP_PORT       (1 << 5)
96 #define ARES_OPT_SERVERS        (1 << 6)
97 #define ARES_OPT_DOMAINS        (1 << 7)
98 #define ARES_OPT_LOOKUPS        (1 << 8)
99 #define ARES_OPT_SOCK_STATE_CB  (1 << 9)
100 #define ARES_OPT_SORTLIST       (1 << 10)
101
102 /* Nameinfo flag values */
103 #define ARES_NI_NOFQDN                  (1 << 0)
104 #define ARES_NI_NUMERICHOST             (1 << 1)
105 #define ARES_NI_NAMEREQD                (1 << 2)
106 #define ARES_NI_NUMERICSERV             (1 << 3)
107 #define ARES_NI_DGRAM                   (1 << 4)
108 #define ARES_NI_TCP                     0
109 #define ARES_NI_UDP                     ARES_NI_DGRAM
110 #define ARES_NI_SCTP                    (1 << 5)
111 #define ARES_NI_DCCP                    (1 << 6)
112 #define ARES_NI_NUMERICSCOPE            (1 << 7)
113 #define ARES_NI_LOOKUPHOST              (1 << 8)
114 #define ARES_NI_LOOKUPSERVICE           (1 << 9)
115 /* Reserved for future use */
116 #define ARES_NI_IDN                     (1 << 10)
117 #define ARES_NI_IDN_ALLOW_UNASSIGNED    (1 << 11)
118 #define ARES_NI_IDN_USE_STD3_ASCII_RULES (1 << 12)
119
120 /* Addrinfo flag values */
121 #define ARES_AI_CANONNAME               (1 << 0)
122 #define ARES_AI_NUMERICHOST             (1 << 1)
123 #define ARES_AI_PASSIVE                 (1 << 2)
124 #define ARES_AI_NUMERICSERV             (1 << 3)
125 #define ARES_AI_V4MAPPED                (1 << 4)
126 #define ARES_AI_ALL                     (1 << 5)
127 #define ARES_AI_ADDRCONFIG              (1 << 6)
128 /* Reserved for future use */
129 #define ARES_AI_IDN                     (1 << 10)
130 #define ARES_AI_IDN_ALLOW_UNASSIGNED    (1 << 11)
131 #define ARES_AI_IDN_USE_STD3_ASCII_RULES (1 << 12)
132 #define ARES_AI_CANONIDN                (1 << 13)
133
134 #define ARES_AI_MASK (ARES_AI_CANONNAME|ARES_AI_NUMERICHOST|ARES_AI_PASSIVE| \
135                       ARES_AI_NUMERICSERV|ARES_AI_V4MAPPED|ARES_AI_ALL| \
136                       ARES_AI_ADDRCONFIG)
137 #define ARES_GETSOCK_MAXNUM 16 /* ares_getsock() can return info about this
138                                   many sockets */
139 #define ARES_GETSOCK_READABLE(bits,num) (bits & (1<< (num)))
140 #define ARES_GETSOCK_WRITABLE(bits,num) (bits & (1 << ((num) + \
141                                          ARES_GETSOCK_MAXNUM)))
142
143
144 /*
145  * Typedef our socket type
146  */
147
148 #ifndef ares_socket_typedef
149 #ifdef WIN32
150 typedef SOCKET ares_socket_t;
151 #define ARES_SOCKET_BAD INVALID_SOCKET
152 #else
153 typedef int ares_socket_t;
154 #define ARES_SOCKET_BAD -1
155 #endif
156 #define ares_socket_typedef
157 #endif /* ares_socket_typedef */
158
159 #ifdef WIN32
160 typedef void (*ares_sock_state_cb)(void *data,
161                                    SOCKET socket,
162                                    int readable,
163                                    int writable);
164 #else
165 typedef void (*ares_sock_state_cb)(void *data,
166                                    int socket,
167                                    int readable,
168                                    int writable);
169 #endif
170
171 struct apattern;
172
173 struct ares_options {
174   int flags;
175   int timeout;
176   int tries;
177   int ndots;
178   unsigned short udp_port;
179   unsigned short tcp_port;
180   struct in_addr *servers;
181   int nservers;
182   char **domains;
183   int ndomains;
184   char *lookups;
185   ares_sock_state_cb sock_state_cb;
186   void *sock_state_cb_data;
187   struct apattern *sortlist;
188   int nsort;
189 };
190
191 struct hostent;
192 struct timeval;
193 struct sockaddr;
194 struct ares_channeldata;
195 typedef struct ares_channeldata *ares_channel;
196 typedef void (*ares_callback)(void *arg, int status, int timeouts,
197                               unsigned char *abuf, int alen);
198 typedef void (*ares_host_callback)(void *arg, int status, int timeouts,
199                                    struct hostent *hostent);
200 typedef void (*ares_nameinfo_callback)(void *arg, int status, int timeouts,
201                                        char *node, char *service);
202
203 int ares_init(ares_channel *channelptr);
204 int ares_init_options(ares_channel *channelptr, struct ares_options *options,
205                       int optmask);
206 int ares_save_options(ares_channel channel, struct ares_options *options, int *optmask);
207 void ares_destroy_options(struct ares_options *options);
208 void ares_destroy(ares_channel channel);
209 void ares_cancel(ares_channel channel);
210 void ares_send(ares_channel channel, const unsigned char *qbuf, int qlen,
211                ares_callback callback, void *arg);
212 void ares_query(ares_channel channel, const char *name, int dnsclass,
213                 int type, ares_callback callback, void *arg);
214 void ares_search(ares_channel channel, const char *name, int dnsclass,
215                  int type, ares_callback callback, void *arg);
216 void ares_gethostbyname(ares_channel channel, const char *name, int family,
217                         ares_host_callback callback, void *arg);
218 void ares_gethostbyaddr(ares_channel channel, const void *addr, int addrlen,
219                         int family, ares_host_callback callback, void *arg);
220 void ares_getnameinfo(ares_channel channel, const struct sockaddr *sa,
221                       socklen_t salen, int flags,
222                       ares_nameinfo_callback callback,
223                       void *arg);
224 int ares_fds(ares_channel channel, fd_set *read_fds, fd_set *write_fds);
225 int ares_getsock(ares_channel channel, int *socks, int numsocks);
226 struct timeval *ares_timeout(ares_channel channel, struct timeval *maxtv,
227                              struct timeval *tv);
228 void ares_process(ares_channel channel, fd_set *read_fds, fd_set *write_fds);
229 void ares_process_fd(ares_channel channel, ares_socket_t read_fd,
230                      ares_socket_t write_fd);
231
232 int ares_mkquery(const char *name, int dnsclass, int type, unsigned short id,
233                  int rd, unsigned char **buf, int *buflen);
234 int ares_expand_name(const unsigned char *encoded, const unsigned char *abuf,
235                      int alen, char **s, long *enclen);
236 int ares_expand_string(const unsigned char *encoded, const unsigned char *abuf,
237                      int alen, unsigned char **s, long *enclen);
238 int ares_parse_a_reply(const unsigned char *abuf, int alen,
239                        struct hostent **host);
240 int ares_parse_aaaa_reply(const unsigned char *abuf, int alen,
241                        struct hostent **host);
242 int ares_parse_ptr_reply(const unsigned char *abuf, int alen, const void *addr,
243                          int addrlen, int family, struct hostent **host);
244 int ares_parse_ns_reply(const unsigned char *abuf, int alen,
245                        struct hostent **host);
246 void ares_free_string(void *str);
247 void ares_free_hostent(struct hostent *host);
248 const char *ares_strerror(int code);
249
250 #ifdef  __cplusplus
251 }
252 #endif
253
254 #endif /* ARES__H */