sendf.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407
  1. #ifndef HEADER_CURL_SENDF_H
  2. #define HEADER_CURL_SENDF_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. #include "curl_setup.h"
  27. #include "curl_trc.h"
  28. /**
  29. * Type of data that is being written to the client (application)
  30. * - data written can be either BODY or META data
  31. * - META data is either INFO or HEADER
  32. * - INFO is meta information, e.g. not BODY, that cannot be interpreted
  33. * as headers of a response. Example FTP/IMAP pingpong answers.
  34. * - HEADER can have additional bits set (more than one)
  35. * - STATUS special "header", e.g. response status line in HTTP
  36. * - CONNECT header was received during proxying the connection
  37. * - 1XX header is part of an intermediate response, e.g. HTTP 1xx code
  38. * - TRAILER header is trailing response data, e.g. HTTP trailers
  39. * BODY, INFO and HEADER should not be mixed, as this would lead to
  40. * confusion on how to interpret/format/convert the data.
  41. */
  42. #define CLIENTWRITE_BODY (1<<0) /* non-meta information, BODY */
  43. #define CLIENTWRITE_INFO (1<<1) /* meta information, not a HEADER */
  44. #define CLIENTWRITE_HEADER (1<<2) /* meta information, HEADER */
  45. #define CLIENTWRITE_STATUS (1<<3) /* a special status HEADER */
  46. #define CLIENTWRITE_CONNECT (1<<4) /* a CONNECT related HEADER */
  47. #define CLIENTWRITE_1XX (1<<5) /* a 1xx response related HEADER */
  48. #define CLIENTWRITE_TRAILER (1<<6) /* a trailer HEADER */
  49. #define CLIENTWRITE_EOS (1<<7) /* End Of transfer download Stream */
  50. /**
  51. * Write `len` bytes at `prt` to the client. `type` indicates what
  52. * kind of data is being written.
  53. */
  54. CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *ptr,
  55. size_t len) WARN_UNUSED_RESULT;
  56. /**
  57. * Free all resources related to client writing.
  58. */
  59. void Curl_client_cleanup(struct Curl_easy *data);
  60. /**
  61. * Reset readers and writer chains, keep rewind information
  62. * when necessary.
  63. */
  64. void Curl_client_reset(struct Curl_easy *data);
  65. /**
  66. * A new request is starting, perform any ops like rewinding
  67. * previous readers when needed.
  68. */
  69. CURLcode Curl_client_start(struct Curl_easy *data);
  70. /**
  71. * Client Writers - a chain passing transfer BODY data to the client.
  72. * Main application: HTTP and related protocols
  73. * Other uses: monitoring of download progress
  74. *
  75. * Writers in the chain are order by their `phase`. First come all
  76. * writers in CURL_CW_RAW, followed by any in CURL_CW_TRANSFER_DECODE,
  77. * followed by any in CURL_CW_PROTOCOL, etc.
  78. *
  79. * When adding a writer, it is inserted as first in its phase. This means
  80. * the order of adding writers of the same phase matters, but writers for
  81. * different phases may be added in any order.
  82. *
  83. * Writers which do modify the BODY data written are expected to be of
  84. * phases TRANSFER_DECODE or CONTENT_DECODE. The other phases are intended
  85. * for monitoring writers. Which do *not* modify the data but gather
  86. * statistics or update progress reporting.
  87. */
  88. /* Phase a writer operates at. */
  89. typedef enum {
  90. CURL_CW_RAW, /* raw data written, before any decoding */
  91. CURL_CW_TRANSFER_DECODE, /* remove transfer-encodings */
  92. CURL_CW_PROTOCOL, /* after transfer, but before content decoding */
  93. CURL_CW_CONTENT_DECODE, /* remove content-encodings */
  94. CURL_CW_CLIENT /* data written to client */
  95. } Curl_cwriter_phase;
  96. /* Client Writer Type, provides the implementation */
  97. struct Curl_cwtype {
  98. const char *name; /* writer name. */
  99. const char *alias; /* writer name alias, maybe NULL. */
  100. CURLcode (*do_init)(struct Curl_easy *data,
  101. struct Curl_cwriter *writer);
  102. CURLcode (*do_write)(struct Curl_easy *data,
  103. struct Curl_cwriter *writer, int type,
  104. const char *buf, size_t nbytes);
  105. void (*do_close)(struct Curl_easy *data,
  106. struct Curl_cwriter *writer);
  107. size_t cwriter_size; /* sizeof() allocated struct Curl_cwriter */
  108. };
  109. /* Client writer instance, allocated on creation.
  110. * `void *ctx` is the pointer from the allocation of
  111. * the `struct Curl_cwriter` itself. This is suitable for "downcasting"
  112. * by the writers implementation. See https://github.com/curl/curl/pull/13054
  113. * for the alignment problems that arise otherwise.
  114. */
  115. struct Curl_cwriter {
  116. const struct Curl_cwtype *cwt; /* type implementation */
  117. struct Curl_cwriter *next; /* Downstream writer. */
  118. void *ctx; /* allocated instance pointer */
  119. Curl_cwriter_phase phase; /* phase at which it operates */
  120. };
  121. /**
  122. * Create a new cwriter instance with given type and phase. Is not
  123. * inserted into the writer chain by this call.
  124. * Invokes `writer->do_init()`.
  125. */
  126. CURLcode Curl_cwriter_create(struct Curl_cwriter **pwriter,
  127. struct Curl_easy *data,
  128. const struct Curl_cwtype *ce_handler,
  129. Curl_cwriter_phase phase);
  130. /**
  131. * Free a cwriter instance.
  132. * Invokes `writer->do_close()`.
  133. */
  134. void Curl_cwriter_free(struct Curl_easy *data,
  135. struct Curl_cwriter *writer);
  136. /**
  137. * Count the number of writers installed of the given phase.
  138. */
  139. size_t Curl_cwriter_count(struct Curl_easy *data, Curl_cwriter_phase phase);
  140. /**
  141. * Adds a writer to the transfer's writer chain.
  142. * The writers `phase` determines where in the chain it is inserted.
  143. */
  144. CURLcode Curl_cwriter_add(struct Curl_easy *data,
  145. struct Curl_cwriter *writer);
  146. /**
  147. * Look up an installed client writer on `data` by its type.
  148. * @return first writer with that type or NULL
  149. */
  150. struct Curl_cwriter *Curl_cwriter_get_by_type(struct Curl_easy *data,
  151. const struct Curl_cwtype *cwt);
  152. void Curl_cwriter_remove_by_name(struct Curl_easy *data,
  153. const char *name);
  154. struct Curl_cwriter *Curl_cwriter_get_by_name(struct Curl_easy *data,
  155. const char *name);
  156. /**
  157. * Convenience method for calling `writer->do_write()` that
  158. * checks for NULL writer.
  159. */
  160. CURLcode Curl_cwriter_write(struct Curl_easy *data,
  161. struct Curl_cwriter *writer, int type,
  162. const char *buf, size_t nbytes);
  163. /**
  164. * Return TRUE iff client writer is paused.
  165. */
  166. bool Curl_cwriter_is_paused(struct Curl_easy *data);
  167. /**
  168. * Unpause client writer and flush any buffered date to the client.
  169. */
  170. CURLcode Curl_cwriter_unpause(struct Curl_easy *data);
  171. /**
  172. * Default implementations for do_init, do_write, do_close that
  173. * do nothing and pass the data through.
  174. */
  175. CURLcode Curl_cwriter_def_init(struct Curl_easy *data,
  176. struct Curl_cwriter *writer);
  177. CURLcode Curl_cwriter_def_write(struct Curl_easy *data,
  178. struct Curl_cwriter *writer, int type,
  179. const char *buf, size_t nbytes);
  180. void Curl_cwriter_def_close(struct Curl_easy *data,
  181. struct Curl_cwriter *writer);
  182. /* Client Reader Type, provides the implementation */
  183. struct Curl_crtype {
  184. const char *name; /* writer name. */
  185. CURLcode (*do_init)(struct Curl_easy *data, struct Curl_creader *reader);
  186. CURLcode (*do_read)(struct Curl_easy *data, struct Curl_creader *reader,
  187. char *buf, size_t blen, size_t *nread, bool *eos);
  188. void (*do_close)(struct Curl_easy *data, struct Curl_creader *reader);
  189. bool (*needs_rewind)(struct Curl_easy *data, struct Curl_creader *reader);
  190. curl_off_t (*total_length)(struct Curl_easy *data,
  191. struct Curl_creader *reader);
  192. CURLcode (*resume_from)(struct Curl_easy *data,
  193. struct Curl_creader *reader, curl_off_t offset);
  194. CURLcode (*rewind)(struct Curl_easy *data, struct Curl_creader *reader);
  195. CURLcode (*unpause)(struct Curl_easy *data, struct Curl_creader *reader);
  196. void (*done)(struct Curl_easy *data,
  197. struct Curl_creader *reader, int premature);
  198. size_t creader_size; /* sizeof() allocated struct Curl_creader */
  199. };
  200. /* Phase a reader operates at. */
  201. typedef enum {
  202. CURL_CR_NET, /* data send to the network (connection filters) */
  203. CURL_CR_TRANSFER_ENCODE, /* add transfer-encodings */
  204. CURL_CR_PROTOCOL, /* before transfer, but after content decoding */
  205. CURL_CR_CONTENT_ENCODE, /* add content-encodings */
  206. CURL_CR_CLIENT /* data read from client */
  207. } Curl_creader_phase;
  208. /* Client reader instance, allocated on creation.
  209. * `void *ctx` is the pointer from the allocation of
  210. * the `struct Curl_cwriter` itself. This is suitable for "downcasting"
  211. * by the writers implementation. See https://github.com/curl/curl/pull/13054
  212. * for the alignment problems that arise otherwise.
  213. */
  214. struct Curl_creader {
  215. const struct Curl_crtype *crt; /* type implementation */
  216. struct Curl_creader *next; /* Downstream reader. */
  217. void *ctx;
  218. Curl_creader_phase phase; /* phase at which it operates */
  219. };
  220. /**
  221. * Default implementations for do_init, do_write, do_close that
  222. * do nothing and pass the data through.
  223. */
  224. CURLcode Curl_creader_def_init(struct Curl_easy *data,
  225. struct Curl_creader *reader);
  226. void Curl_creader_def_close(struct Curl_easy *data,
  227. struct Curl_creader *reader);
  228. CURLcode Curl_creader_def_read(struct Curl_easy *data,
  229. struct Curl_creader *reader,
  230. char *buf, size_t blen,
  231. size_t *nread, bool *eos);
  232. bool Curl_creader_def_needs_rewind(struct Curl_easy *data,
  233. struct Curl_creader *reader);
  234. curl_off_t Curl_creader_def_total_length(struct Curl_easy *data,
  235. struct Curl_creader *reader);
  236. CURLcode Curl_creader_def_resume_from(struct Curl_easy *data,
  237. struct Curl_creader *reader,
  238. curl_off_t offset);
  239. CURLcode Curl_creader_def_rewind(struct Curl_easy *data,
  240. struct Curl_creader *reader);
  241. CURLcode Curl_creader_def_unpause(struct Curl_easy *data,
  242. struct Curl_creader *reader);
  243. void Curl_creader_def_done(struct Curl_easy *data,
  244. struct Curl_creader *reader, int premature);
  245. /**
  246. * Convenience method for calling `reader->do_read()` that
  247. * checks for NULL reader.
  248. */
  249. CURLcode Curl_creader_read(struct Curl_easy *data,
  250. struct Curl_creader *reader,
  251. char *buf, size_t blen, size_t *nread, bool *eos);
  252. /**
  253. * Create a new creader instance with given type and phase. Is not
  254. * inserted into the writer chain by this call.
  255. * Invokes `reader->do_init()`.
  256. */
  257. CURLcode Curl_creader_create(struct Curl_creader **preader,
  258. struct Curl_easy *data,
  259. const struct Curl_crtype *cr_handler,
  260. Curl_creader_phase phase);
  261. /**
  262. * Free a creader instance.
  263. * Invokes `reader->do_close()`.
  264. */
  265. void Curl_creader_free(struct Curl_easy *data, struct Curl_creader *reader);
  266. /**
  267. * Adds a reader to the transfer's reader chain.
  268. * The readers `phase` determines where in the chain it is inserted.
  269. */
  270. CURLcode Curl_creader_add(struct Curl_easy *data,
  271. struct Curl_creader *reader);
  272. /**
  273. * Set the given reader, which needs to be of type CURL_CR_CLIENT,
  274. * as the new first reader. Discard any installed readers and init
  275. * the reader chain anew.
  276. * The function takes ownership of `r`.
  277. */
  278. CURLcode Curl_creader_set(struct Curl_easy *data, struct Curl_creader *r);
  279. /**
  280. * Read at most `blen` bytes at `buf` from the client.
  281. * @param data the transfer to read client bytes for
  282. * @param buf the memory location to read to
  283. * @param blen the amount of memory at `buf`
  284. * @param nread on return the number of bytes read into `buf`
  285. * @param eos TRUE iff bytes are the end of data from client
  286. * @return CURLE_OK on successful read (even 0 length) or error
  287. */
  288. CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen,
  289. size_t *nread, bool *eos) WARN_UNUSED_RESULT;
  290. /**
  291. * TRUE iff client reader needs rewing before it can be used for
  292. * a retry request.
  293. */
  294. bool Curl_creader_needs_rewind(struct Curl_easy *data);
  295. /**
  296. * TRUE iff client reader will rewind at next start
  297. */
  298. bool Curl_creader_will_rewind(struct Curl_easy *data);
  299. /**
  300. * En-/disable rewind of client reader at next start.
  301. */
  302. void Curl_creader_set_rewind(struct Curl_easy *data, bool enable);
  303. /**
  304. * Get the total length of bytes provided by the installed readers.
  305. * This is independent of the amount already delivered and is calculated
  306. * by all readers in the stack. If a reader like "chunked" or
  307. * "crlf conversion" is installed, the returned length will be -1.
  308. * @return -1 if length is indeterminate
  309. */
  310. curl_off_t Curl_creader_total_length(struct Curl_easy *data);
  311. /**
  312. * Get the total length of bytes provided by the reader at phase
  313. * CURL_CR_CLIENT. This may not match the amount of bytes read
  314. * for a request, depending if other, encoding readers are also installed.
  315. * However it allows for rough estimation of the overall length.
  316. * @return -1 if length is indeterminate
  317. */
  318. curl_off_t Curl_creader_client_length(struct Curl_easy *data);
  319. /**
  320. * Ask the installed reader at phase CURL_CR_CLIENT to start
  321. * reading from the given offset. On success, this will reduce
  322. * the `total_length()` by the amount.
  323. * @param data the transfer to read client bytes for
  324. * @param offset the offset where to start reads from, negative
  325. * values will be ignored.
  326. * @return CURLE_OK if offset could be set
  327. * CURLE_READ_ERROR if not supported by reader or seek/read failed
  328. * of offset larger then total length
  329. * CURLE_PARTIAL_FILE if offset led to 0 total length
  330. */
  331. CURLcode Curl_creader_resume_from(struct Curl_easy *data, curl_off_t offset);
  332. /**
  333. * Unpause all installed readers.
  334. */
  335. CURLcode Curl_creader_unpause(struct Curl_easy *data);
  336. /**
  337. * Tell all client readers that they are done.
  338. */
  339. void Curl_creader_done(struct Curl_easy *data, int premature);
  340. /**
  341. * Look up an installed client reader on `data` by its type.
  342. * @return first reader with that type or NULL
  343. */
  344. struct Curl_creader *Curl_creader_get_by_type(struct Curl_easy *data,
  345. const struct Curl_crtype *crt);
  346. /**
  347. * Set the client reader to provide 0 bytes, immediate EOS.
  348. */
  349. CURLcode Curl_creader_set_null(struct Curl_easy *data);
  350. /**
  351. * Set the client reader the reads from fread callback.
  352. */
  353. CURLcode Curl_creader_set_fread(struct Curl_easy *data, curl_off_t len);
  354. /**
  355. * Set the client reader the reads from the supplied buf (NOT COPIED).
  356. */
  357. CURLcode Curl_creader_set_buf(struct Curl_easy *data,
  358. const char *buf, size_t blen);
  359. #endif /* HEADER_CURL_SENDF_H */