1#ifndef HEADER_CURL_CFILTERS_H
2#define HEADER_CURL_CFILTERS_H
3/***************************************************************************
4 * _ _ ____ _
5 * Project ___| | | | _ \| |
6 * / __| | | | |_) | |
7 * | (__| |_| | _ <| |___
8 * \___|\___/|_| \_\_____|
9 *
10 * Copyright (C) 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
39typedef void Curl_cft_close(struct Curl_cfilter *cf,
40 struct Curl_easy *data);
41
42typedef CURLcode Curl_cft_connect(struct Curl_cfilter *cf,
43 struct Curl_easy *data,
44 bool blocking, bool *done);
45
46/* Return the hostname and port the connection goes to.
47 * This may change with the connection state of filters when tunneling
48 * is involved.
49 * @param cf the filter to ask
50 * @param data the easy handle currently active
51 * @param phost on return, points to the relevant, real hostname.
52 * this is owned by the connection.
53 * @param pdisplay_host on return, points to the printable hostname.
54 * this is owned by the connection.
55 * @param pport on return, contains the port number
56 */
57typedef void Curl_cft_get_host(struct Curl_cfilter *cf,
58 struct Curl_easy *data,
59 const char **phost,
60 const char **pdisplay_host,
61 int *pport);
62
63/* Filters may return sockets and fdset flags they are waiting for.
64 * The passes array has room for up to MAX_SOCKSPEREASYHANDLE sockets.
65 * @return read/write fdset for index in socks
66 * or GETSOCK_BLANK when nothing to wait on
67 */
68typedef int Curl_cft_get_select_socks(struct Curl_cfilter *cf,
69 struct Curl_easy *data,
70 curl_socket_t *socks);
71
72typedef bool Curl_cft_data_pending(struct Curl_cfilter *cf,
73 const struct Curl_easy *data);
74
75typedef ssize_t Curl_cft_send(struct Curl_cfilter *cf,
76 struct Curl_easy *data, /* transfer */
77 const void *buf, /* data to write */
78 size_t len, /* amount to write */
79 CURLcode *err); /* error to return */
80
81typedef ssize_t Curl_cft_recv(struct Curl_cfilter *cf,
82 struct Curl_easy *data, /* transfer */
83 char *buf, /* store data here */
84 size_t len, /* amount to read */
85 CURLcode *err); /* error to return */
86
87typedef bool Curl_cft_conn_is_alive(struct Curl_cfilter *cf,
88 struct Curl_easy *data,
89 bool *input_pending);
90
91typedef CURLcode Curl_cft_conn_keep_alive(struct Curl_cfilter *cf,
92 struct Curl_easy *data);
93
94/**
95 * Events/controls for connection filters, their arguments and
96 * return code handling. Filter callbacks are invoked "top down".
97 * Return code handling:
98 * "first fail" meaning that the first filter returning != CURLE_OK, will
99 * abort further event distribution and determine the result.
100 * "ignored" meaning return values are ignored and the event is distributed
101 * to all filters in the chain. Overall result is always CURLE_OK.
102 */
103/* data event arg1 arg2 return */
104#define CF_CTRL_DATA_ATTACH 1 /* 0 NULL ignored */
105#define CF_CTRL_DATA_DETACH 2 /* 0 NULL ignored */
106#define CF_CTRL_DATA_SETUP 4 /* 0 NULL first fail */
107#define CF_CTRL_DATA_IDLE 5 /* 0 NULL first fail */
108#define CF_CTRL_DATA_PAUSE 6 /* on/off NULL first fail */
109#define CF_CTRL_DATA_DONE 7 /* premature NULL ignored */
110#define CF_CTRL_DATA_DONE_SEND 8 /* 0 NULL ignored */
111/* update conn info at connection and data */
112#define CF_CTRL_CONN_INFO_UPDATE (256+0) /* 0 NULL ignored */
113
114/**
115 * Handle event/control for the filter.
116 * Implementations MUST NOT chain calls to cf->next.
117 */
118typedef CURLcode Curl_cft_cntrl(struct Curl_cfilter *cf,
119 struct Curl_easy *data,
120 int event, int arg1, void *arg2);
121
122
123/**
124 * Queries to ask via a `Curl_cft_query *query` method on a cfilter chain.
125 * - MAX_CONCURRENT: the maximum number of parallel transfers the filter
126 * chain expects to handle at the same time.
127 * default: 1 if no filter overrides.
128 * - CONNECT_REPLY_MS: milliseconds until the first indication of a server
129 * response was received on a connect. For TCP, this
130 * reflects the time until the socket connected. On UDP
131 * this gives the time the first bytes from the server
132 * were received.
133 * -1 if not determined yet.
134 * - CF_QUERY_SOCKET: the socket used by the filter chain
135 */
136/* query res1 res2 */
137#define CF_QUERY_MAX_CONCURRENT 1 /* number - */
138#define CF_QUERY_CONNECT_REPLY_MS 2 /* number - */
139#define CF_QUERY_SOCKET 3 /* - curl_socket_t */
140#define CF_QUERY_TIMER_CONNECT 4 /* - struct curltime */
141#define CF_QUERY_TIMER_APPCONNECT 5 /* - struct curltime */
142
143/**
144 * Query the cfilter for properties. Filters ignorant of a query will
145 * pass it "down" the filter chain.
146 */
147typedef CURLcode Curl_cft_query(struct Curl_cfilter *cf,
148 struct Curl_easy *data,
149 int query, int *pres1, void *pres2);
150
151/**
152 * Type flags for connection filters. A filter can have none, one or
153 * many of those. Use to evaluate state/capabilities of a filter chain.
154 *
155 * CF_TYPE_IP_CONNECT: provides an IP connection or sth equivalent, like
156 * a CONNECT tunnel, a UNIX domain socket, a QUIC
157 * connection, etc.
158 * CF_TYPE_SSL: provide SSL/TLS
159 * CF_TYPE_MULTIPLEX: provides multiplexing of easy handles
160 */
161#define CF_TYPE_IP_CONNECT (1 << 0)
162#define CF_TYPE_SSL (1 << 1)
163#define CF_TYPE_MULTIPLEX (1 << 2)
164
165/* A connection filter type, e.g. specific implementation. */
166struct Curl_cftype {
167 const char *name; /* name of the filter type */
168 int flags; /* flags of filter type */
169 int log_level; /* log level for such filters */
170 Curl_cft_destroy_this *destroy; /* destroy resources of this cf */
171 Curl_cft_connect *do_connect; /* establish connection */
172 Curl_cft_close *do_close; /* close conn */
173 Curl_cft_get_host *get_host; /* host filter talks to */
174 Curl_cft_get_select_socks *get_select_socks;/* sockets to select on */
175 Curl_cft_data_pending *has_data_pending;/* conn has data pending */
176 Curl_cft_send *do_send; /* send data */
177 Curl_cft_recv *do_recv; /* receive data */
178 Curl_cft_cntrl *cntrl; /* events/control */
179 Curl_cft_conn_is_alive *is_alive; /* FALSE if conn is dead, Jim! */
180 Curl_cft_conn_keep_alive *keep_alive; /* try to keep it alive */
181 Curl_cft_query *query; /* query filter chain */
182};
183
184/* A connection filter instance, e.g. registered at a connection */
185struct Curl_cfilter {
186 const struct Curl_cftype *cft; /* the type providing implementation */
187 struct Curl_cfilter *next; /* next filter in chain */
188 void *ctx; /* filter type specific settings */
189 struct connectdata *conn; /* the connection this filter belongs to */
190 int sockindex; /* the index the filter is installed at */
191 BIT(connected); /* != 0 iff this filter is connected */
192};
193
194/* Default implementations for the type functions, implementing nop. */
195void Curl_cf_def_destroy_this(struct Curl_cfilter *cf,
196 struct Curl_easy *data);
197
198/* Default implementations for the type functions, implementing pass-through
199 * the filter chain. */
200void Curl_cf_def_get_host(struct Curl_cfilter *cf, struct Curl_easy *data,
201 const char **phost, const char **pdisplay_host,
202 int *pport);
203int Curl_cf_def_get_select_socks(struct Curl_cfilter *cf,
204 struct Curl_easy *data,
205 curl_socket_t *socks);
206bool Curl_cf_def_data_pending(struct Curl_cfilter *cf,
207 const struct Curl_easy *data);
208ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
209 const void *buf, size_t len, CURLcode *err);
210ssize_t Curl_cf_def_recv(struct Curl_cfilter *cf, struct Curl_easy *data,
211 char *buf, size_t len, CURLcode *err);
212CURLcode Curl_cf_def_cntrl(struct Curl_cfilter *cf,
213 struct Curl_easy *data,
214 int event, int arg1, void *arg2);
215bool Curl_cf_def_conn_is_alive(struct Curl_cfilter *cf,
216 struct Curl_easy *data,
217 bool *input_pending);
218CURLcode Curl_cf_def_conn_keep_alive(struct Curl_cfilter *cf,
219 struct Curl_easy *data);
220CURLcode Curl_cf_def_query(struct Curl_cfilter *cf,
221 struct Curl_easy *data,
222 int query, int *pres1, void *pres2);
223
224/**
225 * Create a new filter instance, unattached to the filter chain.
226 * Use Curl_conn_cf_add() to add it to the chain.
227 * @param pcf on success holds the created instance
228 * @param cft the filter type
229 * @param ctx the type specific context to use
230 */
231CURLcode Curl_cf_create(struct Curl_cfilter **pcf,
232 const struct Curl_cftype *cft,
233 void *ctx);
234
235/**
236 * Add a filter instance to the `sockindex` filter chain at connection
237 * `conn`. The filter must not already be attached. It is inserted at
238 * the start of the chain (top).
239 */
240void Curl_conn_cf_add(struct Curl_easy *data,
241 struct connectdata *conn,
242 int sockindex,
243 struct Curl_cfilter *cf);
244
245/**
246 * Insert a filter (chain) after `cf_at`.
247 * `cf_new` must not already be attached.
248 */
249void Curl_conn_cf_insert_after(struct Curl_cfilter *cf_at,
250 struct Curl_cfilter *cf_new);
251
252/**
253 * Discard, e.g. remove and destroy `discard` iff
254 * it still is in the filter chain below `cf`. If `discard`
255 * is no longer found beneath `cf` return FALSE.
256 * if `destroy_always` is TRUE, will call `discard`s destroy
257 * function and free it even if not found in the subchain.
258 */
259bool Curl_conn_cf_discard_sub(struct Curl_cfilter *cf,
260 struct Curl_cfilter *discard,
261 struct Curl_easy *data,
262 bool destroy_always);
263
264/**
265 * Discard all cfilters starting with `*pcf` and clearing it afterwards.
266 */
267void Curl_conn_cf_discard_chain(struct Curl_cfilter **pcf,
268 struct Curl_easy *data);
269
270/**
271 * Remove and destroy all filters at chain `sockindex` on connection `conn`.
272 */
273void Curl_conn_cf_discard_all(struct Curl_easy *data,
274 struct connectdata *conn,
275 int sockindex);
276
277
278CURLcode Curl_conn_cf_connect(struct Curl_cfilter *cf,
279 struct Curl_easy *data,
280 bool blocking, bool *done);
281void Curl_conn_cf_close(struct Curl_cfilter *cf, struct Curl_easy *data);
282int Curl_conn_cf_get_select_socks(struct Curl_cfilter *cf,
283 struct Curl_easy *data,
284 curl_socket_t *socks);
285ssize_t Curl_conn_cf_send(struct Curl_cfilter *cf, struct Curl_easy *data,
286 const void *buf, size_t len, CURLcode *err);
287ssize_t Curl_conn_cf_recv(struct Curl_cfilter *cf, struct Curl_easy *data,
288 char *buf, size_t len, CURLcode *err);
289CURLcode Curl_conn_cf_cntrl(struct Curl_cfilter *cf,
290 struct Curl_easy *data,
291 bool ignore_result,
292 int event, int arg1, void *arg2);
293
294/**
295 * Determine if the connection filter chain is using SSL to the remote host
296 * (or will be once connected).
297 */
298bool Curl_conn_cf_is_ssl(struct Curl_cfilter *cf);
299
300/**
301 * Get the socket used by the filter chain starting at `cf`.
302 * Returns CURL_SOCKET_BAD if not available.
303 */
304curl_socket_t Curl_conn_cf_get_socket(struct Curl_cfilter *cf,
305 struct Curl_easy *data);
306
307
308#define CURL_CF_SSL_DEFAULT -1
309#define CURL_CF_SSL_DISABLE 0
310#define CURL_CF_SSL_ENABLE 1
311
312/**
313 * Bring the filter chain at `sockindex` for connection `data->conn` into
314 * connected state. Which will set `*done` to TRUE.
315 * This can be called on an already connected chain with no side effects.
316 * When not `blocking`, calls may return without error and `*done != TRUE`,
317 * while the individual filters negotiated the connection.
318 */
319CURLcode Curl_conn_connect(struct Curl_easy *data, int sockindex,
320 bool blocking, bool *done);
321
322/**
323 * Check if the filter chain at `sockindex` for connection `conn` is
324 * completely connected.
325 */
326bool Curl_conn_is_connected(struct connectdata *conn, int sockindex);
327
328/**
329 * Determine if we have reached the remote host on IP level, e.g.
330 * have a TCP connection. This turns TRUE before a possible SSL
331 * handshake has been started/done.
332 */
333bool Curl_conn_is_ip_connected(struct Curl_easy *data, int sockindex);
334
335/**
336 * Determine if the connection is using SSL to the remote host
337 * (or will be once connected). This will return FALSE, if SSL
338 * is only used in proxying and not for the tunnel itself.
339 */
340bool Curl_conn_is_ssl(struct connectdata *conn, int sockindex);
341
342/**
343 * Connection provides multiplexing of easy handles at `socketindex`.
344 */
345bool Curl_conn_is_multiplex(struct connectdata *conn, int sockindex);
346
347/**
348 * Close the filter chain at `sockindex` for connection `data->conn`.
349 * Filters remain in place and may be connected again afterwards.
350 */
351void Curl_conn_close(struct Curl_easy *data, int sockindex);
352
353/**
354 * Return if data is pending in some connection filter at chain
355 * `sockindex` for connection `data->conn`.
356 */
357bool Curl_conn_data_pending(struct Curl_easy *data,
358 int sockindex);
359
360/**
361 * Return the socket used on data's connection for the index.
362 * Returns CURL_SOCKET_BAD if not available.
363 */
364curl_socket_t Curl_conn_get_socket(struct Curl_easy *data, int sockindex);
365
366/**
367 * Get any select fd flags and the socket filters at chain `sockindex`
368 * at connection `conn` might be waiting for.
369 */
370int Curl_conn_get_select_socks(struct Curl_easy *data, int sockindex,
371 curl_socket_t *socks);
372
373/**
374 * Receive data through the filter chain at `sockindex` for connection
375 * `data->conn`. Copy at most `len` bytes into `buf`. Return the
376 * actuel number of bytes copied or a negative value on error.
377 * The error code is placed into `*code`.
378 */
379ssize_t Curl_conn_recv(struct Curl_easy *data, int sockindex, char *buf,
380 size_t len, CURLcode *code);
381
382/**
383 * Send `len` bytes of data from `buf` through the filter chain `sockindex`
384 * at connection `data->conn`. Return the actual number of bytes written
385 * or a negative value on error.
386 * The error code is placed into `*code`.
387 */
388ssize_t Curl_conn_send(struct Curl_easy *data, int sockindex,
389 const void *buf, size_t len, CURLcode *code);
390
391/**
392 * The easy handle `data` is being attached to `conn`. This does
393 * not mean that data will actually do a transfer. Attachment is
394 * also used for temporary actions on the connection.
395 */
396void Curl_conn_ev_data_attach(struct connectdata *conn,
397 struct Curl_easy *data);
398
399/**
400 * The easy handle `data` is being detached (no longer served)
401 * by connection `conn`. All filters are informed to release any resources
402 * related to `data`.
403 * Note: there may be several `data` attached to a connection at the same
404 * time.
405 */
406void Curl_conn_ev_data_detach(struct connectdata *conn,
407 struct Curl_easy *data);
408
409/**
410 * Notify connection filters that they need to setup data for
411 * a transfer.
412 */
413CURLcode Curl_conn_ev_data_setup(struct Curl_easy *data);
414
415/**
416 * Notify connection filters that now would be a good time to
417 * perform any idle, e.g. time related, actions.
418 */
419CURLcode Curl_conn_ev_data_idle(struct Curl_easy *data);
420
421/**
422 * Notify connection filters that the transfer represented by `data`
423 * is donw with sending data (e.g. has uploaded everything).
424 */
425void Curl_conn_ev_data_done_send(struct Curl_easy *data);
426
427/**
428 * Notify connection filters that the transfer represented by `data`
429 * is finished - eventually premature, e.g. before being complete.
430 */
431void Curl_conn_ev_data_done(struct Curl_easy *data, bool premature);
432
433/**
434 * Notify connection filters that the transfer of data is paused/unpaused.
435 */
436CURLcode Curl_conn_ev_data_pause(struct Curl_easy *data, bool do_pause);
437
438/**
439 * Inform connection filters to update their info in `conn`.
440 */
441void Curl_conn_ev_update_info(struct Curl_easy *data,
442 struct connectdata *conn);
443
444/**
445 * Check if FIRSTSOCKET's cfilter chain deems connection alive.
446 */
447bool Curl_conn_is_alive(struct Curl_easy *data, struct connectdata *conn,
448 bool *input_pending);
449
450/**
451 * Try to upkeep the connection filters at sockindex.
452 */
453CURLcode Curl_conn_keep_alive(struct Curl_easy *data,
454 struct connectdata *conn,
455 int sockindex);
456
457void Curl_cf_def_close(struct Curl_cfilter *cf, struct Curl_easy *data);
458void Curl_conn_get_host(struct Curl_easy *data, int sockindex,
459 const char **phost, const char **pdisplay_host,
460 int *pport);
461
462/**
463 * Get the maximum number of parallel transfers the connection
464 * expects to be able to handle at `sockindex`.
465 */
466size_t Curl_conn_get_max_concurrent(struct Curl_easy *data,
467 struct connectdata *conn,
468 int sockindex);
469
470
471/**
472 * Types and macros used to keep the current easy handle in filter calls,
473 * allowing for nested invocations. See #10336.
474 *
475 * `cf_call_data` is intended to be a member of the cfilter's `ctx` type.
476 * A filter defines the macro `CF_CTX_CALL_DATA` to give access to that.
477 *
478 * With all values 0, the default, this indicates that there is no cfilter
479 * call with `data` ongoing.
480 * Macro `CF_DATA_SAVE` preserves the current `cf_call_data` in a local
481 * variable and sets the `data` given, incrementing the `depth` counter.
482 *
483 * Macro `CF_DATA_RESTORE` restores the old values from the local variable,
484 * while checking that `depth` values are as expected (debug build), catching
485 * cases where a "lower" RESTORE was not called.
486 *
487 * Finally, macro `CF_DATA_CURRENT` gives the easy handle of the current
488 * invocation.
489 */
490struct cf_call_data {
491 struct Curl_easy *data;
492#ifdef DEBUGBUILD
493 int depth;
494#endif
495};
496
497/**
498 * define to access the `struct cf_call_data for a cfilter. Normally
499 * a member in the cfilter's `ctx`.
500 *
501 * #define CF_CTX_CALL_DATA(cf) -> struct cf_call_data instance
502*/
503
504#ifdef DEBUGBUILD
505
506#define CF_DATA_SAVE(save, cf, data) \
507 do { \
508 (save) = CF_CTX_CALL_DATA(cf); \
509 DEBUGASSERT((save).data == NULL || (save).depth > 0); \
510 CF_CTX_CALL_DATA(cf).depth++; \
511 CF_CTX_CALL_DATA(cf).data = (struct Curl_easy *)data; \
512 } while(0)
513
514#define CF_DATA_RESTORE(cf, save) \
515 do { \
516 DEBUGASSERT(CF_CTX_CALL_DATA(cf).depth == (save).depth + 1); \
517 DEBUGASSERT((save).data == NULL || (save).depth > 0); \
518 CF_CTX_CALL_DATA(cf) = (save); \
519 } while(0)
520
521#else /* DEBUGBUILD */
522
523#define CF_DATA_SAVE(save, cf, data) \
524 do { \
525 (save) = CF_CTX_CALL_DATA(cf); \
526 CF_CTX_CALL_DATA(cf).data = (struct Curl_easy *)data; \
527 } while(0)
528
529#define CF_DATA_RESTORE(cf, save) \
530 do { \
531 CF_CTX_CALL_DATA(cf) = (save); \
532 } while(0)
533
534#endif /* !DEBUGBUILD */
535
536#define CF_DATA_CURRENT(cf) \
537 ((cf)? (CF_CTX_CALL_DATA(cf).data) : NULL)
538
539#endif /* HEADER_CURL_CFILTERS_H */
540