VirtualBox

source: vbox/trunk/src/libs/curl-7.87.0/lib/cfilters.h@ 98339

Last change on this file since 98339 was 98339, checked in by vboxsync, 20 months ago

curl-7.87.0: EOL style fixing, bit more irrelevant export fixing

  • Property svn:eol-style set to native
File size: 13.2 KB
Line 
1#ifndef HEADER_CURL_CFILTERS_H
2#define HEADER_CURL_CFILTERS_H
3/***************************************************************************
4 * _ _ ____ _
5 * Project ___| | | | _ \| |
6 * / __| | | | |_) | |
7 * | (__| |_| | _ <| |___
8 * \___|\___/|_| \_\_____|
9 *
10 * Copyright (C) 1998 - 2022, 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.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 * SPDX-License-Identifier: curl
24 *
25 ***************************************************************************/
26
27
28struct Curl_cfilter;
29struct Curl_easy;
30struct Curl_dns_entry;
31struct connectdata;
32
33/* Callback to destroy resources held by this filter instance.
34 * Implementations MUST NOT chain calls to cf->next.
35 */
36typedef void Curl_cft_destroy_this(struct Curl_cfilter *cf,
37 struct Curl_easy *data);
38
39/* Setup the connection for `data`, using destination `remotehost`.
40 */
41typedef CURLcode Curl_cft_setup(struct Curl_cfilter *cf,
42 struct Curl_easy *data,
43 const struct Curl_dns_entry *remotehost);
44typedef void Curl_cft_close(struct Curl_cfilter *cf,
45 struct Curl_easy *data);
46
47typedef CURLcode Curl_cft_connect(struct Curl_cfilter *cf,
48 struct Curl_easy *data,
49 bool blocking, bool *done);
50
51/* Return the hostname and port the connection goes to.
52 * This may change with the connection state of filters when tunneling
53 * is involved.
54 * @param cf the filter to ask
55 * @param data the easy handle currently active
56 * @param phost on return, points to the relevant, real hostname.
57 * this is owned by the connection.
58 * @param pdisplay_host on return, points to the printable hostname.
59 * this is owned by the connection.
60 * @param pport on return, contains the port number
61 */
62typedef void Curl_cft_get_host(struct Curl_cfilter *cf,
63 struct Curl_easy *data,
64 const char **phost,
65 const char **pdisplay_host,
66 int *pport);
67
68/* Filters may return sockets and fdset flags they are waiting for.
69 * The passes array has room for up to MAX_SOCKSPEREASYHANDLE sockets.
70 * @return read/write fdset for index in socks
71 * or GETSOCK_BLANK when nothing to wait on
72 */
73typedef int Curl_cft_get_select_socks(struct Curl_cfilter *cf,
74 struct Curl_easy *data,
75 curl_socket_t *socks);
76
77typedef bool Curl_cft_data_pending(struct Curl_cfilter *cf,
78 const struct Curl_easy *data);
79
80typedef ssize_t Curl_cft_send(struct Curl_cfilter *cf,
81 struct Curl_easy *data, /* transfer */
82 const void *buf, /* data to write */
83 size_t len, /* amount to write */
84 CURLcode *err); /* error to return */
85
86typedef ssize_t Curl_cft_recv(struct Curl_cfilter *cf,
87 struct Curl_easy *data, /* transfer */
88 char *buf, /* store data here */
89 size_t len, /* amount to read */
90 CURLcode *err); /* error to return */
91
92typedef void Curl_cft_attach_data(struct Curl_cfilter *cf,
93 struct Curl_easy *data);
94typedef void Curl_cft_detach_data(struct Curl_cfilter *cf,
95 struct Curl_easy *data);
96
97/**
98 * The easy handle `data` is being detached (no longer served)
99 * by connection `conn`. All filters are informed to release any resources
100 * related to `data`.
101 * Note: there may be several `data` attached to a connection at the same
102 * time.
103 */
104void Curl_conn_detach(struct connectdata *conn, struct Curl_easy *data);
105
106#define CF_TYPE_IP_CONNECT (1 << 0)
107#define CF_TYPE_SSL (1 << 1)
108
109/* A connection filter type, e.g. specific implementation. */
110struct Curl_cftype {
111 const char *name; /* name of the filter type */
112 long flags; /* flags of filter type */
113 Curl_cft_destroy_this *destroy; /* destroy resources of this cf */
114 Curl_cft_setup *setup; /* setup for a connection */
115 Curl_cft_connect *connect; /* establish connection */
116 Curl_cft_close *close; /* close conn */
117 Curl_cft_get_host *get_host; /* host filter talks to */
118 Curl_cft_get_select_socks *get_select_socks;/* sockets to select on */
119 Curl_cft_data_pending *has_data_pending;/* conn has data pending */
120 Curl_cft_send *do_send; /* send data */
121 Curl_cft_recv *do_recv; /* receive data */
122 Curl_cft_attach_data *attach_data; /* data is being handled here */
123 Curl_cft_detach_data *detach_data; /* data is no longer handled here */
124};
125
126/* A connection filter instance, e.g. registered at a connection */
127struct Curl_cfilter {
128 const struct Curl_cftype *cft; /* the type providing implementation */
129 struct Curl_cfilter *next; /* next filter in chain */
130 void *ctx; /* filter type specific settings */
131 struct connectdata *conn; /* the connection this filter belongs to */
132 int sockindex; /* TODO: like to get rid off this */
133 BIT(connected); /* != 0 iff this filter is connected */
134};
135
136/* Default implementations for the type functions, implementing nop. */
137void Curl_cf_def_destroy_this(struct Curl_cfilter *cf,
138 struct Curl_easy *data);
139
140/* Default implementations for the type functions, implementing pass-through
141 * the filter chain. */
142CURLcode Curl_cf_def_setup(struct Curl_cfilter *cf,
143 struct Curl_easy *data,
144 const struct Curl_dns_entry *remotehost);
145void Curl_cf_def_close(struct Curl_cfilter *cf, struct Curl_easy *data);
146CURLcode Curl_cf_def_connect(struct Curl_cfilter *cf,
147 struct Curl_easy *data,
148 bool blocking, bool *done);
149void Curl_cf_def_get_host(struct Curl_cfilter *cf, struct Curl_easy *data,
150 const char **phost, const char **pdisplay_host,
151 int *pport);
152int Curl_cf_def_get_select_socks(struct Curl_cfilter *cf,
153 struct Curl_easy *data,
154 curl_socket_t *socks);
155bool Curl_cf_def_data_pending(struct Curl_cfilter *cf,
156 const struct Curl_easy *data);
157ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
158 const void *buf, size_t len, CURLcode *err);
159ssize_t Curl_cf_def_recv(struct Curl_cfilter *cf, struct Curl_easy *data,
160 char *buf, size_t len, CURLcode *err);
161void Curl_cf_def_attach_data(struct Curl_cfilter *cf,
162 struct Curl_easy *data);
163void Curl_cf_def_detach_data(struct Curl_cfilter *cf,
164 struct Curl_easy *data);
165
166/**
167 * Create a new filter instance, unattached to the filter chain.
168 * Use Curl_conn_cf_add() to add it to the chain.
169 * @param pcf on success holds the created instance
170 * @parm cft the filter type
171 * @param ctx the type specific context to use
172 */
173CURLcode Curl_cf_create(struct Curl_cfilter **pcf,
174 const struct Curl_cftype *cft,
175 void *ctx);
176
177/**
178 * Add a filter instance to the `sockindex` filter chain at connection
179 * `data->conn`. The filter must not already be attached. It is inserted at
180 * the start of the chain (top).
181 */
182void Curl_conn_cf_add(struct Curl_easy *data,
183 struct connectdata *conn,
184 int sockindex,
185 struct Curl_cfilter *cf);
186
187/**
188 * Remove and destroy all filters at chain `sockindex` on connection `conn`.
189 */
190void Curl_conn_cf_discard_all(struct Curl_easy *data,
191 struct connectdata *conn,
192 int sockindex);
193
194/**
195 * Discard, e.g. remove and destroy a specific filter instance.
196 * If the filter is attached to a connection, it will be removed before
197 * it is destroyed.
198 */
199void Curl_conn_cf_discard(struct Curl_cfilter *cf, struct Curl_easy *data);
200
201
202ssize_t Curl_conn_cf_send(struct Curl_cfilter *cf, struct Curl_easy *data,
203 const void *buf, size_t len, CURLcode *err);
204ssize_t Curl_conn_cf_recv(struct Curl_cfilter *cf, struct Curl_easy *data,
205 char *buf, size_t len, CURLcode *err);
206
207#define CURL_CF_SSL_DEFAULT -1
208#define CURL_CF_SSL_DISABLE 0
209#define CURL_CF_SSL_ENABLE 1
210
211/**
212 * Setup the filter chain at `sockindex` in connection `conn`, invoking
213 * the instance `setup(remotehost)` methods. If no filter chain is
214 * installed yet, inspects the configuration in `data` to install a
215 * suitable filter chain.
216 */
217CURLcode Curl_conn_setup(struct Curl_easy *data,
218 struct connectdata *conn,
219 int sockindex,
220 const struct Curl_dns_entry *remotehost,
221 int ssl_mode);
222
223/**
224 * Bring the filter chain at `sockindex` for connection `data->conn` into
225 * connected state. Which will set `*done` to TRUE.
226 * This can be called on an already connected chain with no side effects.
227 * When not `blocking`, calls may return without error and `*done != TRUE`,
228 * while the individual filters negotiated the connection.
229 */
230CURLcode Curl_conn_connect(struct Curl_easy *data, int sockindex,
231 bool blocking, bool *done);
232
233/**
234 * Check if the filter chain at `sockindex` for connection `conn` is
235 * completely connected.
236 */
237bool Curl_conn_is_connected(struct connectdata *conn, int sockindex);
238
239/**
240 * Determine if we have reached the remote host on IP level, e.g.
241 * have a TCP connection. This turns TRUE before a possible SSL
242 * handshake has been started/done.
243 */
244bool Curl_conn_is_ip_connected(struct Curl_easy *data, int sockindex);
245
246/**
247 * Determine if the connection is using SSL to the remote host
248 * (or will be once connected). This will return FALSE, if SSL
249 * is only used in proxying and not for the tunnel itself.
250 */
251bool Curl_conn_is_ssl(struct Curl_easy *data, int sockindex);
252
253/**
254 * Close the filter chain at `sockindex` for connection `data->conn`.
255 * Filters remain in place and may be connected again afterwards.
256 */
257void Curl_conn_close(struct Curl_easy *data, int sockindex);
258
259/**
260 * Return if data is pending in some connection filter at chain
261 * `sockindex` for connection `data->conn`.
262 */
263bool Curl_conn_data_pending(struct Curl_easy *data,
264 int sockindex);
265
266/**
267 * Get any select fd flags and the socket filters at chain `sockindex`
268 * at connection `conn` might be waiting for.
269 */
270int Curl_conn_get_select_socks(struct Curl_easy *data, int sockindex,
271 curl_socket_t *socks);
272
273/**
274 * Receive data through the filter chain at `sockindex` for connection
275 * `data->conn`. Copy at most `len` bytes into `buf`. Return the
276 * actuel number of bytes copied or a negative value on error.
277 * The error code is placed into `*code`.
278 */
279ssize_t Curl_conn_recv(struct Curl_easy *data, int sockindex, char *buf,
280 size_t len, CURLcode *code);
281
282/**
283 * Send `len` bytes of data from `buf` through the filter chain `sockindex`
284 * at connection `data->conn`. Return the actual number of bytes written
285 * or a negative value on error.
286 * The error code is placed into `*code`.
287 */
288ssize_t Curl_conn_send(struct Curl_easy *data, int sockindex,
289 const void *buf, size_t len, CURLcode *code);
290
291/**
292 * The easy handle `data` is being attached (served) by connection `conn`.
293 * All filters are informed to adapt to handling `data`.
294 * Note: there may be several `data` attached to a connection at the same
295 * time.
296 */
297void Curl_conn_attach_data(struct connectdata *conn,
298 struct Curl_easy *data);
299
300/**
301 * The easy handle `data` is being detached (no longer served)
302 * by connection `conn`. All filters are informed to release any resources
303 * related to `data`.
304 * Note: there may be several `data` attached to a connection at the same
305 * time.
306 */
307void Curl_conn_detach_data(struct connectdata *conn,
308 struct Curl_easy *data);
309
310void Curl_conn_get_host(struct Curl_easy *data, int sockindex,
311 const char **phost, const char **pdisplay_host,
312 int *pport);
313
314
315#endif /* HEADER_CURL_CFILTERS_H */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy