boost/beast/http/read.hpp

   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
  10 #ifndef BOOST_BEAST_HTTP_READ_HPP
  11 #define BOOST_BEAST_HTTP_READ_HPP
  12
  13 #include <boost/beast/core/detail/config.hpp>
  14 #include <boost/beast/core/error.hpp>
  15 #include <boost/beast/core/stream_traits.hpp>
  16 #include <boost/beast/http/basic_parser.hpp>
  17 #include <boost/beast/http/message.hpp>
  18 #include <boost/asio/async_result.hpp>
  19
  20 namespace boost {
  21 namespace beast {
  22 namespace http {
  23
  24 //------------------------------------------------------------------------------
  25
  26 /** Read part of a message from a stream using a parser.
  27
  28     This function is used to read part of a message from a stream into an
  29     instance of @ref basic_parser. The call will block until one of the
  30     following conditions is true:
  31
  32     @li A call to @ref basic_parser::put with a non-empty buffer sequence
  33         is successful.
  34
  35     @li An error occurs.
  36
  37     This operation is implemented in terms of one or more calls to the stream's
  38     `read_some` function. The implementation may read additional bytes from
  39     the stream that lie past the end of the message being read. These additional
  40     bytes are stored in the dynamic buffer, which must be preserved for
  41     subsequent reads.
  42
  43     If the end of file error is received while reading from the stream, then
  44     the error returned from this function will be:
  45
  46     @li @ref error::end_of_stream if no bytes were parsed, or
  47
  48     @li @ref error::partial_message if any bytes were parsed but the
  49         message was incomplete, otherwise:
  50
  51     @li A successful result. The next attempt to read will return
  52         @ref error::end_of_stream
  53
  54     @param stream The stream from which the data is to be read. The type must
  55     meet the <em>SyncReadStream</em> requirements.
  56
  57     @param buffer Storage for additional bytes read by the implementation from
  58     the stream. This is both an input and an output parameter; on entry, the
  59     parser will be presented with any remaining data in the dynamic buffer's
  60     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
  61     requirements.
  62
  63     @param parser The parser to use.
  64
  65     @return The number of bytes transferred from the stream.
  66
  67     @throws system_error Thrown on failure.
  68
  69     @note The function returns the total number of bytes transferred from the
  70     stream. This may be zero for the case where there is sufficient pre-existing
  71     message data in the dynamic buffer.
  72 */
  73 template<
  74     class SyncReadStream,
  75     class DynamicBuffer,
  76     bool isRequest>
  77 std::size_t
  78 read_some(
  79     SyncReadStream& stream,
  80     DynamicBuffer& buffer,
  81     basic_parser<isRequest>& parser);
  82
  83 /** Read part of a message from a stream using a parser.
  84
  85     This function is used to read part of a message from a stream into an
  86     instance of @ref basic_parser. The call will block until one of the
  87     following conditions is true:
  88
  89     @li A call to @ref basic_parser::put with a non-empty buffer sequence
  90         is successful.
  91
  92     @li An error occurs.
  93
  94     This operation is implemented in terms of one or more calls to the stream's
  95     `read_some` function. The implementation may read additional bytes from
  96     the stream that lie past the end of the message being read. These additional
  97     bytes are stored in the dynamic buffer, which must be preserved for
  98     subsequent reads.
  99
 100     If the end of file error is received while reading from the stream, then
 101     the error returned from this function will be:
 102
 103     @li @ref error::end_of_stream if no bytes were parsed, or
 104
 105     @li @ref error::partial_message if any bytes were parsed but the
 106         message was incomplete, otherwise:
 107
 108     @li A successful result. The next attempt to read will return
 109         @ref error::end_of_stream
 110
 111     @param stream The stream from which the data is to be read. The type must
 112     support the <em>SyncReadStream</em> requirements.
 113
 114     @param buffer Storage for additional bytes read by the implementation from
 115     the stream. This is both an input and an output parameter; on entry, the
 116     parser will be presented with any remaining data in the dynamic buffer's
 117     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 118     requirements.
 119
 120     @param parser The parser to use.
 121
 122     @param ec Set to the error, if any occurred.
 123
 124     @return The number of bytes transferred from the stream.
 125
 126     @note The function returns the total number of bytes transferred from the
 127     stream. This may be zero for the case where there is sufficient pre-existing
 128     message data in the dynamic buffer.
 129 */
 130 template<
 131     class SyncReadStream,
 132     class DynamicBuffer,
 133     bool isRequest>
 134 std::size_t
 135 read_some(
 136     SyncReadStream& stream,
 137     DynamicBuffer& buffer,
 138     basic_parser<isRequest>& parser,
 139     error_code& ec);
 140
 141 /** Read part of a message asynchronously from a stream using a parser.
 142
 143     This function is used to asynchronously read part of a message from
 144     a stream into an instance of @ref basic_parser. The function call
 145     always returns immediately. The asynchronous operation will continue
 146     until one of the following conditions is true:
 147
 148     @li A call to @ref basic_parser::put with a non-empty buffer sequence
 149         is successful.
 150
 151     @li An error occurs.
 152
 153     This operation is implemented in terms of zero or more calls to the
 154     next layer's `async_read_some` function, and is known as a <em>composed
 155     operation</em>. The program must ensure that the stream performs no other
 156     reads until this operation completes. The implementation may read additional
 157     bytes from the stream that lie past the end of the message being read.
 158     These additional bytes are stored in the dynamic buffer, which must be
 159     preserved for subsequent reads.
 160
 161     If the end of file error is received while reading from the stream, then
 162     the error returned from this function will be:
 163
 164     @li @ref error::end_of_stream if no bytes were parsed, or
 165
 166     @li @ref error::partial_message if any bytes were parsed but the
 167         message was incomplete, otherwise:
 168
 169     @li A successful result. The next attempt to read will return
 170         @ref error::end_of_stream
 171
 172     @param stream The stream from which the data is to be read. The type
 173     must meet the <em>AsyncReadStream</em> requirements.
 174
 175     @param buffer Storage for additional bytes read by the implementation from
 176     the stream. This is both an input and an output parameter; on entry, the
 177     parser will be presented with any remaining data in the dynamic buffer's
 178     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 179     requirements. The object must remain valid at least until the handler
 180     is called; ownership is not transferred.
 181
 182     @param parser The parser to use. The object must remain valid at least until
 183     the handler is called; ownership is not transferred.
 184
 185     @param handler The completion handler to invoke when the operation
 186     completes. The implementation takes ownership of the handler by
 187     performing a decay-copy. The equivalent function signature of
 188     the handler must be:
 189     @code
 190     void handler(
 191         error_code const& error,        // result of operation
 192         std::size_t bytes_transferred   // the total number of bytes transferred from the stream
 193     );
 194     @endcode
 195     Regardless of whether the asynchronous operation completes
 196     immediately or not, the handler will not be invoked from within
 197     this function. Invocation of the handler will be performed in a
 198     manner equivalent to using `net::post`.
 199
 200     @note The completion handler will receive as a parameter the total number
 201     of bytes transferred from the stream. This may be zero for the case where
 202     there is sufficient pre-existing message data in the dynamic buffer.
 203 */
 204 template<
 205     class AsyncReadStream,
 206     class DynamicBuffer,
 207     bool isRequest,
 208     BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
 209         net::default_completion_token_t<
 210             executor_type<AsyncReadStream>>>
 211 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
 212 async_read_some(
 213     AsyncReadStream& stream,
 214     DynamicBuffer& buffer,
 215     basic_parser<isRequest>& parser,
 216     ReadHandler&& handler =
 217         net::default_completion_token_t<
 218             executor_type<AsyncReadStream>>{});
 219
 220 //------------------------------------------------------------------------------
 221
 222 /** Read a complete message header from a stream using a parser.
 223
 224     This function is used to read a complete message header from a stream
 225     into an instance of @ref basic_parser. The call will block until one of the
 226     following conditions is true:
 227
 228     @li @ref basic_parser::is_header_done returns `true`
 229
 230     @li An error occurs.
 231
 232     This operation is implemented in terms of one or more calls to the stream's
 233     `read_some` function. The implementation may read additional bytes from
 234     the stream that lie past the end of the message being read. These additional
 235     bytes are stored in the dynamic buffer, which must be preserved for
 236     subsequent reads.
 237
 238     If the end of file error is received while reading from the stream, then
 239     the error returned from this function will be:
 240
 241     @li @ref error::end_of_stream if no bytes were parsed, or
 242
 243     @li @ref error::partial_message if any bytes were parsed but the
 244         message was incomplete, otherwise:
 245
 246     @li A successful result. The next attempt to read will return
 247         @ref error::end_of_stream
 248
 249     @param stream The stream from which the data is to be read. The type must
 250     meet the <em>SyncReadStream</em> requirements.
 251
 252     @param buffer Storage for additional bytes read by the implementation from
 253     the stream. This is both an input and an output parameter; on entry, the
 254     parser will be presented with any remaining data in the dynamic buffer's
 255     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 256     requirements.
 257
 258     @param parser The parser to use.
 259
 260     @return The number of bytes transferred from the stream.
 261
 262     @throws system_error Thrown on failure.
 263
 264     @note The function returns the total number of bytes transferred from the
 265     stream. This may be zero for the case where there is sufficient pre-existing
 266     message data in the dynamic buffer. The implementation will call
 267     @ref basic_parser::eager with the value `false` on the parser passed in.
 268 */
 269 template<
 270     class SyncReadStream,
 271     class DynamicBuffer,
 272     bool isRequest>
 273 std::size_t
 274 read_header(
 275     SyncReadStream& stream,
 276     DynamicBuffer& buffer,
 277     basic_parser<isRequest>& parser);
 278
 279 /** Read a complete message header from a stream using a parser.
 280
 281     This function is used to read a complete message header from a stream
 282     into an instance of @ref basic_parser. The call will block until one of the
 283     following conditions is true:
 284
 285     @li @ref basic_parser::is_header_done returns `true`
 286
 287     @li An error occurs.
 288
 289     This operation is implemented in terms of one or more calls to the stream's
 290     `read_some` function. The implementation may read additional bytes from
 291     the stream that lie past the end of the message being read. These additional
 292     bytes are stored in the dynamic buffer, which must be preserved for
 293     subsequent reads.
 294
 295     If the end of file error is received while reading from the stream, then
 296     the error returned from this function will be:
 297
 298     @li @ref error::end_of_stream if no bytes were parsed, or
 299
 300     @li @ref error::partial_message if any bytes were parsed but the
 301         message was incomplete, otherwise:
 302
 303     @li A successful result. The next attempt to read will return
 304         @ref error::end_of_stream
 305
 306     @param stream The stream from which the data is to be read. The type must
 307     meet the <em>SyncReadStream</em> requirements.
 308
 309     @param buffer Storage for additional bytes read by the implementation from
 310     the stream. This is both an input and an output parameter; on entry, the
 311     parser will be presented with any remaining data in the dynamic buffer's
 312     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 313     requirements.
 314
 315     @param parser The parser to use.
 316
 317     @param ec Set to the error, if any occurred.
 318
 319     @return The number of bytes transferred from the stream.
 320
 321     @note The function returns the total number of bytes transferred from the
 322     stream. This may be zero for the case where there is sufficient pre-existing
 323     message data in the dynamic buffer. The implementation will call
 324     @ref basic_parser::eager with the value `false` on the parser passed in.
 325 */
 326 template<
 327     class SyncReadStream,
 328     class DynamicBuffer,
 329     bool isRequest>
 330 std::size_t
 331 read_header(
 332     SyncReadStream& stream,
 333     DynamicBuffer& buffer,
 334     basic_parser<isRequest>& parser,
 335     error_code& ec);
 336
 337 /** Read a complete message header asynchronously from a stream using a parser.
 338
 339     This function is used to asynchronously read a complete message header from
 340     a stream into an instance of @ref basic_parser. The function call always
 341     returns immediately. The asynchronous operation will continue until one of
 342     the following conditions is true:
 343
 344     @li @ref basic_parser::is_header_done returns `true`
 345
 346     @li An error occurs.
 347
 348     This operation is implemented in terms of zero or more calls to the
 349     next layer's `async_read_some` function, and is known as a <em>composed
 350     operation</em>. The program must ensure that the stream performs no other
 351     reads until this operation completes. The implementation may read additional
 352     bytes from the stream that lie past the end of the message being read.
 353     These additional bytes are stored in the dynamic buffer, which must be
 354     preserved for subsequent reads.
 355
 356     If the end of file error is received while reading from the stream, then
 357     the error returned from this function will be:
 358
 359     @li @ref error::end_of_stream if no bytes were parsed, or
 360
 361     @li @ref error::partial_message if any bytes were parsed but the
 362         message was incomplete, otherwise:
 363
 364     @li A successful result. The next attempt to read will return
 365         @ref error::end_of_stream
 366
 367     @param stream The stream from which the data is to be read. The type
 368     must meet the <em>AsyncReadStream</em> requirements.
 369
 370     @param buffer Storage for additional bytes read by the implementation from
 371     the stream. This is both an input and an output parameter; on entry, the
 372     parser will be presented with any remaining data in the dynamic buffer's
 373     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 374     requirements. The object must remain valid at least until the handler
 375     is called; ownership is not transferred.
 376
 377     @param parser The parser to use. The object must remain valid at least until
 378     the handler is called; ownership is not transferred.
 379
 380     @param handler The completion handler to invoke when the operation
 381     completes. The implementation takes ownership of the handler by
 382     performing a decay-copy. The equivalent function signature of
 383     the handler must be:
 384     @code
 385     void handler(
 386         error_code const& error,        // result of operation
 387         std::size_t bytes_transferred   // the total number of bytes transferred from the stream
 388     );
 389     @endcode
 390     Regardless of whether the asynchronous operation completes
 391     immediately or not, the handler will not be invoked from within
 392     this function. Invocation of the handler will be performed in a
 393     manner equivalent to using `net::post`.
 394
 395     @note The completion handler will receive as a parameter the total number
 396     of bytes transferred from the stream. This may be zero for the case where
 397     there is sufficient pre-existing message data in the dynamic buffer. The
 398     implementation will call @ref basic_parser::eager with the value `false`
 399     on the parser passed in.
 400 */
 401 template<
 402     class AsyncReadStream,
 403     class DynamicBuffer,
 404     bool isRequest,
 405     BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
 406         net::default_completion_token_t<
 407             executor_type<AsyncReadStream>>>
 408 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
 409 async_read_header(
 410     AsyncReadStream& stream,
 411     DynamicBuffer& buffer,
 412     basic_parser<isRequest>& parser,
 413     ReadHandler&& handler =
 414         net::default_completion_token_t<
 415             executor_type<AsyncReadStream>>{});
 416
 417 //------------------------------------------------------------------------------
 418
 419 /** Read a complete message from a stream using a parser.
 420
 421     This function is used to read a complete message from a stream into an
 422     instance of @ref basic_parser. The call will block until one of the
 423     following conditions is true:
 424
 425     @li @ref basic_parser::is_done returns `true`
 426
 427     @li An error occurs.
 428
 429     This operation is implemented in terms of one or more calls to the stream's
 430     `read_some` function. The implementation may read additional bytes from
 431     the stream that lie past the end of the message being read. These additional
 432     bytes are stored in the dynamic buffer, which must be preserved for
 433     subsequent reads.
 434
 435     If the end of file error is received while reading from the stream, then
 436     the error returned from this function will be:
 437
 438     @li @ref error::end_of_stream if no bytes were parsed, or
 439
 440     @li @ref error::partial_message if any bytes were parsed but the
 441         message was incomplete, otherwise:
 442
 443     @li A successful result. The next attempt to read will return
 444         @ref error::end_of_stream
 445
 446     @param stream The stream from which the data is to be read. The type must
 447     meet the <em>SyncReadStream</em> requirements.
 448
 449     @param buffer Storage for additional bytes read by the implementation from
 450     the stream. This is both an input and an output parameter; on entry, the
 451     parser will be presented with any remaining data in the dynamic buffer's
 452     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 453     requirements.
 454
 455     @param parser The parser to use.
 456
 457     @return The number of bytes transferred from the stream.
 458
 459     @throws system_error Thrown on failure.
 460
 461     @note The function returns the total number of bytes transferred from the
 462     stream. This may be zero for the case where there is sufficient pre-existing
 463     message data in the dynamic buffer. The implementation will call
 464     @ref basic_parser::eager with the value `true` on the parser passed in.
 465 */
 466 template<
 467     class SyncReadStream,
 468     class DynamicBuffer,
 469     bool isRequest>
 470 std::size_t
 471 read(
 472     SyncReadStream& stream,
 473     DynamicBuffer& buffer,
 474     basic_parser<isRequest>& parser);
 475
 476 /** Read a complete message from a stream using a parser.
 477
 478     This function is used to read a complete message from a stream into an
 479     instance of @ref basic_parser. The call will block until one of the
 480     following conditions is true:
 481
 482     @li @ref basic_parser::is_done returns `true`
 483
 484     @li An error occurs.
 485
 486     This operation is implemented in terms of one or more calls to the stream's
 487     `read_some` function. The implementation may read additional bytes from
 488     the stream that lie past the end of the message being read. These additional
 489     bytes are stored in the dynamic buffer, which must be preserved for
 490     subsequent reads.
 491
 492     If the end of file error is received while reading from the stream, then
 493     the error returned from this function will be:
 494
 495     @li @ref error::end_of_stream if no bytes were parsed, or
 496
 497     @li @ref error::partial_message if any bytes were parsed but the
 498         message was incomplete, otherwise:
 499
 500     @li A successful result. The next attempt to read will return
 501         @ref error::end_of_stream
 502
 503     @param stream The stream from which the data is to be read. The type must
 504     meet the <em>SyncReadStream</em> requirements.
 505
 506     @param buffer Storage for additional bytes read by the implementation from
 507     the stream. This is both an input and an output parameter; on entry, the
 508     parser will be presented with any remaining data in the dynamic buffer's
 509     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 510     requirements.
 511
 512     @param parser The parser to use.
 513
 514     @param ec Set to the error, if any occurred.
 515
 516     @return The number of bytes transferred from the stream.
 517
 518     @note The function returns the total number of bytes transferred from the
 519     stream. This may be zero for the case where there is sufficient pre-existing
 520     message data in the dynamic buffer. The implementation will call
 521     @ref basic_parser::eager with the value `true` on the parser passed in.
 522 */
 523 template<
 524     class SyncReadStream,
 525     class DynamicBuffer,
 526     bool isRequest>
 527 std::size_t
 528 read(
 529     SyncReadStream& stream,
 530     DynamicBuffer& buffer,
 531     basic_parser<isRequest>& parser,
 532     error_code& ec);
 533
 534 /** Read a complete message asynchronously from a stream using a parser.
 535
 536     This function is used to asynchronously read a complete message from a
 537     stream into an instance of @ref basic_parser. The function call always
 538     returns immediately. The asynchronous operation will continue until one
 539     of the following conditions is true:
 540
 541     @li @ref basic_parser::is_done returns `true`
 542
 543     @li An error occurs.
 544
 545     This operation is implemented in terms of zero or more calls to the
 546     next layer's `async_read_some` function, and is known as a <em>composed
 547     operation</em>. The program must ensure that the stream performs no other
 548     reads until this operation completes. The implementation may read additional
 549     bytes from the stream that lie past the end of the message being read.
 550     These additional bytes are stored in the dynamic buffer, which must be
 551     preserved for subsequent reads.
 552
 553     If the end of file error is received while reading from the stream, then
 554     the error returned from this function will be:
 555
 556     @li @ref error::end_of_stream if no bytes were parsed, or
 557
 558     @li @ref error::partial_message if any bytes were parsed but the
 559         message was incomplete, otherwise:
 560
 561     @li A successful result. The next attempt to read will return
 562         @ref error::end_of_stream
 563
 564     @param stream The stream from which the data is to be read. The type
 565     must meet the <em>AsyncReadStream</em> requirements.
 566
 567     @param buffer Storage for additional bytes read by the implementation from
 568     the stream. This is both an input and an output parameter; on entry, the
 569     parser will be presented with any remaining data in the dynamic buffer's
 570     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 571     requirements. The object must remain valid at least until the handler
 572     is called; ownership is not transferred.
 573
 574     @param parser The parser to use. The object must remain valid at least until
 575     the handler is called; ownership is not transferred.
 576
 577     @param handler The completion handler to invoke when the operation
 578     completes. The implementation takes ownership of the handler by
 579     performing a decay-copy. The equivalent function signature of
 580     the handler must be:
 581     @code
 582     void handler(
 583         error_code const& error,        // result of operation
 584         std::size_t bytes_transferred   // the total number of bytes transferred from the stream
 585     );
 586     @endcode
 587     Regardless of whether the asynchronous operation completes
 588     immediately or not, the handler will not be invoked from within
 589     this function. Invocation of the handler will be performed in a
 590     manner equivalent to using `net::post`.
 591
 592     @note The completion handler will receive as a parameter the total number
 593     of bytes transferred from the stream. This may be zero for the case where
 594     there is sufficient pre-existing message data in the dynamic buffer. The
 595     implementation will call @ref basic_parser::eager with the value `true`
 596     on the parser passed in.
 597 */
 598 template<
 599     class AsyncReadStream,
 600     class DynamicBuffer,
 601     bool isRequest,
 602     BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
 603         net::default_completion_token_t<
 604             executor_type<AsyncReadStream>>>
 605 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
 606 async_read(
 607     AsyncReadStream& stream,
 608     DynamicBuffer& buffer,
 609     basic_parser<isRequest>& parser,
 610     ReadHandler&& handler =
 611         net::default_completion_token_t<
 612             executor_type<AsyncReadStream>>{});
 613
 614 //------------------------------------------------------------------------------
 615
 616 /** Read a complete message from a stream.
 617
 618     This function is used to read a complete message from a stream into an
 619     instance of @ref message. The call will block until one of the following
 620     conditions is true:
 621
 622     @li The entire message is read in.
 623
 624     @li An error occurs.
 625
 626     This operation is implemented in terms of one or more calls to the stream's
 627     `read_some` function. The implementation may read additional bytes from
 628     the stream that lie past the end of the message being read. These additional
 629     bytes are stored in the dynamic buffer, which must be preserved for
 630     subsequent reads.
 631
 632     If the end of file error is received while reading from the stream, then
 633     the error returned from this function will be:
 634
 635     @li @ref error::end_of_stream if no bytes were parsed, or
 636
 637     @li @ref error::partial_message if any bytes were parsed but the
 638         message was incomplete, otherwise:
 639
 640     @li A successful result. The next attempt to read will return
 641         @ref error::end_of_stream
 642
 643     @param stream The stream from which the data is to be read. The type must
 644     meet the <em>SyncReadStream</em> requirements.
 645
 646     @param buffer Storage for additional bytes read by the implementation from
 647     the stream. This is both an input and an output parameter; on entry, the
 648     parser will be presented with any remaining data in the dynamic buffer's
 649     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 650     requirements.
 651
 652     @param msg The container in which to store the message contents. This
 653     message container should not have previous contents, otherwise the behavior
 654     is undefined. The type must be meet the <em>MoveAssignable</em> and
 655     <em>MoveConstructible</em> requirements.
 656
 657     @return The number of bytes transferred from the stream.
 658
 659     @throws system_error Thrown on failure.
 660
 661     @note The function returns the total number of bytes transferred from the
 662     stream. This may be zero for the case where there is sufficient pre-existing
 663     message data in the dynamic buffer. The implementation will call
 664     @ref basic_parser::eager with the value `true` on the parser passed in.
 665 */
 666 template<
 667     class SyncReadStream,
 668     class DynamicBuffer,
 669     bool isRequest, class Body, class Allocator>
 670 std::size_t
 671 read(
 672     SyncReadStream& stream,
 673     DynamicBuffer& buffer,
 674     message<isRequest, Body, basic_fields<Allocator>>& msg);
 675
 676 /** Read a complete message from a stream.
 677
 678     This function is used to read a complete message from a stream into an
 679     instance of @ref message. The call will block until one of the following
 680     conditions is true:
 681
 682     @li The entire message is read in.
 683
 684     @li An error occurs.
 685
 686     This operation is implemented in terms of one or more calls to the stream's
 687     `read_some` function. The implementation may read additional bytes from
 688     the stream that lie past the end of the message being read. These additional
 689     bytes are stored in the dynamic buffer, which must be preserved for
 690     subsequent reads.
 691
 692     If the end of file error is received while reading from the stream, then
 693     the error returned from this function will be:
 694
 695     @li @ref error::end_of_stream if no bytes were parsed, or
 696
 697     @li @ref error::partial_message if any bytes were parsed but the
 698         message was incomplete, otherwise:
 699
 700     @li A successful result. The next attempt to read will return
 701         @ref error::end_of_stream
 702
 703     @param stream The stream from which the data is to be read. The type must
 704     meet the <em>SyncReadStream</em> requirements.
 705
 706     @param buffer Storage for additional bytes read by the implementation from
 707     the stream. This is both an input and an output parameter; on entry, the
 708     parser will be presented with any remaining data in the dynamic buffer's
 709     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 710     requirements.
 711
 712     @param msg The container in which to store the message contents. This
 713     message container should not have previous contents, otherwise the behavior
 714     is undefined. The type must be meet the <em>MoveAssignable</em> and
 715     <em>MoveConstructible</em> requirements.
 716
 717     @param ec Set to the error, if any occurred.
 718
 719     @return The number of bytes transferred from the stream.
 720
 721     @note The function returns the total number of bytes transferred from the
 722     stream. This may be zero for the case where there is sufficient pre-existing
 723     message data in the dynamic buffer. The implementation will call
 724     @ref basic_parser::eager with the value `true` on the parser passed in.
 725 */
 726 template<
 727     class SyncReadStream,
 728     class DynamicBuffer,
 729     bool isRequest, class Body, class Allocator>
 730 std::size_t
 731 read(
 732     SyncReadStream& stream,
 733     DynamicBuffer& buffer,
 734     message<isRequest, Body, basic_fields<Allocator>>& msg,
 735     error_code& ec);
 736
 737 /** Read a complete message asynchronously from a stream.
 738
 739     This function is used to asynchronously read a complete message from a
 740     stream into an instance of @ref message. The function call always returns
 741     immediately. The asynchronous operation will continue until one of the
 742     following conditions is true:
 743
 744     @li The entire message is read in.
 745
 746     @li An error occurs.
 747
 748     This operation is implemented in terms of zero or more calls to the
 749     next layer's `async_read_some` function, and is known as a <em>composed
 750     operation</em>. The program must ensure that the stream performs no other
 751     reads until this operation completes. The implementation may read additional
 752     bytes from the stream that lie past the end of the message being read.
 753     These additional bytes are stored in the dynamic buffer, which must be
 754     preserved for subsequent reads.
 755
 756     If the end of file error is received while reading from the stream, then
 757     the error returned from this function will be:
 758
 759     @li @ref error::end_of_stream if no bytes were parsed, or
 760
 761     @li @ref error::partial_message if any bytes were parsed but the
 762         message was incomplete, otherwise:
 763
 764     @li A successful result. The next attempt to read will return
 765         @ref error::end_of_stream
 766
 767     @param stream The stream from which the data is to be read. The type
 768     must meet the <em>AsyncReadStream</em> requirements.
 769
 770     @param buffer Storage for additional bytes read by the implementation from
 771     the stream. This is both an input and an output parameter; on entry, the
 772     parser will be presented with any remaining data in the dynamic buffer's
 773     readable bytes sequence first. The type must meet the <em>DynamicBuffer</em>
 774     requirements. The object must remain valid at least until the handler
 775     is called; ownership is not transferred.
 776
 777     @param msg The container in which to store the message contents. This
 778     message container should not have previous contents, otherwise the behavior
 779     is undefined. The type must be meet the <em>MoveAssignable</em> and
 780     <em>MoveConstructible</em> requirements. The object must remain valid
 781     at least until the handler is called; ownership is not transferred.
 782
 783     @param handler The completion handler to invoke when the operation
 784     completes. The implementation takes ownership of the handler by
 785     performing a decay-copy. The equivalent function signature of
 786     the handler must be:
 787     @code
 788     void handler(
 789         error_code const& error,        // result of operation
 790         std::size_t bytes_transferred   // the total number of bytes transferred from the stream
 791     );
 792     @endcode
 793     Regardless of whether the asynchronous operation completes
 794     immediately or not, the handler will not be invoked from within
 795     this function. Invocation of the handler will be performed in a
 796     manner equivalent to using `net::post`.
 797
 798     @note The completion handler will receive as a parameter the total number
 799     of bytes transferred from the stream. This may be zero for the case where
 800     there is sufficient pre-existing message data in the dynamic buffer. The
 801     implementation will call @ref basic_parser::eager with the value `true`
 802     on the parser passed in.
 803 */
 804 template<
 805     class AsyncReadStream,
 806     class DynamicBuffer,
 807     bool isRequest, class Body, class Allocator,
 808     BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
 809         net::default_completion_token_t<
 810             executor_type<AsyncReadStream>>>
 811 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
 812 async_read(
 813     AsyncReadStream& stream,
 814     DynamicBuffer& buffer,
 815     message<isRequest, Body, basic_fields<Allocator>>& msg,
 816     ReadHandler&& handler =
 817         net::default_completion_token_t<
 818             executor_type<AsyncReadStream>>{});
 819
 820 } // http
 821 } // beast
 822 } // boost
 823
 824 #include <boost/beast/http/impl/read.hpp>
 825
 826 #endif