1 | #ifndef HEADER_CURL_ASYN_H |
2 | #define |
3 | /*************************************************************************** |
4 | * _ _ ____ _ |
5 | * Project ___| | | | _ \| | |
6 | * / __| | | | |_) | | |
7 | * | (__| |_| | _ <| |___ |
8 | * \___|\___/|_| \_\_____| |
9 | * |
10 | * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. |
11 | * |
12 | * This software is licensed as described in the file COPYING, which |
13 | * you should have received as part of this distribution. The terms |
14 | * are also available at https://curl.haxx.se/docs/copyright.html. |
15 | * |
16 | * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
17 | * copies of the Software, and permit persons to whom the Software is |
18 | * furnished to do so, under the terms of the COPYING file. |
19 | * |
20 | * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
21 | * KIND, either express or implied. |
22 | * |
23 | ***************************************************************************/ |
24 | |
25 | #include "curl_setup.h" |
26 | #include "curl_addrinfo.h" |
27 | |
28 | struct addrinfo; |
29 | struct hostent; |
30 | struct Curl_easy; |
31 | struct connectdata; |
32 | struct Curl_dns_entry; |
33 | |
34 | /* |
35 | * This header defines all functions in the internal asynch resolver interface. |
36 | * All asynch resolvers need to provide these functions. |
37 | * asyn-ares.c and asyn-thread.c are the current implementations of asynch |
38 | * resolver backends. |
39 | */ |
40 | |
41 | /* |
42 | * Curl_resolver_global_init() |
43 | * |
44 | * Called from curl_global_init() to initialize global resolver environment. |
45 | * Returning anything else than CURLE_OK fails curl_global_init(). |
46 | */ |
47 | int Curl_resolver_global_init(void); |
48 | |
49 | /* |
50 | * Curl_resolver_global_cleanup() |
51 | * Called from curl_global_cleanup() to destroy global resolver environment. |
52 | */ |
53 | void Curl_resolver_global_cleanup(void); |
54 | |
55 | /* |
56 | * Curl_resolver_init() |
57 | * Called from curl_easy_init() -> Curl_open() to initialize resolver |
58 | * URL-state specific environment ('resolver' member of the UrlState |
59 | * structure). Should fill the passed pointer by the initialized handler. |
60 | * Returning anything else than CURLE_OK fails curl_easy_init() with the |
61 | * correspondent code. |
62 | */ |
63 | CURLcode Curl_resolver_init(struct Curl_easy *easy, void **resolver); |
64 | |
65 | /* |
66 | * Curl_resolver_cleanup() |
67 | * Called from curl_easy_cleanup() -> Curl_close() to cleanup resolver |
68 | * URL-state specific environment ('resolver' member of the UrlState |
69 | * structure). Should destroy the handler and free all resources connected to |
70 | * it. |
71 | */ |
72 | void Curl_resolver_cleanup(void *resolver); |
73 | |
74 | /* |
75 | * Curl_resolver_duphandle() |
76 | * Called from curl_easy_duphandle() to duplicate resolver URL-state specific |
77 | * environment ('resolver' member of the UrlState structure). Should |
78 | * duplicate the 'from' handle and pass the resulting handle to the 'to' |
79 | * pointer. Returning anything else than CURLE_OK causes failed |
80 | * curl_easy_duphandle() call. |
81 | */ |
82 | CURLcode Curl_resolver_duphandle(struct Curl_easy *easy, void **to, |
83 | void *from); |
84 | |
85 | /* |
86 | * Curl_resolver_cancel(). |
87 | * |
88 | * It is called from inside other functions to cancel currently performing |
89 | * resolver request. Should also free any temporary resources allocated to |
90 | * perform a request. This never waits for resolver threads to complete. |
91 | * |
92 | * It is safe to call this when conn is in any state. |
93 | */ |
94 | void Curl_resolver_cancel(struct connectdata *conn); |
95 | |
96 | /* |
97 | * Curl_resolver_kill(). |
98 | * |
99 | * This acts like Curl_resolver_cancel() except it will block until any threads |
100 | * associated with the resolver are complete. This never blocks for resolvers |
101 | * that do not use threads. This is intended to be the "last chance" function |
102 | * that cleans up an in-progress resolver completely (before its owner is about |
103 | * to die). |
104 | * |
105 | * It is safe to call this when conn is in any state. |
106 | */ |
107 | void Curl_resolver_kill(struct connectdata *conn); |
108 | |
109 | /* Curl_resolver_getsock() |
110 | * |
111 | * This function is called from the multi_getsock() function. 'sock' is a |
112 | * pointer to an array to hold the file descriptors, with 'numsock' being the |
113 | * size of that array (in number of entries). This function is supposed to |
114 | * return bitmask indicating what file descriptors (referring to array indexes |
115 | * in the 'sock' array) to wait for, read/write. |
116 | */ |
117 | int Curl_resolver_getsock(struct connectdata *conn, curl_socket_t *sock); |
118 | |
119 | /* |
120 | * Curl_resolver_is_resolved() |
121 | * |
122 | * Called repeatedly to check if a previous name resolve request has |
123 | * completed. It should also make sure to time-out if the operation seems to |
124 | * take too long. |
125 | * |
126 | * Returns normal CURLcode errors. |
127 | */ |
128 | CURLcode Curl_resolver_is_resolved(struct connectdata *conn, |
129 | struct Curl_dns_entry **dns); |
130 | |
131 | /* |
132 | * Curl_resolver_wait_resolv() |
133 | * |
134 | * Waits for a resolve to finish. This function should be avoided since using |
135 | * this risk getting the multi interface to "hang". |
136 | * |
137 | * If 'entry' is non-NULL, make it point to the resolved dns entry |
138 | * |
139 | * Returns CURLE_COULDNT_RESOLVE_HOST if the host was not resolved, |
140 | * CURLE_OPERATION_TIMEDOUT if a time-out occurred, or other errors. |
141 | */ |
142 | CURLcode Curl_resolver_wait_resolv(struct connectdata *conn, |
143 | struct Curl_dns_entry **dnsentry); |
144 | |
145 | /* |
146 | * Curl_resolver_getaddrinfo() - when using this resolver |
147 | * |
148 | * Returns name information about the given hostname and port number. If |
149 | * successful, the 'hostent' is returned and the forth argument will point to |
150 | * memory we need to free after use. That memory *MUST* be freed with |
151 | * Curl_freeaddrinfo(), nothing else. |
152 | * |
153 | * Each resolver backend must of course make sure to return data in the |
154 | * correct format to comply with this. |
155 | */ |
156 | Curl_addrinfo *Curl_resolver_getaddrinfo(struct connectdata *conn, |
157 | const char *hostname, |
158 | int port, |
159 | int *waitp); |
160 | |
161 | #ifndef CURLRES_ASYNCH |
162 | /* convert these functions if an asynch resolver isn't used */ |
163 | #define Curl_resolver_cancel(x) Curl_nop_stmt |
164 | #define Curl_resolver_kill(x) Curl_nop_stmt |
165 | #define Curl_resolver_is_resolved(x,y) CURLE_COULDNT_RESOLVE_HOST |
166 | #define Curl_resolver_wait_resolv(x,y) CURLE_COULDNT_RESOLVE_HOST |
167 | #define Curl_resolver_getsock(x,y,z) 0 |
168 | #define Curl_resolver_duphandle(x,y,z) CURLE_OK |
169 | #define Curl_resolver_init(x,y) CURLE_OK |
170 | #define Curl_resolver_global_init() CURLE_OK |
171 | #define Curl_resolver_global_cleanup() Curl_nop_stmt |
172 | #define Curl_resolver_cleanup(x) Curl_nop_stmt |
173 | #endif |
174 | |
175 | #ifdef CURLRES_ASYNCH |
176 | #define Curl_resolver_asynch() 1 |
177 | #else |
178 | #define Curl_resolver_asynch() 0 |
179 | #endif |
180 | |
181 | |
182 | /********** end of generic resolver interface functions *****************/ |
183 | #endif /* HEADER_CURL_ASYN_H */ |
184 | |