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 28 struct Curl_cfilter; 29 struct Curl_easy; 30 struct Curl_dns_entry; 31 struct connectdata; 32 33 /* Callback to destroy resources held by this filter instance. 34 * Implementations MUST NOT chain calls to cf->next. 35 */ 36 typedef void Curl_cft_destroy_this(struct Curl_cfilter *cf, 37 struct Curl_easy *data); 38 39 typedef void Curl_cft_close(struct Curl_cfilter *cf, 40 struct Curl_easy *data); 41 42 typedef 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 */ 57 typedef 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 */ 68 typedef int Curl_cft_get_select_socks(struct Curl_cfilter *cf, 69 struct Curl_easy *data, 70 curl_socket_t *socks); 71 72 typedef bool Curl_cft_data_pending(struct Curl_cfilter *cf, 73 const struct Curl_easy *data); 74 75 typedef 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 81 typedef 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 87 typedef bool Curl_cft_conn_is_alive(struct Curl_cfilter *cf, 88 struct Curl_easy *data, 89 bool *input_pending); 90 91 typedef 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 */ 118 typedef 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 */ 147 typedef 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. */ 166 struct 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 */ 185 struct 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. */ 195 void 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. */ 200 void Curl_cf_def_get_host(struct Curl_cfilter *cf, struct Curl_easy *data, 201 const char **phost, const char **pdisplay_host, 202 int *pport); 203 int Curl_cf_def_get_select_socks(struct Curl_cfilter *cf, 204 struct Curl_easy *data, 205 curl_socket_t *socks); 206 bool Curl_cf_def_data_pending(struct Curl_cfilter *cf, 207 const struct Curl_easy *data); 208 ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data, 209 const void *buf, size_t len, CURLcode *err); 210 ssize_t Curl_cf_def_recv(struct Curl_cfilter *cf, struct Curl_easy *data, 211 char *buf, size_t len, CURLcode *err); 212 CURLcode Curl_cf_def_cntrl(struct Curl_cfilter *cf, 213 struct Curl_easy *data, 214 int event, int arg1, void *arg2); 215 bool Curl_cf_def_conn_is_alive(struct Curl_cfilter *cf, 216 struct Curl_easy *data, 217 bool *input_pending); 218 CURLcode Curl_cf_def_conn_keep_alive(struct Curl_cfilter *cf, 219 struct Curl_easy *data); 220 CURLcode 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 */ 231 CURLcode 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 */ 240 void 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 */ 249 void 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 */ 259 bool 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 */ 267 void 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 */ 273 void Curl_conn_cf_discard_all(struct Curl_easy *data, 274 struct connectdata *conn, 275 int sockindex); 276 277 278 CURLcode Curl_conn_cf_connect(struct Curl_cfilter *cf, 279 struct Curl_easy *data, 280 bool blocking, bool *done); 281 void Curl_conn_cf_close(struct Curl_cfilter *cf, struct Curl_easy *data); 282 int Curl_conn_cf_get_select_socks(struct Curl_cfilter *cf, 283 struct Curl_easy *data, 284 curl_socket_t *socks); 285 ssize_t Curl_conn_cf_send(struct Curl_cfilter *cf, struct Curl_easy *data, 286 const void *buf, size_t len, CURLcode *err); 287 ssize_t Curl_conn_cf_recv(struct Curl_cfilter *cf, struct Curl_easy *data, 288 char *buf, size_t len, CURLcode *err); 289 CURLcode 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 */ 298 bool 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 */ 304 curl_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 */ 319 CURLcode 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 */ 326 bool 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 */ 333 bool 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 */ 340 bool Curl_conn_is_ssl(struct connectdata *conn, int sockindex); 341 342 /** 343 * Connection provides multiplexing of easy handles at `socketindex`. 344 */ 345 bool 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 */ 351 void 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 */ 357 bool 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 */ 364 curl_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 */ 370 int 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 */ 379 ssize_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 */ 388 ssize_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 */ 396 void 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 */ 406 void 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 */ 413 CURLcode 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 */ 419 CURLcode 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 */ 425 void 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 */ 431 void 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 */ 436 CURLcode 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 */ 441 void 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 */ 447 bool 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 */ 453 CURLcode Curl_conn_keep_alive(struct Curl_easy *data, 454 struct connectdata *conn, 455 int sockindex); 456 457 void Curl_cf_def_close(struct Curl_cfilter *cf, struct Curl_easy *data); 458 void 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 */ 466 size_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 */ 490 struct 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