read.hpp 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845
  1. //
  2. // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
  3. //
  4. // Distributed under the Boost Software License, Version 1.0. (See accompanying
  5. // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  6. //
  7. // Official repository: https://github.com/boostorg/beast
  8. //
  9. #ifndef BOOST_BEAST_HTTP_READ_HPP
  10. #define BOOST_BEAST_HTTP_READ_HPP
  11. #include <boost/beast/core/detail/config.hpp>
  12. #include <boost/beast/core/error.hpp>
  13. #include <boost/beast/core/stream_traits.hpp>
  14. #include <boost/beast/http/basic_parser.hpp>
  15. #include <boost/beast/http/message.hpp>
  16. #include <boost/asio/async_result.hpp>
  17. namespace boost {
  18. namespace beast {
  19. namespace http {
  20. //------------------------------------------------------------------------------
  21. /** Read part of a message from a stream using a parser.
  22. This function is used to read part of a message from a stream into an
  23. instance of @ref basic_parser. The call will block until one of the
  24. following conditions is true:
  25. @li A call to @ref basic_parser::put with a non-empty buffer sequence
  26. is successful.
  27. @li An error occurs.
  28. This operation is implemented in terms of one or more calls to the stream's
  29. `read_some` function. The implementation may read additional bytes from
  30. the stream that lie past the end of the message being read. These additional
  31. bytes are stored in the dynamic buffer, which must be preserved for
  32. subsequent reads.
  33. If the end of file error is received while reading from the stream, then
  34. the error returned from this function will be:
  35. @li @ref error::end_of_stream if no bytes were parsed, or
  36. @li @ref error::partial_message if any bytes were parsed but the
  37. message was incomplete, otherwise:
  38. @li A successful result. The next attempt to read will return
  39. @ref error::end_of_stream
  40. @param stream The stream from which the data is to be read. The type must
  41. meet the <em>SyncReadStream</em> requirements.
  42. @param buffer Storage for additional bytes read by the implementation from
  43. the stream. This is both an input and an output parameter; on entry, the
  44. parser will be presented with any remaining data in the dynamic buffer's
  45. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  46. requirements.
  47. @param parser The parser to use.
  48. @return The number of bytes consumed by the parser.
  49. @throws system_error Thrown on failure.
  50. */
  51. template<
  52. class SyncReadStream,
  53. class DynamicBuffer,
  54. bool isRequest>
  55. std::size_t
  56. read_some(
  57. SyncReadStream& stream,
  58. DynamicBuffer& buffer,
  59. basic_parser<isRequest>& parser);
  60. /** Read part of a message from a stream using a parser.
  61. This function is used to read part of a message from a stream into an
  62. instance of @ref basic_parser. The call will block until one of the
  63. following conditions is true:
  64. @li A call to @ref basic_parser::put with a non-empty buffer sequence
  65. is successful.
  66. @li An error occurs.
  67. This operation is implemented in terms of one or more calls to the stream's
  68. `read_some` function. The implementation may read additional bytes from
  69. the stream that lie past the end of the message being read. These additional
  70. bytes are stored in the dynamic buffer, which must be preserved for
  71. subsequent reads.
  72. If the end of file error is received while reading from the stream, then
  73. the error returned from this function will be:
  74. @li @ref error::end_of_stream if no bytes were parsed, or
  75. @li @ref error::partial_message if any bytes were parsed but the
  76. message was incomplete, otherwise:
  77. @li A successful result. The next attempt to read will return
  78. @ref error::end_of_stream
  79. @param stream The stream from which the data is to be read. The type must
  80. support the <em>SyncReadStream</em> requirements.
  81. @param buffer Storage for additional bytes read by the implementation from
  82. the stream. This is both an input and an output parameter; on entry, the
  83. parser will be presented with any remaining data in the dynamic buffer's
  84. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  85. requirements.
  86. @param parser The parser to use.
  87. @param ec Set to the error, if any occurred.
  88. @return The number of bytes consumed by the parser.
  89. */
  90. template<
  91. class SyncReadStream,
  92. class DynamicBuffer,
  93. bool isRequest>
  94. std::size_t
  95. read_some(
  96. SyncReadStream& stream,
  97. DynamicBuffer& buffer,
  98. basic_parser<isRequest>& parser,
  99. error_code& ec);
  100. /** Read part of a message asynchronously from a stream using a parser.
  101. This function is used to asynchronously read part of a message from
  102. a stream into an instance of @ref basic_parser. The function call
  103. always returns immediately. The asynchronous operation will continue
  104. until one of the following conditions is true:
  105. @li A call to @ref basic_parser::put with a non-empty buffer sequence
  106. is successful.
  107. @li An error occurs.
  108. This operation is implemented in terms of zero or more calls to the
  109. next layer's `async_read_some` function, and is known as a <em>composed
  110. operation</em>. The program must ensure that the stream performs no other
  111. reads until this operation completes. The implementation may read additional
  112. bytes from the stream that lie past the end of the message being read.
  113. These additional bytes are stored in the dynamic buffer, which must be
  114. preserved for subsequent reads.
  115. If the end of file error is received while reading from the stream, then
  116. the error returned from this function will be:
  117. @li @ref error::end_of_stream if no bytes were parsed, or
  118. @li @ref error::partial_message if any bytes were parsed but the
  119. message was incomplete, otherwise:
  120. @li A successful result. The next attempt to read will return
  121. @ref error::end_of_stream
  122. @param stream The stream from which the data is to be read. The type
  123. must meet the <em>AsyncReadStream</em> requirements.
  124. @param buffer Storage for additional bytes read by the implementation from
  125. the stream. This is both an input and an output parameter; on entry, the
  126. parser will be presented with any remaining data in the dynamic buffer's
  127. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  128. requirements. The object must remain valid at least until the handler
  129. is called; ownership is not transferred.
  130. @param parser The parser to use. The object must remain valid at least until
  131. the handler is called; ownership is not transferred.
  132. @param handler The completion handler to invoke when the operation
  133. completes. The implementation takes ownership of the handler by
  134. performing a decay-copy. The equivalent function signature of
  135. the handler must be:
  136. @code
  137. void handler(
  138. error_code const& error, // result of operation
  139. std::size_t bytes_transferred // the number of bytes consumed by the parser
  140. );
  141. @endcode
  142. If the handler has an associated immediate executor,
  143. an immediate completion will be dispatched to it.
  144. Otherwise, the handler will not be invoked from within
  145. this function. Invocation of the handler will be performed in a
  146. manner equivalent to using `net::post`.
  147. @par Per-Operation Cancellation
  148. This asynchronous operation supports cancellation for the following
  149. net::cancellation_type values:
  150. @li @c net::cancellation_type::terminal
  151. if the `stream` also supports terminal cancellation, `terminal`
  152. cancellation leaves the stream in an undefined state, so that only
  153. closing it is guaranteed to succeed.
  154. */
  155. template<
  156. class AsyncReadStream,
  157. class DynamicBuffer,
  158. bool isRequest,
  159. BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
  160. net::default_completion_token_t<
  161. executor_type<AsyncReadStream>>>
  162. BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
  163. async_read_some(
  164. AsyncReadStream& stream,
  165. DynamicBuffer& buffer,
  166. basic_parser<isRequest>& parser,
  167. ReadHandler&& handler =
  168. net::default_completion_token_t<
  169. executor_type<AsyncReadStream>>{});
  170. //------------------------------------------------------------------------------
  171. /** Read a complete message header from a stream using a parser.
  172. This function is used to read a complete message header from a stream
  173. into an instance of @ref basic_parser. The call will block until one of the
  174. following conditions is true:
  175. @li @ref basic_parser::is_header_done returns `true`
  176. @li An error occurs.
  177. This operation is implemented in terms of one or more calls to the stream's
  178. `read_some` function. The implementation may read additional bytes from
  179. the stream that lie past the end of the message being read. These additional
  180. bytes are stored in the dynamic buffer, which must be preserved for
  181. subsequent reads.
  182. If the end of file error is received while reading from the stream, then
  183. the error returned from this function will be:
  184. @li @ref error::end_of_stream if no bytes were parsed, or
  185. @li @ref error::partial_message if any bytes were parsed but the
  186. message was incomplete, otherwise:
  187. @li A successful result. The next attempt to read will return
  188. @ref error::end_of_stream
  189. @param stream The stream from which the data is to be read. The type must
  190. meet the <em>SyncReadStream</em> requirements.
  191. @param buffer Storage for additional bytes read by the implementation from
  192. the stream. This is both an input and an output parameter; on entry, the
  193. parser will be presented with any remaining data in the dynamic buffer's
  194. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  195. requirements.
  196. @param parser The parser to use.
  197. @return The number of bytes consumed by the parser.
  198. @throws system_error Thrown on failure.
  199. @note The implementation will call @ref basic_parser::eager with the value
  200. `false` on the parser passed in.
  201. */
  202. template<
  203. class SyncReadStream,
  204. class DynamicBuffer,
  205. bool isRequest>
  206. std::size_t
  207. read_header(
  208. SyncReadStream& stream,
  209. DynamicBuffer& buffer,
  210. basic_parser<isRequest>& parser);
  211. /** Read a complete message header from a stream using a parser.
  212. This function is used to read a complete message header from a stream
  213. into an instance of @ref basic_parser. The call will block until one of the
  214. following conditions is true:
  215. @li @ref basic_parser::is_header_done returns `true`
  216. @li An error occurs.
  217. This operation is implemented in terms of one or more calls to the stream's
  218. `read_some` function. The implementation may read additional bytes from
  219. the stream that lie past the end of the message being read. These additional
  220. bytes are stored in the dynamic buffer, which must be preserved for
  221. subsequent reads.
  222. If the end of file error is received while reading from the stream, then
  223. the error returned from this function will be:
  224. @li @ref error::end_of_stream if no bytes were parsed, or
  225. @li @ref error::partial_message if any bytes were parsed but the
  226. message was incomplete, otherwise:
  227. @li A successful result. The next attempt to read will return
  228. @ref error::end_of_stream
  229. @param stream The stream from which the data is to be read. The type must
  230. meet the <em>SyncReadStream</em> requirements.
  231. @param buffer Storage for additional bytes read by the implementation from
  232. the stream. This is both an input and an output parameter; on entry, the
  233. parser will be presented with any remaining data in the dynamic buffer's
  234. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  235. requirements.
  236. @param parser The parser to use.
  237. @param ec Set to the error, if any occurred.
  238. @return The number of bytes consumed by the parser.
  239. @note The implementation will call @ref basic_parser::eager with the value
  240. `false` on the parser passed in.
  241. */
  242. template<
  243. class SyncReadStream,
  244. class DynamicBuffer,
  245. bool isRequest>
  246. std::size_t
  247. read_header(
  248. SyncReadStream& stream,
  249. DynamicBuffer& buffer,
  250. basic_parser<isRequest>& parser,
  251. error_code& ec);
  252. /** Read a complete message header asynchronously from a stream using a parser.
  253. This function is used to asynchronously read a complete message header from
  254. a stream into an instance of @ref basic_parser. The function call always
  255. returns immediately. The asynchronous operation will continue until one of
  256. the following conditions is true:
  257. @li @ref basic_parser::is_header_done returns `true`
  258. @li An error occurs.
  259. This operation is implemented in terms of zero or more calls to the
  260. next layer's `async_read_some` function, and is known as a <em>composed
  261. operation</em>. The program must ensure that the stream performs no other
  262. reads until this operation completes. The implementation may read additional
  263. bytes from the stream that lie past the end of the message being read.
  264. These additional bytes are stored in the dynamic buffer, which must be
  265. preserved for subsequent reads.
  266. If the end of file error is received while reading from the stream, then
  267. the error returned from this function will be:
  268. @li @ref error::end_of_stream if no bytes were parsed, or
  269. @li @ref error::partial_message if any bytes were parsed but the
  270. message was incomplete, otherwise:
  271. @li A successful result. The next attempt to read will return
  272. @ref error::end_of_stream
  273. @param stream The stream from which the data is to be read. The type
  274. must meet the <em>AsyncReadStream</em> requirements.
  275. @param buffer Storage for additional bytes read by the implementation from
  276. the stream. This is both an input and an output parameter; on entry, the
  277. parser will be presented with any remaining data in the dynamic buffer's
  278. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  279. requirements. The object must remain valid at least until the handler
  280. is called; ownership is not transferred.
  281. @param parser The parser to use. The object must remain valid at least until
  282. the handler is called; ownership is not transferred.
  283. @param handler The completion handler to invoke when the operation
  284. completes. The implementation takes ownership of the handler by
  285. performing a decay-copy. The equivalent function signature of
  286. the handler must be:
  287. @code
  288. void handler(
  289. error_code const& error, // result of operation
  290. std::size_t bytes_transferred // the number of bytes consumed by the parser
  291. );
  292. @endcode
  293. If the handler has an associated immediate executor,
  294. an immediate completion will be dispatched to it.
  295. Otherwise, the handler will not be invoked from within
  296. this function. Invocation of the handler will be performed in a
  297. manner equivalent to using `net::post`.
  298. @note The implementation will call @ref basic_parser::eager with the value
  299. `false` on the parser passed in.
  300. @par Per-Operation Cancellation
  301. This asynchronous operation supports cancellation for the following
  302. net::cancellation_type values:
  303. @li @c net::cancellation_type::terminal
  304. if the `stream` also supports terminal cancellation, `terminal`
  305. cancellation leaves the stream in an undefined state, so that only
  306. closing it is guaranteed to succeed.
  307. */
  308. template<
  309. class AsyncReadStream,
  310. class DynamicBuffer,
  311. bool isRequest,
  312. BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
  313. net::default_completion_token_t<
  314. executor_type<AsyncReadStream>>>
  315. BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
  316. async_read_header(
  317. AsyncReadStream& stream,
  318. DynamicBuffer& buffer,
  319. basic_parser<isRequest>& parser,
  320. ReadHandler&& handler =
  321. net::default_completion_token_t<
  322. executor_type<AsyncReadStream>>{});
  323. //------------------------------------------------------------------------------
  324. /** Read a complete message from a stream using a parser.
  325. This function is used to read a complete message from a stream into an
  326. instance of @ref basic_parser. The call will block until one of the
  327. following conditions is true:
  328. @li @ref basic_parser::is_done returns `true`
  329. @li An error occurs.
  330. This operation is implemented in terms of one or more calls to the stream's
  331. `read_some` function. The implementation may read additional bytes from
  332. the stream that lie past the end of the message being read. These additional
  333. bytes are stored in the dynamic buffer, which must be preserved for
  334. subsequent reads.
  335. If the end of file error is received while reading from the stream, then
  336. the error returned from this function will be:
  337. @li @ref error::end_of_stream if no bytes were parsed, or
  338. @li @ref error::partial_message if any bytes were parsed but the
  339. message was incomplete, otherwise:
  340. @li A successful result. The next attempt to read will return
  341. @ref error::end_of_stream
  342. @param stream The stream from which the data is to be read. The type must
  343. meet the <em>SyncReadStream</em> requirements.
  344. @param buffer Storage for additional bytes read by the implementation from
  345. the stream. This is both an input and an output parameter; on entry, the
  346. parser will be presented with any remaining data in the dynamic buffer's
  347. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  348. requirements.
  349. @param parser The parser to use.
  350. @return The number of bytes consumed by the parser.
  351. @throws system_error Thrown on failure.
  352. @note The implementation will call @ref basic_parser::eager with the value
  353. `true` on the parser passed in.
  354. */
  355. template<
  356. class SyncReadStream,
  357. class DynamicBuffer,
  358. bool isRequest>
  359. std::size_t
  360. read(
  361. SyncReadStream& stream,
  362. DynamicBuffer& buffer,
  363. basic_parser<isRequest>& parser);
  364. /** Read a complete message from a stream using a parser.
  365. This function is used to read a complete message from a stream into an
  366. instance of @ref basic_parser. The call will block until one of the
  367. following conditions is true:
  368. @li @ref basic_parser::is_done returns `true`
  369. @li An error occurs.
  370. This operation is implemented in terms of one or more calls to the stream's
  371. `read_some` function. The implementation may read additional bytes from
  372. the stream that lie past the end of the message being read. These additional
  373. bytes are stored in the dynamic buffer, which must be preserved for
  374. subsequent reads.
  375. If the end of file error is received while reading from the stream, then
  376. the error returned from this function will be:
  377. @li @ref error::end_of_stream if no bytes were parsed, or
  378. @li @ref error::partial_message if any bytes were parsed but the
  379. message was incomplete, otherwise:
  380. @li A successful result. The next attempt to read will return
  381. @ref error::end_of_stream
  382. @param stream The stream from which the data is to be read. The type must
  383. meet the <em>SyncReadStream</em> requirements.
  384. @param buffer Storage for additional bytes read by the implementation from
  385. the stream. This is both an input and an output parameter; on entry, the
  386. parser will be presented with any remaining data in the dynamic buffer's
  387. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  388. requirements.
  389. @param parser The parser to use.
  390. @param ec Set to the error, if any occurred.
  391. @return The number of bytes consumed by the parser.
  392. @note The implementation will call @ref basic_parser::eager with the value
  393. `true` on the parser passed in.
  394. */
  395. template<
  396. class SyncReadStream,
  397. class DynamicBuffer,
  398. bool isRequest>
  399. std::size_t
  400. read(
  401. SyncReadStream& stream,
  402. DynamicBuffer& buffer,
  403. basic_parser<isRequest>& parser,
  404. error_code& ec);
  405. /** Read a complete message asynchronously from a stream using a parser.
  406. This function is used to asynchronously read a complete message from a
  407. stream into an instance of @ref basic_parser. The function call always
  408. returns immediately. The asynchronous operation will continue until one
  409. of the following conditions is true:
  410. @li @ref basic_parser::is_done returns `true`
  411. @li An error occurs.
  412. This operation is implemented in terms of zero or more calls to the
  413. next layer's `async_read_some` function, and is known as a <em>composed
  414. operation</em>. The program must ensure that the stream performs no other
  415. reads until this operation completes. The implementation may read additional
  416. bytes from the stream that lie past the end of the message being read.
  417. These additional bytes are stored in the dynamic buffer, which must be
  418. preserved for subsequent reads.
  419. If the end of file error is received while reading from the stream, then
  420. the error returned from this function will be:
  421. @li @ref error::end_of_stream if no bytes were parsed, or
  422. @li @ref error::partial_message if any bytes were parsed but the
  423. message was incomplete, otherwise:
  424. @li A successful result. The next attempt to read will return
  425. @ref error::end_of_stream
  426. @param stream The stream from which the data is to be read. The type
  427. must meet the <em>AsyncReadStream</em> requirements.
  428. @param buffer Storage for additional bytes read by the implementation from
  429. the stream. This is both an input and an output parameter; on entry, the
  430. parser will be presented with any remaining data in the dynamic buffer's
  431. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  432. requirements. The object must remain valid at least until the handler
  433. is called; ownership is not transferred.
  434. @param parser The parser to use. The object must remain valid at least until
  435. the handler is called; ownership is not transferred.
  436. @param handler The completion handler to invoke when the operation
  437. completes. The implementation takes ownership of the handler by
  438. performing a decay-copy. The equivalent function signature of
  439. the handler must be:
  440. @code
  441. void handler(
  442. error_code const& error, // result of operation
  443. std::size_t bytes_transferred // the number of bytes consumed by the parser
  444. );
  445. @endcode
  446. If the handler has an associated immediate executor,
  447. an immediate completion will be dispatched to it.
  448. Otherwise, the handler will not be invoked from within
  449. this function. Invocation of the handler will be performed in a
  450. manner equivalent to using `net::post`.
  451. @note The implementation will call @ref basic_parser::eager with the value
  452. `true` on the parser passed in.
  453. @par Per-Operation Cancellation
  454. This asynchronous operation supports cancellation for the following
  455. net::cancellation_type values:
  456. @li @c net::cancellation_type::terminal
  457. if the `stream` also supports terminal cancellation, `terminal`
  458. cancellation leaves the stream in an undefined state, so that only
  459. closing it is guaranteed to succeed.
  460. */
  461. template<
  462. class AsyncReadStream,
  463. class DynamicBuffer,
  464. bool isRequest,
  465. BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
  466. net::default_completion_token_t<
  467. executor_type<AsyncReadStream>>>
  468. BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
  469. async_read(
  470. AsyncReadStream& stream,
  471. DynamicBuffer& buffer,
  472. basic_parser<isRequest>& parser,
  473. ReadHandler&& handler =
  474. net::default_completion_token_t<
  475. executor_type<AsyncReadStream>>{});
  476. //------------------------------------------------------------------------------
  477. /** Read a complete message from a stream.
  478. This function is used to read a complete message from a stream into an
  479. instance of @ref message. The call will block until one of the following
  480. conditions is true:
  481. @li The entire message is read in.
  482. @li An error occurs.
  483. This operation is implemented in terms of one or more calls to the stream's
  484. `read_some` function. The implementation may read additional bytes from
  485. the stream that lie past the end of the message being read. These additional
  486. bytes are stored in the dynamic buffer, which must be preserved for
  487. subsequent reads.
  488. If the end of file error is received while reading from the stream, then
  489. the error returned from this function will be:
  490. @li @ref error::end_of_stream if no bytes were parsed, or
  491. @li @ref error::partial_message if any bytes were parsed but the
  492. message was incomplete, otherwise:
  493. @li A successful result. The next attempt to read will return
  494. @ref error::end_of_stream
  495. @param stream The stream from which the data is to be read. The type must
  496. meet the <em>SyncReadStream</em> requirements.
  497. @param buffer Storage for additional bytes read by the implementation from
  498. the stream. This is both an input and an output parameter; on entry, the
  499. parser will be presented with any remaining data in the dynamic buffer's
  500. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  501. requirements.
  502. @param msg The container in which to store the message contents. This
  503. message container should not have previous contents, otherwise the behavior
  504. is undefined. The type must be meet the <em>MoveAssignable</em> and
  505. <em>MoveConstructible</em> requirements.
  506. @return The number of bytes consumed by the parser.
  507. @throws system_error Thrown on failure.
  508. @note The implementation will call @ref basic_parser::eager with the value
  509. `true` on the parser passed in.
  510. */
  511. template<
  512. class SyncReadStream,
  513. class DynamicBuffer,
  514. bool isRequest, class Body, class Allocator>
  515. std::size_t
  516. read(
  517. SyncReadStream& stream,
  518. DynamicBuffer& buffer,
  519. message<isRequest, Body, basic_fields<Allocator>>& msg);
  520. /** Read a complete message from a stream.
  521. This function is used to read a complete message from a stream into an
  522. instance of @ref message. The call will block until one of the following
  523. conditions is true:
  524. @li The entire message is read in.
  525. @li An error occurs.
  526. This operation is implemented in terms of one or more calls to the stream's
  527. `read_some` function. The implementation may read additional bytes from
  528. the stream that lie past the end of the message being read. These additional
  529. bytes are stored in the dynamic buffer, which must be preserved for
  530. subsequent reads.
  531. If the end of file error is received while reading from the stream, then
  532. the error returned from this function will be:
  533. @li @ref error::end_of_stream if no bytes were parsed, or
  534. @li @ref error::partial_message if any bytes were parsed but the
  535. message was incomplete, otherwise:
  536. @li A successful result. The next attempt to read will return
  537. @ref error::end_of_stream
  538. @param stream The stream from which the data is to be read. The type must
  539. meet the <em>SyncReadStream</em> requirements.
  540. @param buffer Storage for additional bytes read by the implementation from
  541. the stream. This is both an input and an output parameter; on entry, the
  542. parser will be presented with any remaining data in the dynamic buffer's
  543. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  544. requirements.
  545. @param msg The container in which to store the message contents. This
  546. message container should not have previous contents, otherwise the behavior
  547. is undefined. The type must be meet the <em>MoveAssignable</em> and
  548. <em>MoveConstructible</em> requirements.
  549. @param ec Set to the error, if any occurred.
  550. @return The number of bytes consumed by the parser.
  551. @note The implementation will call @ref basic_parser::eager with the value
  552. `true` on the parser passed in.
  553. */
  554. template<
  555. class SyncReadStream,
  556. class DynamicBuffer,
  557. bool isRequest, class Body, class Allocator>
  558. std::size_t
  559. read(
  560. SyncReadStream& stream,
  561. DynamicBuffer& buffer,
  562. message<isRequest, Body, basic_fields<Allocator>>& msg,
  563. error_code& ec);
  564. /** Read a complete message asynchronously from a stream.
  565. This function is used to asynchronously read a complete message from a
  566. stream into an instance of @ref message. The function call always returns
  567. immediately. The asynchronous operation will continue until one of the
  568. following conditions is true:
  569. @li The entire message is read in.
  570. @li An error occurs.
  571. This operation is implemented in terms of zero or more calls to the
  572. next layer's `async_read_some` function, and is known as a <em>composed
  573. operation</em>. The program must ensure that the stream performs no other
  574. reads until this operation completes. The implementation may read additional
  575. bytes from the stream that lie past the end of the message being read.
  576. These additional bytes are stored in the dynamic buffer, which must be
  577. preserved for subsequent reads.
  578. If the end of file error is received while reading from the stream, then
  579. the error returned from this function will be:
  580. @li @ref error::end_of_stream if no bytes were parsed, or
  581. @li @ref error::partial_message if any bytes were parsed but the
  582. message was incomplete, otherwise:
  583. @li A successful result. The next attempt to read will return
  584. @ref error::end_of_stream
  585. @param stream The stream from which the data is to be read. The type
  586. must meet the <em>AsyncReadStream</em> requirements.
  587. @param buffer Storage for additional bytes read by the implementation from
  588. the stream. This is both an input and an output parameter; on entry, the
  589. parser will be presented with any remaining data in the dynamic buffer's
  590. readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  591. requirements. The object must remain valid at least until the handler
  592. is called; ownership is not transferred.
  593. @param msg The container in which to store the message contents. This
  594. message container should not have previous contents, otherwise the behavior
  595. is undefined. The type must be meet the <em>MoveAssignable</em> and
  596. <em>MoveConstructible</em> requirements. The object must remain valid
  597. at least until the handler is called; ownership is not transferred.
  598. @param handler The completion handler to invoke when the operation
  599. completes. The implementation takes ownership of the handler by
  600. performing a decay-copy. The equivalent function signature of
  601. the handler must be:
  602. @code
  603. void handler(
  604. error_code const& error, // result of operation
  605. std::size_t bytes_transferred // the number of bytes consumed by the parser
  606. );
  607. @endcode
  608. If the handler has an associated immediate executor,
  609. an immediate completion will be dispatched to it.
  610. Otherwise, the handler will not be invoked from within
  611. this function. Invocation of the handler will be performed in a
  612. manner equivalent to using `net::post`.
  613. @note The implementation will call @ref basic_parser::eager with the value
  614. `true` on the parser passed in.
  615. @par Per-Operation Cancellation
  616. This asynchronous operation supports cancellation for the following
  617. net::cancellation_type values:
  618. @li @c net::cancellation_type::terminal
  619. if the `stream` also supports terminal cancellation, `terminal`
  620. cancellation leaves the stream in an undefined state, so that only
  621. closing it is guaranteed to succeed.
  622. */
  623. template<
  624. class AsyncReadStream,
  625. class DynamicBuffer,
  626. bool isRequest, class Body, class Allocator,
  627. BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
  628. net::default_completion_token_t<
  629. executor_type<AsyncReadStream>>>
  630. BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
  631. async_read(
  632. AsyncReadStream& stream,
  633. DynamicBuffer& buffer,
  634. message<isRequest, Body, basic_fields<Allocator>>& msg,
  635. ReadHandler&& handler =
  636. net::default_completion_token_t<
  637. executor_type<AsyncReadStream>>{});
  638. } // http
  639. } // beast
  640. } // boost
  641. #include <boost/beast/http/impl/read.hpp>
  642. #endif