mirror of
https://github.com/curl/curl.git
synced 2024-12-27 06:59:43 +08:00
9369c30cd8
- replace `Curl_read()`, `Curl_write()` and `Curl_nwrite()` to
clarify when and at what level they operate
- send/recv of transfer related data is now done via
`Curl_xfer_send()/Curl_xfer_recv()` which no longer has
socket/socketindex as parameter. It decides on the transfer
setup of `conn->sockfd` and `conn->writesockfd` on which
connection filter chain to operate.
- send/recv on a specific connection filter chain is done via
`Curl_conn_send()/Curl_conn_recv()` which get the socket index
as parameter.
- rename `Curl_setup_transfer()` to `Curl_xfer_setup()` for
naming consistency
- clarify that the special CURLE_AGAIN hangling to return
`CURLE_OK` with length 0 only applies to `Curl_xfer_send()`
and CURLE_AGAIN is returned by all other send() variants.
- fix a bug in websocket `curl_ws_recv()` that mixed up data
when it arrived in more than a single chunk (to be made
into a sperate PR, also)
Added as documented [in
CLIENT-READER.md](5b1f31dfba/docs/CLIENT-READERS.md).
- old `Curl_buffer_send()` completely replaced by new `Curl_req_send()`
- old `Curl_fillreadbuffer()` replaced with `Curl_client_read()`
- HTTP chunked uploads are now formatted in a client reader added when
needed.
- FTP line-end conversions are done in a client reader added when
needed.
- when sending requests headers, remaining buffer space is filled with
body data for sending in "one go". This is independent of the request
body size. Resolves #12938 as now small and large requests have the
same code path.
Changes done to test cases:
- test513: now fails before sending request headers as this initial
"client read" triggers the setup fault. Behaves now the same as in
hyper build
- test547, test555, test1620: fix the length check in the lib code to
only fail for reads *smaller* than expected. This was a bug in the
test code that never triggered in the old implementation.
Closes #12969
282 lines
11 KiB
C
282 lines
11 KiB
C
#ifndef HEADER_CURL_SENDF_H
|
|
#define HEADER_CURL_SENDF_H
|
|
/***************************************************************************
|
|
* _ _ ____ _
|
|
* Project ___| | | | _ \| |
|
|
* / __| | | | |_) | |
|
|
* | (__| |_| | _ <| |___
|
|
* \___|\___/|_| \_\_____|
|
|
*
|
|
* Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
*
|
|
* This software is licensed as described in the file COPYING, which
|
|
* you should have received as part of this distribution. The terms
|
|
* are also available at https://curl.se/docs/copyright.html.
|
|
*
|
|
* You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
* copies of the Software, and permit persons to whom the Software is
|
|
* furnished to do so, under the terms of the COPYING file.
|
|
*
|
|
* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
* KIND, either express or implied.
|
|
*
|
|
* SPDX-License-Identifier: curl
|
|
*
|
|
***************************************************************************/
|
|
|
|
#include "curl_setup.h"
|
|
|
|
#include "curl_trc.h"
|
|
|
|
/**
|
|
* Type of data that is being written to the client (application)
|
|
* - data written can be either BODY or META data
|
|
* - META data is either INFO or HEADER
|
|
* - INFO is meta information, e.g. not BODY, that cannot be interpreted
|
|
* as headers of a response. Example FTP/IMAP pingpong answers.
|
|
* - HEADER can have additional bits set (more than one)
|
|
* - STATUS special "header", e.g. response status line in HTTP
|
|
* - CONNECT header was received during proxying the connection
|
|
* - 1XX header is part of an intermediate response, e.g. HTTP 1xx code
|
|
* - TRAILER header is trailing response data, e.g. HTTP trailers
|
|
* BODY, INFO and HEADER should not be mixed, as this would lead to
|
|
* confusion on how to interpret/format/convert the data.
|
|
*/
|
|
#define CLIENTWRITE_BODY (1<<0) /* non-meta information, BODY */
|
|
#define CLIENTWRITE_INFO (1<<1) /* meta information, not a HEADER */
|
|
#define CLIENTWRITE_HEADER (1<<2) /* meta information, HEADER */
|
|
#define CLIENTWRITE_STATUS (1<<3) /* a special status HEADER */
|
|
#define CLIENTWRITE_CONNECT (1<<4) /* a CONNECT related HEADER */
|
|
#define CLIENTWRITE_1XX (1<<5) /* a 1xx response related HEADER */
|
|
#define CLIENTWRITE_TRAILER (1<<6) /* a trailer HEADER */
|
|
#define CLIENTWRITE_EOS (1<<7) /* End Of transfer download Stream */
|
|
|
|
/**
|
|
* Write `len` bytes at `prt` to the client. `type` indicates what
|
|
* kind of data is being written.
|
|
*/
|
|
CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *ptr,
|
|
size_t len) WARN_UNUSED_RESULT;
|
|
|
|
/**
|
|
* Free all resources related to client writing.
|
|
*/
|
|
void Curl_client_reset(struct Curl_easy *data);
|
|
|
|
/**
|
|
* Client Writers - a chain passing transfer BODY data to the client.
|
|
* Main application: HTTP and related protocols
|
|
* Other uses: monitoring of download progress
|
|
*
|
|
* Writers in the chain are order by their `phase`. First come all
|
|
* writers in CURL_CW_RAW, followed by any in CURL_CW_TRANSFER_DECODE,
|
|
* followed by any in CURL_CW_PROTOCOL, etc.
|
|
*
|
|
* When adding a writer, it is inserted as first in its phase. This means
|
|
* the order of adding writers of the same phase matters, but writers for
|
|
* different phases may be added in any order.
|
|
*
|
|
* Writers which do modify the BODY data written are expected to be of
|
|
* phases TRANSFER_DECODE or CONTENT_DECODE. The other phases are intended
|
|
* for monitoring writers. Which do *not* modify the data but gather
|
|
* statistics or update progress reporting.
|
|
*/
|
|
|
|
/* Phase a writer operates at. */
|
|
typedef enum {
|
|
CURL_CW_RAW, /* raw data written, before any decoding */
|
|
CURL_CW_TRANSFER_DECODE, /* remove transfer-encodings */
|
|
CURL_CW_PROTOCOL, /* after transfer, but before content decoding */
|
|
CURL_CW_CONTENT_DECODE, /* remove content-encodings */
|
|
CURL_CW_CLIENT /* data written to client */
|
|
} Curl_cwriter_phase;
|
|
|
|
/* Client Writer Type, provides the implementation */
|
|
struct Curl_cwtype {
|
|
const char *name; /* writer name. */
|
|
const char *alias; /* writer name alias, maybe NULL. */
|
|
CURLcode (*do_init)(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer);
|
|
CURLcode (*do_write)(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer, int type,
|
|
const char *buf, size_t nbytes);
|
|
void (*do_close)(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer);
|
|
size_t cwriter_size; /* sizeof() allocated struct Curl_cwriter */
|
|
};
|
|
|
|
/* Client writer instance */
|
|
struct Curl_cwriter {
|
|
const struct Curl_cwtype *cwt; /* type implementation */
|
|
struct Curl_cwriter *next; /* Downstream writer. */
|
|
Curl_cwriter_phase phase; /* phase at which it operates */
|
|
};
|
|
|
|
/**
|
|
* Create a new cwriter instance with given type and phase. Is not
|
|
* inserted into the writer chain by this call.
|
|
* Invokes `writer->do_init()`.
|
|
*/
|
|
CURLcode Curl_cwriter_create(struct Curl_cwriter **pwriter,
|
|
struct Curl_easy *data,
|
|
const struct Curl_cwtype *ce_handler,
|
|
Curl_cwriter_phase phase);
|
|
|
|
/**
|
|
* Free a cwriter instance.
|
|
* Invokes `writer->do_close()`.
|
|
*/
|
|
void Curl_cwriter_free(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer);
|
|
|
|
/**
|
|
* Count the number of writers installed of the given phase.
|
|
*/
|
|
size_t Curl_cwriter_count(struct Curl_easy *data, Curl_cwriter_phase phase);
|
|
|
|
/**
|
|
* Adds a writer to the transfer's writer chain.
|
|
* The writers `phase` determines where in the chain it is inserted.
|
|
*/
|
|
CURLcode Curl_cwriter_add(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer);
|
|
|
|
/**
|
|
* Look up an installed client writer on `data` by its type.
|
|
* @return first writer with that type or NULL
|
|
*/
|
|
struct Curl_cwriter *Curl_cwriter_get_by_type(struct Curl_easy *data,
|
|
const struct Curl_cwtype *cwt);
|
|
|
|
void Curl_cwriter_remove_by_name(struct Curl_easy *data,
|
|
const char *name);
|
|
|
|
struct Curl_cwriter *Curl_cwriter_get_by_name(struct Curl_easy *data,
|
|
const char *name);
|
|
|
|
/**
|
|
* Convenience method for calling `writer->do_write()` that
|
|
* checks for NULL writer.
|
|
*/
|
|
CURLcode Curl_cwriter_write(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer, int type,
|
|
const char *buf, size_t nbytes);
|
|
|
|
/**
|
|
* Default implementations for do_init, do_write, do_close that
|
|
* do nothing and pass the data through.
|
|
*/
|
|
CURLcode Curl_cwriter_def_init(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer);
|
|
CURLcode Curl_cwriter_def_write(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer, int type,
|
|
const char *buf, size_t nbytes);
|
|
void Curl_cwriter_def_close(struct Curl_easy *data,
|
|
struct Curl_cwriter *writer);
|
|
|
|
|
|
/* Client Reader Type, provides the implementation */
|
|
struct Curl_crtype {
|
|
const char *name; /* writer name. */
|
|
CURLcode (*do_init)(struct Curl_easy *data, struct Curl_creader *writer);
|
|
CURLcode (*do_read)(struct Curl_easy *data, struct Curl_creader *reader,
|
|
char *buf, size_t blen, size_t *nread, bool *eos);
|
|
void (*do_close)(struct Curl_easy *data, struct Curl_creader *reader);
|
|
bool (*needs_rewind)(struct Curl_easy *data, struct Curl_creader *reader);
|
|
size_t creader_size; /* sizeof() allocated struct Curl_creader */
|
|
};
|
|
|
|
/* Phase a reader operates at. */
|
|
typedef enum {
|
|
CURL_CR_NET, /* data send to the network (connection filters) */
|
|
CURL_CR_TRANSFER_ENCODE, /* add transfer-encodings */
|
|
CURL_CR_PROTOCOL, /* before transfer, but after content decoding */
|
|
CURL_CR_CONTENT_ENCODE, /* add content-encodings */
|
|
CURL_CR_CLIENT /* data read from client */
|
|
} Curl_creader_phase;
|
|
|
|
/* Client reader instance */
|
|
struct Curl_creader {
|
|
const struct Curl_crtype *crt; /* type implementation */
|
|
struct Curl_creader *next; /* Downstream reader. */
|
|
Curl_creader_phase phase; /* phase at which it operates */
|
|
};
|
|
|
|
/**
|
|
* Default implementations for do_init, do_write, do_close that
|
|
* do nothing and pass the data through.
|
|
*/
|
|
CURLcode Curl_creader_def_init(struct Curl_easy *data,
|
|
struct Curl_creader *reader);
|
|
void Curl_creader_def_close(struct Curl_easy *data,
|
|
struct Curl_creader *reader);
|
|
bool Curl_creader_def_needs_rewind(struct Curl_easy *data,
|
|
struct Curl_creader *reader);
|
|
|
|
/**
|
|
* Convenience method for calling `reader->do_read()` that
|
|
* checks for NULL reader.
|
|
*/
|
|
CURLcode Curl_creader_read(struct Curl_easy *data,
|
|
struct Curl_creader *reader,
|
|
char *buf, size_t blen, size_t *nread, bool *eos);
|
|
|
|
/**
|
|
* Create a new creader instance with given type and phase. Is not
|
|
* inserted into the writer chain by this call.
|
|
* Invokes `reader->do_init()`.
|
|
*/
|
|
CURLcode Curl_creader_create(struct Curl_creader **preader,
|
|
struct Curl_easy *data,
|
|
const struct Curl_crtype *cr_handler,
|
|
Curl_creader_phase phase);
|
|
|
|
/**
|
|
* Free a creader instance.
|
|
* Invokes `reader->do_close()`.
|
|
*/
|
|
void Curl_creader_free(struct Curl_easy *data, struct Curl_creader *reader);
|
|
|
|
/**
|
|
* Adds a reader to the transfer's reader chain.
|
|
* The readers `phase` determines where in the chain it is inserted.
|
|
*/
|
|
CURLcode Curl_creader_add(struct Curl_easy *data,
|
|
struct Curl_creader *reader);
|
|
|
|
/**
|
|
* Read at most `blen` bytes at `buf` from the client.
|
|
* @param date the transfer to read client bytes for
|
|
* @param buf the memory location to read to
|
|
* @param blen the amount of memory at `buf`
|
|
* @param nread on return the number of bytes read into `buf`
|
|
* @param eos TRUE iff bytes are the end of data from client
|
|
* @return CURLE_OK on successful read (even 0 length) or error
|
|
*/
|
|
CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen,
|
|
size_t *nread, bool *eos) WARN_UNUSED_RESULT;
|
|
|
|
/**
|
|
* TRUE iff client reader needs rewing before it can be used for
|
|
* a retry request.
|
|
*/
|
|
bool Curl_client_read_needs_rewind(struct Curl_easy *data);
|
|
|
|
/**
|
|
* Set the client reader to provide 0 bytes, immediate EOS.
|
|
*/
|
|
CURLcode Client_reader_set_null(struct Curl_easy *data);
|
|
|
|
/**
|
|
* Set the client reader the reads from fread callback.
|
|
*/
|
|
CURLcode Client_reader_set_fread(struct Curl_easy *data, curl_off_t len);
|
|
|
|
/**
|
|
* Set the client reader the reads from the supplied buf (NOT COPIED).
|
|
*/
|
|
CURLcode Client_reader_set_buf(struct Curl_easy *data,
|
|
const char *buf, size_t blen);
|
|
|
|
#endif /* HEADER_CURL_SENDF_H */
|