| 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 |
|
|---|
| 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 | /* Setup the connection for `data`, using destination `remotehost`.
|
|---|
| 40 | */
|
|---|
| 41 | typedef CURLcode Curl_cft_setup(struct Curl_cfilter *cf,
|
|---|
| 42 | struct Curl_easy *data,
|
|---|
| 43 | const struct Curl_dns_entry *remotehost);
|
|---|
| 44 | typedef void Curl_cft_close(struct Curl_cfilter *cf,
|
|---|
| 45 | struct Curl_easy *data);
|
|---|
| 46 |
|
|---|
| 47 | typedef 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 | */
|
|---|
| 62 | typedef 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 | */
|
|---|
| 73 | typedef int Curl_cft_get_select_socks(struct Curl_cfilter *cf,
|
|---|
| 74 | struct Curl_easy *data,
|
|---|
| 75 | curl_socket_t *socks);
|
|---|
| 76 |
|
|---|
| 77 | typedef bool Curl_cft_data_pending(struct Curl_cfilter *cf,
|
|---|
| 78 | const struct Curl_easy *data);
|
|---|
| 79 |
|
|---|
| 80 | typedef 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 |
|
|---|
| 86 | typedef 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 |
|
|---|
| 92 | typedef void Curl_cft_attach_data(struct Curl_cfilter *cf,
|
|---|
| 93 | struct Curl_easy *data);
|
|---|
| 94 | typedef 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 | */
|
|---|
| 104 | void 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. */
|
|---|
| 110 | struct 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 */
|
|---|
| 127 | struct 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. */
|
|---|
| 137 | void 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. */
|
|---|
| 142 | CURLcode Curl_cf_def_setup(struct Curl_cfilter *cf,
|
|---|
| 143 | struct Curl_easy *data,
|
|---|
| 144 | const struct Curl_dns_entry *remotehost);
|
|---|
| 145 | void Curl_cf_def_close(struct Curl_cfilter *cf, struct Curl_easy *data);
|
|---|
| 146 | CURLcode Curl_cf_def_connect(struct Curl_cfilter *cf,
|
|---|
| 147 | struct Curl_easy *data,
|
|---|
| 148 | bool blocking, bool *done);
|
|---|
| 149 | void Curl_cf_def_get_host(struct Curl_cfilter *cf, struct Curl_easy *data,
|
|---|
| 150 | const char **phost, const char **pdisplay_host,
|
|---|
| 151 | int *pport);
|
|---|
| 152 | int Curl_cf_def_get_select_socks(struct Curl_cfilter *cf,
|
|---|
| 153 | struct Curl_easy *data,
|
|---|
| 154 | curl_socket_t *socks);
|
|---|
| 155 | bool Curl_cf_def_data_pending(struct Curl_cfilter *cf,
|
|---|
| 156 | const struct Curl_easy *data);
|
|---|
| 157 | ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
|
|---|
| 158 | const void *buf, size_t len, CURLcode *err);
|
|---|
| 159 | ssize_t Curl_cf_def_recv(struct Curl_cfilter *cf, struct Curl_easy *data,
|
|---|
| 160 | char *buf, size_t len, CURLcode *err);
|
|---|
| 161 | void Curl_cf_def_attach_data(struct Curl_cfilter *cf,
|
|---|
| 162 | struct Curl_easy *data);
|
|---|
| 163 | void 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 | */
|
|---|
| 173 | CURLcode 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 | */
|
|---|
| 182 | void 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 | */
|
|---|
| 190 | void 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 | */
|
|---|
| 199 | void Curl_conn_cf_discard(struct Curl_cfilter *cf, struct Curl_easy *data);
|
|---|
| 200 |
|
|---|
| 201 |
|
|---|
| 202 | ssize_t Curl_conn_cf_send(struct Curl_cfilter *cf, struct Curl_easy *data,
|
|---|
| 203 | const void *buf, size_t len, CURLcode *err);
|
|---|
| 204 | ssize_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 | */
|
|---|
| 217 | CURLcode 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 | */
|
|---|
| 230 | CURLcode 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 | */
|
|---|
| 237 | bool 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 | */
|
|---|
| 244 | bool 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 | */
|
|---|
| 251 | bool 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 | */
|
|---|
| 257 | void 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 | */
|
|---|
| 263 | bool 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 | */
|
|---|
| 270 | int 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 | */
|
|---|
| 279 | ssize_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 | */
|
|---|
| 288 | ssize_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 | */
|
|---|
| 297 | void 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 | */
|
|---|
| 307 | void Curl_conn_detach_data(struct connectdata *conn,
|
|---|
| 308 | struct Curl_easy *data);
|
|---|
| 309 |
|
|---|
| 310 | void 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 */
|
|---|