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