Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2025-04-04 08:17:50

0001 //
0002 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // Official repository: https://github.com/boostorg/beast
0008 //
0009 
0010 #ifndef BOOST_BEAST_HTTP_READ_HPP
0011 #define BOOST_BEAST_HTTP_READ_HPP
0012 
0013 #include <boost/beast/core/detail/config.hpp>
0014 #include <boost/beast/core/error.hpp>
0015 #include <boost/beast/core/stream_traits.hpp>
0016 #include <boost/beast/http/basic_parser.hpp>
0017 #include <boost/beast/http/message.hpp>
0018 #include <boost/asio/async_result.hpp>
0019 
0020 namespace boost {
0021 namespace beast {
0022 namespace http {
0023 
0024 //------------------------------------------------------------------------------
0025 
0026 /** Read part of a message from a stream using a parser.
0027 
0028     This function is used to read part of a message from a stream into an
0029     instance of @ref basic_parser. The call will block until one of the
0030     following conditions is true:
0031 
0032     @li A call to @ref basic_parser::put with a non-empty buffer sequence
0033         is successful.
0034 
0035     @li An error occurs.
0036 
0037     This operation is implemented in terms of one or more calls to the stream's
0038     `read_some` function. The implementation may read additional bytes from
0039     the stream that lie past the end of the message being read. These additional
0040     bytes are stored in the dynamic buffer, which must be preserved for
0041     subsequent reads.
0042 
0043     If the end of file error is received while reading from the stream, then
0044     the error returned from this function will be:
0045 
0046     @li @ref error::end_of_stream if no bytes were parsed, or
0047 
0048     @li @ref error::partial_message if any bytes were parsed but the
0049         message was incomplete, otherwise:
0050 
0051     @li A successful result. The next attempt to read will return
0052         @ref error::end_of_stream
0053 
0054     @param stream The stream from which the data is to be read. The type must
0055     meet the <em>SyncReadStream</em> requirements.
0056 
0057     @param buffer Storage for additional bytes read by the implementation from
0058     the stream. This is both an input and an output parameter; on entry, the
0059     parser will be presented with any remaining data in the dynamic buffer's
0060     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0061     requirements.
0062 
0063     @param parser The parser to use.
0064 
0065     @return The number of bytes consumed by the parser.
0066 
0067     @throws system_error Thrown on failure.
0068 */
0069 template<
0070     class SyncReadStream,
0071     class DynamicBuffer,
0072     bool isRequest>
0073 std::size_t
0074 read_some(
0075     SyncReadStream& stream,
0076     DynamicBuffer& buffer,
0077     basic_parser<isRequest>& parser);
0078 
0079 /** Read part of a message from a stream using a parser.
0080 
0081     This function is used to read part of a message from a stream into an
0082     instance of @ref basic_parser. The call will block until one of the
0083     following conditions is true:
0084 
0085     @li A call to @ref basic_parser::put with a non-empty buffer sequence
0086         is successful.
0087 
0088     @li An error occurs.
0089 
0090     This operation is implemented in terms of one or more calls to the stream's
0091     `read_some` function. The implementation may read additional bytes from
0092     the stream that lie past the end of the message being read. These additional
0093     bytes are stored in the dynamic buffer, which must be preserved for
0094     subsequent reads.
0095 
0096     If the end of file error is received while reading from the stream, then
0097     the error returned from this function will be:
0098 
0099     @li @ref error::end_of_stream if no bytes were parsed, or
0100 
0101     @li @ref error::partial_message if any bytes were parsed but the
0102         message was incomplete, otherwise:
0103 
0104     @li A successful result. The next attempt to read will return
0105         @ref error::end_of_stream
0106 
0107     @param stream The stream from which the data is to be read. The type must
0108     support the <em>SyncReadStream</em> requirements.
0109 
0110     @param buffer Storage for additional bytes read by the implementation from
0111     the stream. This is both an input and an output parameter; on entry, the
0112     parser will be presented with any remaining data in the dynamic buffer's
0113     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0114     requirements.
0115 
0116     @param parser The parser to use.
0117 
0118     @param ec Set to the error, if any occurred.
0119 
0120     @return The number of bytes consumed by the parser.
0121 */
0122 template<
0123     class SyncReadStream,
0124     class DynamicBuffer,
0125     bool isRequest>
0126 std::size_t
0127 read_some(
0128     SyncReadStream& stream,
0129     DynamicBuffer& buffer,
0130     basic_parser<isRequest>& parser,
0131     error_code& ec);
0132 
0133 /** Read part of a message asynchronously from a stream using a parser.
0134 
0135     This function is used to asynchronously read part of a message from
0136     a stream into an instance of @ref basic_parser. The function call
0137     always returns immediately. The asynchronous operation will continue
0138     until one of the following conditions is true:
0139 
0140     @li A call to @ref basic_parser::put with a non-empty buffer sequence
0141         is successful.
0142 
0143     @li An error occurs.
0144 
0145     This operation is implemented in terms of zero or more calls to the
0146     next layer's `async_read_some` function, and is known as a <em>composed
0147     operation</em>. The program must ensure that the stream performs no other
0148     reads until this operation completes. The implementation may read additional
0149     bytes from the stream that lie past the end of the message being read.
0150     These additional bytes are stored in the dynamic buffer, which must be
0151     preserved for subsequent reads.
0152 
0153     If the end of file error is received while reading from the stream, then
0154     the error returned from this function will be:
0155 
0156     @li @ref error::end_of_stream if no bytes were parsed, or
0157 
0158     @li @ref error::partial_message if any bytes were parsed but the
0159         message was incomplete, otherwise:
0160 
0161     @li A successful result. The next attempt to read will return
0162         @ref error::end_of_stream
0163 
0164     @param stream The stream from which the data is to be read. The type
0165     must meet the <em>AsyncReadStream</em> requirements.
0166 
0167     @param buffer Storage for additional bytes read by the implementation from
0168     the stream. This is both an input and an output parameter; on entry, the
0169     parser will be presented with any remaining data in the dynamic buffer's
0170     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0171     requirements. The object must remain valid at least until the handler
0172     is called; ownership is not transferred.
0173 
0174     @param parser The parser to use. The object must remain valid at least until
0175     the handler is called; ownership is not transferred.
0176 
0177     @param handler The completion handler to invoke when the operation
0178     completes. The implementation takes ownership of the handler by
0179     performing a decay-copy. The equivalent function signature of
0180     the handler must be:
0181     @code
0182     void handler(
0183         error_code const& error,        // result of operation
0184         std::size_t bytes_transferred   // the number of bytes consumed by the parser
0185     );
0186     @endcode
0187     If the handler has an associated immediate executor,
0188     an immediate completion will be dispatched to it.
0189     Otherwise, the handler will not be invoked from within
0190     this function. Invocation of the handler will be performed in a
0191     manner equivalent to using `net::post`.
0192 
0193     @par Per-Operation Cancellation
0194 
0195     This asynchronous operation supports cancellation for the following
0196     net::cancellation_type values:
0197 
0198     @li @c net::cancellation_type::terminal
0199 
0200     if the `stream` also supports terminal cancellation, `terminal`
0201     cancellation leaves the stream in an undefined state, so that only
0202     closing it is guaranteed to succeed.
0203 
0204 */
0205 template<
0206     class AsyncReadStream,
0207     class DynamicBuffer,
0208     bool isRequest,
0209     BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
0210         net::default_completion_token_t<
0211             executor_type<AsyncReadStream>>>
0212 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
0213 async_read_some(
0214     AsyncReadStream& stream,
0215     DynamicBuffer& buffer,
0216     basic_parser<isRequest>& parser,
0217     ReadHandler&& handler =
0218         net::default_completion_token_t<
0219             executor_type<AsyncReadStream>>{});
0220 
0221 //------------------------------------------------------------------------------
0222 
0223 /** Read a complete message header from a stream using a parser.
0224 
0225     This function is used to read a complete message header from a stream
0226     into an instance of @ref basic_parser. The call will block until one of the
0227     following conditions is true:
0228 
0229     @li @ref basic_parser::is_header_done returns `true`
0230 
0231     @li An error occurs.
0232 
0233     This operation is implemented in terms of one or more calls to the stream's
0234     `read_some` function. The implementation may read additional bytes from
0235     the stream that lie past the end of the message being read. These additional
0236     bytes are stored in the dynamic buffer, which must be preserved for
0237     subsequent reads.
0238 
0239     If the end of file error is received while reading from the stream, then
0240     the error returned from this function will be:
0241 
0242     @li @ref error::end_of_stream if no bytes were parsed, or
0243 
0244     @li @ref error::partial_message if any bytes were parsed but the
0245         message was incomplete, otherwise:
0246 
0247     @li A successful result. The next attempt to read will return
0248         @ref error::end_of_stream
0249 
0250     @param stream The stream from which the data is to be read. The type must
0251     meet the <em>SyncReadStream</em> requirements.
0252 
0253     @param buffer Storage for additional bytes read by the implementation from
0254     the stream. This is both an input and an output parameter; on entry, the
0255     parser will be presented with any remaining data in the dynamic buffer's
0256     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0257     requirements.
0258 
0259     @param parser The parser to use.
0260 
0261     @return The number of bytes consumed by the parser.
0262 
0263     @throws system_error Thrown on failure.
0264 
0265     @note The implementation will call @ref basic_parser::eager with the value
0266     `false` on the parser passed in.
0267 */
0268 template<
0269     class SyncReadStream,
0270     class DynamicBuffer,
0271     bool isRequest>
0272 std::size_t
0273 read_header(
0274     SyncReadStream& stream,
0275     DynamicBuffer& buffer,
0276     basic_parser<isRequest>& parser);
0277 
0278 /** Read a complete message header from a stream using a parser.
0279 
0280     This function is used to read a complete message header from a stream
0281     into an instance of @ref basic_parser. The call will block until one of the
0282     following conditions is true:
0283 
0284     @li @ref basic_parser::is_header_done returns `true`
0285 
0286     @li An error occurs.
0287 
0288     This operation is implemented in terms of one or more calls to the stream's
0289     `read_some` function. The implementation may read additional bytes from
0290     the stream that lie past the end of the message being read. These additional
0291     bytes are stored in the dynamic buffer, which must be preserved for
0292     subsequent reads.
0293 
0294     If the end of file error is received while reading from the stream, then
0295     the error returned from this function will be:
0296 
0297     @li @ref error::end_of_stream if no bytes were parsed, or
0298 
0299     @li @ref error::partial_message if any bytes were parsed but the
0300         message was incomplete, otherwise:
0301 
0302     @li A successful result. The next attempt to read will return
0303         @ref error::end_of_stream
0304 
0305     @param stream The stream from which the data is to be read. The type must
0306     meet the <em>SyncReadStream</em> requirements.
0307 
0308     @param buffer Storage for additional bytes read by the implementation from
0309     the stream. This is both an input and an output parameter; on entry, the
0310     parser will be presented with any remaining data in the dynamic buffer's
0311     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0312     requirements.
0313 
0314     @param parser The parser to use.
0315 
0316     @param ec Set to the error, if any occurred.
0317 
0318     @return The number of bytes consumed by the parser.
0319 
0320     @note The implementation will call @ref basic_parser::eager with the value
0321     `false` on the parser passed in.
0322 */
0323 template<
0324     class SyncReadStream,
0325     class DynamicBuffer,
0326     bool isRequest>
0327 std::size_t
0328 read_header(
0329     SyncReadStream& stream,
0330     DynamicBuffer& buffer,
0331     basic_parser<isRequest>& parser,
0332     error_code& ec);
0333 
0334 /** Read a complete message header asynchronously from a stream using a parser.
0335 
0336     This function is used to asynchronously read a complete message header from
0337     a stream into an instance of @ref basic_parser. The function call always
0338     returns immediately. The asynchronous operation will continue until one of
0339     the following conditions is true:
0340 
0341     @li @ref basic_parser::is_header_done returns `true`
0342 
0343     @li An error occurs.
0344 
0345     This operation is implemented in terms of zero or more calls to the
0346     next layer's `async_read_some` function, and is known as a <em>composed
0347     operation</em>. The program must ensure that the stream performs no other
0348     reads until this operation completes. The implementation may read additional
0349     bytes from the stream that lie past the end of the message being read.
0350     These additional bytes are stored in the dynamic buffer, which must be
0351     preserved for subsequent reads.
0352 
0353     If the end of file error is received while reading from the stream, then
0354     the error returned from this function will be:
0355 
0356     @li @ref error::end_of_stream if no bytes were parsed, or
0357 
0358     @li @ref error::partial_message if any bytes were parsed but the
0359         message was incomplete, otherwise:
0360 
0361     @li A successful result. The next attempt to read will return
0362         @ref error::end_of_stream
0363 
0364     @param stream The stream from which the data is to be read. The type
0365     must meet the <em>AsyncReadStream</em> requirements.
0366 
0367     @param buffer Storage for additional bytes read by the implementation from
0368     the stream. This is both an input and an output parameter; on entry, the
0369     parser will be presented with any remaining data in the dynamic buffer's
0370     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0371     requirements. The object must remain valid at least until the handler
0372     is called; ownership is not transferred.
0373 
0374     @param parser The parser to use. The object must remain valid at least until
0375     the handler is called; ownership is not transferred.
0376 
0377     @param handler The completion handler to invoke when the operation
0378     completes. The implementation takes ownership of the handler by
0379     performing a decay-copy. The equivalent function signature of
0380     the handler must be:
0381     @code
0382     void handler(
0383         error_code const& error,        // result of operation
0384         std::size_t bytes_transferred   // the number of bytes consumed by the parser
0385     );
0386     @endcode
0387     If the handler has an associated immediate executor,
0388     an immediate completion will be dispatched to it.
0389     Otherwise, the handler will not be invoked from within
0390     this function. Invocation of the handler will be performed in a
0391     manner equivalent to using `net::post`.
0392 
0393     @note The implementation will call @ref basic_parser::eager with the value
0394     `false` on the parser passed in.
0395 
0396     @par Per-Operation Cancellation
0397 
0398     This asynchronous operation supports cancellation for the following
0399     net::cancellation_type values:
0400 
0401     @li @c net::cancellation_type::terminal
0402 
0403     if the `stream` also supports terminal cancellation, `terminal`
0404     cancellation leaves the stream in an undefined state, so that only
0405     closing it is guaranteed to succeed.
0406 
0407 */
0408 template<
0409     class AsyncReadStream,
0410     class DynamicBuffer,
0411     bool isRequest,
0412     BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
0413         net::default_completion_token_t<
0414             executor_type<AsyncReadStream>>>
0415 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
0416 async_read_header(
0417     AsyncReadStream& stream,
0418     DynamicBuffer& buffer,
0419     basic_parser<isRequest>& parser,
0420     ReadHandler&& handler =
0421         net::default_completion_token_t<
0422             executor_type<AsyncReadStream>>{});
0423 
0424 //------------------------------------------------------------------------------
0425 
0426 /** Read a complete message from a stream using a parser.
0427 
0428     This function is used to read a complete message from a stream into an
0429     instance of @ref basic_parser. The call will block until one of the
0430     following conditions is true:
0431 
0432     @li @ref basic_parser::is_done returns `true`
0433 
0434     @li An error occurs.
0435 
0436     This operation is implemented in terms of one or more calls to the stream's
0437     `read_some` function. The implementation may read additional bytes from
0438     the stream that lie past the end of the message being read. These additional
0439     bytes are stored in the dynamic buffer, which must be preserved for
0440     subsequent reads.
0441 
0442     If the end of file error is received while reading from the stream, then
0443     the error returned from this function will be:
0444 
0445     @li @ref error::end_of_stream if no bytes were parsed, or
0446 
0447     @li @ref error::partial_message if any bytes were parsed but the
0448         message was incomplete, otherwise:
0449 
0450     @li A successful result. The next attempt to read will return
0451         @ref error::end_of_stream
0452 
0453     @param stream The stream from which the data is to be read. The type must
0454     meet the <em>SyncReadStream</em> requirements.
0455 
0456     @param buffer Storage for additional bytes read by the implementation from
0457     the stream. This is both an input and an output parameter; on entry, the
0458     parser will be presented with any remaining data in the dynamic buffer's
0459     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0460     requirements.
0461 
0462     @param parser The parser to use.
0463 
0464     @return The number of bytes consumed by the parser.
0465 
0466     @throws system_error Thrown on failure.
0467 
0468     @note The implementation will call @ref basic_parser::eager with the value
0469     `true` on the parser passed in.
0470 */
0471 template<
0472     class SyncReadStream,
0473     class DynamicBuffer,
0474     bool isRequest>
0475 std::size_t
0476 read(
0477     SyncReadStream& stream,
0478     DynamicBuffer& buffer,
0479     basic_parser<isRequest>& parser);
0480 
0481 /** Read a complete message from a stream using a parser.
0482 
0483     This function is used to read a complete message from a stream into an
0484     instance of @ref basic_parser. The call will block until one of the
0485     following conditions is true:
0486 
0487     @li @ref basic_parser::is_done returns `true`
0488 
0489     @li An error occurs.
0490 
0491     This operation is implemented in terms of one or more calls to the stream's
0492     `read_some` function. The implementation may read additional bytes from
0493     the stream that lie past the end of the message being read. These additional
0494     bytes are stored in the dynamic buffer, which must be preserved for
0495     subsequent reads.
0496 
0497     If the end of file error is received while reading from the stream, then
0498     the error returned from this function will be:
0499 
0500     @li @ref error::end_of_stream if no bytes were parsed, or
0501 
0502     @li @ref error::partial_message if any bytes were parsed but the
0503         message was incomplete, otherwise:
0504 
0505     @li A successful result. The next attempt to read will return
0506         @ref error::end_of_stream
0507 
0508     @param stream The stream from which the data is to be read. The type must
0509     meet the <em>SyncReadStream</em> requirements.
0510 
0511     @param buffer Storage for additional bytes read by the implementation from
0512     the stream. This is both an input and an output parameter; on entry, the
0513     parser will be presented with any remaining data in the dynamic buffer's
0514     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0515     requirements.
0516 
0517     @param parser The parser to use.
0518 
0519     @param ec Set to the error, if any occurred.
0520 
0521     @return The number of bytes consumed by the parser.
0522 
0523     @note The implementation will call @ref basic_parser::eager with the value
0524     `true` on the parser passed in.
0525 */
0526 template<
0527     class SyncReadStream,
0528     class DynamicBuffer,
0529     bool isRequest>
0530 std::size_t
0531 read(
0532     SyncReadStream& stream,
0533     DynamicBuffer& buffer,
0534     basic_parser<isRequest>& parser,
0535     error_code& ec);
0536 
0537 /** Read a complete message asynchronously from a stream using a parser.
0538 
0539     This function is used to asynchronously read a complete message from a
0540     stream into an instance of @ref basic_parser. The function call always
0541     returns immediately. The asynchronous operation will continue until one
0542     of the following conditions is true:
0543 
0544     @li @ref basic_parser::is_done returns `true`
0545 
0546     @li An error occurs.
0547 
0548     This operation is implemented in terms of zero or more calls to the
0549     next layer's `async_read_some` function, and is known as a <em>composed
0550     operation</em>. The program must ensure that the stream performs no other
0551     reads until this operation completes. The implementation may read additional
0552     bytes from the stream that lie past the end of the message being read.
0553     These additional bytes are stored in the dynamic buffer, which must be
0554     preserved for subsequent reads.
0555 
0556     If the end of file error is received while reading from the stream, then
0557     the error returned from this function will be:
0558 
0559     @li @ref error::end_of_stream if no bytes were parsed, or
0560 
0561     @li @ref error::partial_message if any bytes were parsed but the
0562         message was incomplete, otherwise:
0563 
0564     @li A successful result. The next attempt to read will return
0565         @ref error::end_of_stream
0566 
0567     @param stream The stream from which the data is to be read. The type
0568     must meet the <em>AsyncReadStream</em> requirements.
0569 
0570     @param buffer Storage for additional bytes read by the implementation from
0571     the stream. This is both an input and an output parameter; on entry, the
0572     parser will be presented with any remaining data in the dynamic buffer's
0573     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0574     requirements. The object must remain valid at least until the handler
0575     is called; ownership is not transferred.
0576 
0577     @param parser The parser to use. The object must remain valid at least until
0578     the handler is called; ownership is not transferred.
0579 
0580     @param handler The completion handler to invoke when the operation
0581     completes. The implementation takes ownership of the handler by
0582     performing a decay-copy. The equivalent function signature of
0583     the handler must be:
0584     @code
0585     void handler(
0586         error_code const& error,        // result of operation
0587         std::size_t bytes_transferred   // the number of bytes consumed by the parser
0588     );
0589     @endcode
0590     If the handler has an associated immediate executor,
0591     an immediate completion will be dispatched to it.
0592     Otherwise, the handler will not be invoked from within
0593     this function. Invocation of the handler will be performed in a
0594     manner equivalent to using `net::post`.
0595 
0596     @note The implementation will call @ref basic_parser::eager with the value
0597     `true` on the parser passed in.
0598 
0599     @par Per-Operation Cancellation
0600 
0601     This asynchronous operation supports cancellation for the following
0602     net::cancellation_type values:
0603 
0604     @li @c net::cancellation_type::terminal
0605 
0606     if the `stream` also supports terminal cancellation, `terminal`
0607     cancellation leaves the stream in an undefined state, so that only
0608     closing it is guaranteed to succeed.
0609 
0610 */
0611 template<
0612     class AsyncReadStream,
0613     class DynamicBuffer,
0614     bool isRequest,
0615     BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
0616         net::default_completion_token_t<
0617             executor_type<AsyncReadStream>>>
0618 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
0619 async_read(
0620     AsyncReadStream& stream,
0621     DynamicBuffer& buffer,
0622     basic_parser<isRequest>& parser,
0623     ReadHandler&& handler =
0624         net::default_completion_token_t<
0625             executor_type<AsyncReadStream>>{});
0626 
0627 //------------------------------------------------------------------------------
0628 
0629 /** Read a complete message from a stream.
0630 
0631     This function is used to read a complete message from a stream into an
0632     instance of @ref message. The call will block until one of the following
0633     conditions is true:
0634 
0635     @li The entire message is read in.
0636 
0637     @li An error occurs.
0638 
0639     This operation is implemented in terms of one or more calls to the stream's
0640     `read_some` function. The implementation may read additional bytes from
0641     the stream that lie past the end of the message being read. These additional
0642     bytes are stored in the dynamic buffer, which must be preserved for
0643     subsequent reads.
0644 
0645     If the end of file error is received while reading from the stream, then
0646     the error returned from this function will be:
0647 
0648     @li @ref error::end_of_stream if no bytes were parsed, or
0649 
0650     @li @ref error::partial_message if any bytes were parsed but the
0651         message was incomplete, otherwise:
0652 
0653     @li A successful result. The next attempt to read will return
0654         @ref error::end_of_stream
0655 
0656     @param stream The stream from which the data is to be read. The type must
0657     meet the <em>SyncReadStream</em> requirements.
0658 
0659     @param buffer Storage for additional bytes read by the implementation from
0660     the stream. This is both an input and an output parameter; on entry, the
0661     parser will be presented with any remaining data in the dynamic buffer's
0662     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0663     requirements.
0664 
0665     @param msg The container in which to store the message contents. This
0666     message container should not have previous contents, otherwise the behavior
0667     is undefined. The type must be meet the <em>MoveAssignable</em> and
0668     <em>MoveConstructible</em> requirements.
0669 
0670     @return The number of bytes consumed by the parser.
0671 
0672     @throws system_error Thrown on failure.
0673 
0674     @note The implementation will call @ref basic_parser::eager with the value
0675     `true` on the parser passed in.
0676 */
0677 template<
0678     class SyncReadStream,
0679     class DynamicBuffer,
0680     bool isRequest, class Body, class Allocator>
0681 std::size_t
0682 read(
0683     SyncReadStream& stream,
0684     DynamicBuffer& buffer,
0685     message<isRequest, Body, basic_fields<Allocator>>& msg);
0686 
0687 /** Read a complete message from a stream.
0688 
0689     This function is used to read a complete message from a stream into an
0690     instance of @ref message. The call will block until one of the following
0691     conditions is true:
0692 
0693     @li The entire message is read in.
0694 
0695     @li An error occurs.
0696 
0697     This operation is implemented in terms of one or more calls to the stream's
0698     `read_some` function. The implementation may read additional bytes from
0699     the stream that lie past the end of the message being read. These additional
0700     bytes are stored in the dynamic buffer, which must be preserved for
0701     subsequent reads.
0702 
0703     If the end of file error is received while reading from the stream, then
0704     the error returned from this function will be:
0705 
0706     @li @ref error::end_of_stream if no bytes were parsed, or
0707 
0708     @li @ref error::partial_message if any bytes were parsed but the
0709         message was incomplete, otherwise:
0710 
0711     @li A successful result. The next attempt to read will return
0712         @ref error::end_of_stream
0713 
0714     @param stream The stream from which the data is to be read. The type must
0715     meet the <em>SyncReadStream</em> requirements.
0716 
0717     @param buffer Storage for additional bytes read by the implementation from
0718     the stream. This is both an input and an output parameter; on entry, the
0719     parser will be presented with any remaining data in the dynamic buffer's
0720     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0721     requirements.
0722 
0723     @param msg The container in which to store the message contents. This
0724     message container should not have previous contents, otherwise the behavior
0725     is undefined. The type must be meet the <em>MoveAssignable</em> and
0726     <em>MoveConstructible</em> requirements.
0727 
0728     @param ec Set to the error, if any occurred.
0729 
0730     @return The number of bytes consumed by the parser.
0731 
0732     @note The implementation will call @ref basic_parser::eager with the value
0733     `true` on the parser passed in.
0734 */
0735 template<
0736     class SyncReadStream,
0737     class DynamicBuffer,
0738     bool isRequest, class Body, class Allocator>
0739 std::size_t
0740 read(
0741     SyncReadStream& stream,
0742     DynamicBuffer& buffer,
0743     message<isRequest, Body, basic_fields<Allocator>>& msg,
0744     error_code& ec);
0745 
0746 /** Read a complete message asynchronously from a stream.
0747 
0748     This function is used to asynchronously read a complete message from a
0749     stream into an instance of @ref message. The function call always returns
0750     immediately. The asynchronous operation will continue until one of the
0751     following conditions is true:
0752 
0753     @li The entire message is read in.
0754 
0755     @li An error occurs.
0756 
0757     This operation is implemented in terms of zero or more calls to the
0758     next layer's `async_read_some` function, and is known as a <em>composed
0759     operation</em>. The program must ensure that the stream performs no other
0760     reads until this operation completes. The implementation may read additional
0761     bytes from the stream that lie past the end of the message being read.
0762     These additional bytes are stored in the dynamic buffer, which must be
0763     preserved for subsequent reads.
0764 
0765     If the end of file error is received while reading from the stream, then
0766     the error returned from this function will be:
0767 
0768     @li @ref error::end_of_stream if no bytes were parsed, or
0769 
0770     @li @ref error::partial_message if any bytes were parsed but the
0771         message was incomplete, otherwise:
0772 
0773     @li A successful result. The next attempt to read will return
0774         @ref error::end_of_stream
0775 
0776     @param stream The stream from which the data is to be read. The type
0777     must meet the <em>AsyncReadStream</em> requirements.
0778 
0779     @param buffer Storage for additional bytes read by the implementation from
0780     the stream. This is both an input and an output parameter; on entry, the
0781     parser will be presented with any remaining data in the dynamic buffer's
0782     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
0783     requirements. The object must remain valid at least until the handler
0784     is called; ownership is not transferred.
0785 
0786     @param msg The container in which to store the message contents. This
0787     message container should not have previous contents, otherwise the behavior
0788     is undefined. The type must be meet the <em>MoveAssignable</em> and
0789     <em>MoveConstructible</em> requirements. The object must remain valid
0790     at least until the handler is called; ownership is not transferred.
0791 
0792     @param handler The completion handler to invoke when the operation
0793     completes. The implementation takes ownership of the handler by
0794     performing a decay-copy. The equivalent function signature of
0795     the handler must be:
0796     @code
0797     void handler(
0798         error_code const& error,        // result of operation
0799         std::size_t bytes_transferred   // the number of bytes consumed by the parser
0800     );
0801     @endcode
0802     If the handler has an associated immediate executor,
0803     an immediate completion will be dispatched to it.
0804     Otherwise, the handler will not be invoked from within
0805     this function. Invocation of the handler will be performed in a
0806     manner equivalent to using `net::post`.
0807 
0808     @note The implementation will call @ref basic_parser::eager with the value
0809     `true` on the parser passed in.
0810 
0811     @par Per-Operation Cancellation
0812 
0813     This asynchronous operation supports cancellation for the following
0814     net::cancellation_type values:
0815 
0816     @li @c net::cancellation_type::terminal
0817 
0818     if the `stream` also supports terminal cancellation, `terminal`
0819     cancellation leaves the stream in an undefined state, so that only
0820     closing it is guaranteed to succeed.
0821 
0822 */
0823 template<
0824     class AsyncReadStream,
0825     class DynamicBuffer,
0826     bool isRequest, class Body, class Allocator,
0827     BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
0828         net::default_completion_token_t<
0829             executor_type<AsyncReadStream>>>
0830 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
0831 async_read(
0832     AsyncReadStream& stream,
0833     DynamicBuffer& buffer,
0834     message<isRequest, Body, basic_fields<Allocator>>& msg,
0835     ReadHandler&& handler =
0836         net::default_completion_token_t<
0837             executor_type<AsyncReadStream>>{});
0838 
0839 } // http
0840 } // beast
0841 } // boost
0842 
0843 #include <boost/beast/http/impl/read.hpp>
0844 
0845 #endif