EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-04-25 08:53:54
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
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|