1 // 2 // read.hpp 3 // ~~~~~~~~ 4 // 5 // Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) 6 // 7 // Distributed under the Boost Software License, Version 1.0. (See accompanying 8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 9 // 10 11 #ifndef BOOST_ASIO_READ_HPP 12 #define BOOST_ASIO_READ_HPP 13 14 #if defined(_MSC_VER) && (_MSC_VER >= 1200) 15 # pragma once 16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) 17 18 #include <boost/asio/detail/config.hpp> 19 #include <cstddef> 20 #include <boost/asio/async_result.hpp> 21 #include <boost/asio/buffer.hpp> 22 #include <boost/asio/error.hpp> 23 24 #if !defined(BOOST_ASIO_NO_EXTENSIONS) 25 # include <boost/asio/basic_streambuf_fwd.hpp> 26 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) 27 28 #include <boost/asio/detail/push_options.hpp> 29 30 namespace boost { 31 namespace asio { 32 33 /** 34 * @defgroup read boost::asio::read 35 * 36 * @brief The @c read function is a composed operation that reads a certain 37 * amount of data from a stream before returning. 38 */ 39 /*@{*/ 40 41 /// Attempt to read a certain amount of data from a stream before returning. 42 /** 43 * This function is used to read a certain number of bytes of data from a 44 * stream. The call will block until one of the following conditions is true: 45 * 46 * @li The supplied buffers are full. That is, the bytes transferred is equal to 47 * the sum of the buffer sizes. 48 * 49 * @li An error occurred. 50 * 51 * This operation is implemented in terms of zero or more calls to the stream's 52 * read_some function. 53 * 54 * @param s The stream from which the data is to be read. The type must support 55 * the SyncReadStream concept. 56 * 57 * @param buffers One or more buffers into which the data will be read. The sum 58 * of the buffer sizes indicates the maximum number of bytes to read from the 59 * stream. 60 * 61 * @returns The number of bytes transferred. 62 * 63 * @throws boost::system::system_error Thrown on failure. 64 * 65 * @par Example 66 * To read into a single data buffer use the @ref buffer function as follows: 67 * @code boost::asio::read(s, boost::asio::buffer(data, size)); @endcode 68 * See the @ref buffer documentation for information on reading into multiple 69 * buffers in one go, and how to use it with arrays, boost::array or 70 * std::vector. 71 * 72 * @note This overload is equivalent to calling: 73 * @code boost::asio::read( 74 * s, buffers, 75 * boost::asio::transfer_all()); @endcode 76 */ 77 template <typename SyncReadStream, typename MutableBufferSequence> 78 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, 79 typename constraint< 80 is_mutable_buffer_sequence<MutableBufferSequence>::value 81 >::type = 0); 82 83 /// Attempt to read a certain amount of data from a stream before returning. 84 /** 85 * This function is used to read a certain number of bytes of data from a 86 * stream. The call will block until one of the following conditions is true: 87 * 88 * @li The supplied buffers are full. That is, the bytes transferred is equal to 89 * the sum of the buffer sizes. 90 * 91 * @li An error occurred. 92 * 93 * This operation is implemented in terms of zero or more calls to the stream's 94 * read_some function. 95 * 96 * @param s The stream from which the data is to be read. The type must support 97 * the SyncReadStream concept. 98 * 99 * @param buffers One or more buffers into which the data will be read. The sum 100 * of the buffer sizes indicates the maximum number of bytes to read from the 101 * stream. 102 * 103 * @param ec Set to indicate what error occurred, if any. 104 * 105 * @returns The number of bytes transferred. 106 * 107 * @par Example 108 * To read into a single data buffer use the @ref buffer function as follows: 109 * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode 110 * See the @ref buffer documentation for information on reading into multiple 111 * buffers in one go, and how to use it with arrays, boost::array or 112 * std::vector. 113 * 114 * @note This overload is equivalent to calling: 115 * @code boost::asio::read( 116 * s, buffers, 117 * boost::asio::transfer_all(), ec); @endcode 118 */ 119 template <typename SyncReadStream, typename MutableBufferSequence> 120 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, 121 boost::system::error_code& ec, 122 typename constraint< 123 is_mutable_buffer_sequence<MutableBufferSequence>::value 124 >::type = 0); 125 126 /// Attempt to read a certain amount of data from a stream before returning. 127 /** 128 * This function is used to read a certain number of bytes of data from a 129 * stream. The call will block until one of the following conditions is true: 130 * 131 * @li The supplied buffers are full. That is, the bytes transferred is equal to 132 * the sum of the buffer sizes. 133 * 134 * @li The completion_condition function object returns 0. 135 * 136 * This operation is implemented in terms of zero or more calls to the stream's 137 * read_some function. 138 * 139 * @param s The stream from which the data is to be read. The type must support 140 * the SyncReadStream concept. 141 * 142 * @param buffers One or more buffers into which the data will be read. The sum 143 * of the buffer sizes indicates the maximum number of bytes to read from the 144 * stream. 145 * 146 * @param completion_condition The function object to be called to determine 147 * whether the read operation is complete. The signature of the function object 148 * must be: 149 * @code std::size_t completion_condition( 150 * // Result of latest read_some operation. 151 * const boost::system::error_code& error, 152 * 153 * // Number of bytes transferred so far. 154 * std::size_t bytes_transferred 155 * ); @endcode 156 * A return value of 0 indicates that the read operation is complete. A non-zero 157 * return value indicates the maximum number of bytes to be read on the next 158 * call to the stream's read_some function. 159 * 160 * @returns The number of bytes transferred. 161 * 162 * @throws boost::system::system_error Thrown on failure. 163 * 164 * @par Example 165 * To read into a single data buffer use the @ref buffer function as follows: 166 * @code boost::asio::read(s, boost::asio::buffer(data, size), 167 * boost::asio::transfer_at_least(32)); @endcode 168 * See the @ref buffer documentation for information on reading into multiple 169 * buffers in one go, and how to use it with arrays, boost::array or 170 * std::vector. 171 */ 172 template <typename SyncReadStream, typename MutableBufferSequence, 173 typename CompletionCondition> 174 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, 175 CompletionCondition completion_condition, 176 typename constraint< 177 is_mutable_buffer_sequence<MutableBufferSequence>::value 178 >::type = 0); 179 180 /// Attempt to read a certain amount of data from a stream before returning. 181 /** 182 * This function is used to read a certain number of bytes of data from a 183 * stream. The call will block until one of the following conditions is true: 184 * 185 * @li The supplied buffers are full. That is, the bytes transferred is equal to 186 * the sum of the buffer sizes. 187 * 188 * @li The completion_condition function object returns 0. 189 * 190 * This operation is implemented in terms of zero or more calls to the stream's 191 * read_some function. 192 * 193 * @param s The stream from which the data is to be read. The type must support 194 * the SyncReadStream concept. 195 * 196 * @param buffers One or more buffers into which the data will be read. The sum 197 * of the buffer sizes indicates the maximum number of bytes to read from the 198 * stream. 199 * 200 * @param completion_condition The function object to be called to determine 201 * whether the read operation is complete. The signature of the function object 202 * must be: 203 * @code std::size_t completion_condition( 204 * // Result of latest read_some operation. 205 * const boost::system::error_code& error, 206 * 207 * // Number of bytes transferred so far. 208 * std::size_t bytes_transferred 209 * ); @endcode 210 * A return value of 0 indicates that the read operation is complete. A non-zero 211 * return value indicates the maximum number of bytes to be read on the next 212 * call to the stream's read_some function. 213 * 214 * @param ec Set to indicate what error occurred, if any. 215 * 216 * @returns The number of bytes read. If an error occurs, returns the total 217 * number of bytes successfully transferred prior to the error. 218 */ 219 template <typename SyncReadStream, typename MutableBufferSequence, 220 typename CompletionCondition> 221 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, 222 CompletionCondition completion_condition, boost::system::error_code& ec, 223 typename constraint< 224 is_mutable_buffer_sequence<MutableBufferSequence>::value 225 >::type = 0); 226 227 #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) 228 229 /// Attempt to read a certain amount of data from a stream before returning. 230 /** 231 * This function is used to read a certain number of bytes of data from a 232 * stream. The call will block until one of the following conditions is true: 233 * 234 * @li The specified dynamic buffer sequence is full (that is, it has reached 235 * maximum size). 236 * 237 * @li An error occurred. 238 * 239 * This operation is implemented in terms of zero or more calls to the stream's 240 * read_some function. 241 * 242 * @param s The stream from which the data is to be read. The type must support 243 * the SyncReadStream concept. 244 * 245 * @param buffers The dynamic buffer sequence into which the data will be read. 246 * 247 * @returns The number of bytes transferred. 248 * 249 * @throws boost::system::system_error Thrown on failure. 250 * 251 * @note This overload is equivalent to calling: 252 * @code boost::asio::read( 253 * s, buffers, 254 * boost::asio::transfer_all()); @endcode 255 */ 256 template <typename SyncReadStream, typename DynamicBuffer_v1> 257 std::size_t read(SyncReadStream& s, 258 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, 259 typename constraint< 260 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value 261 >::type = 0, 262 typename constraint< 263 !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value 264 >::type = 0); 265 266 /// Attempt to read a certain amount of data from a stream before returning. 267 /** 268 * This function is used to read a certain number of bytes of data from a 269 * stream. The call will block until one of the following conditions is true: 270 * 271 * @li The supplied buffer is full (that is, it has reached maximum size). 272 * 273 * @li An error occurred. 274 * 275 * This operation is implemented in terms of zero or more calls to the stream's 276 * read_some function. 277 * 278 * @param s The stream from which the data is to be read. The type must support 279 * the SyncReadStream concept. 280 * 281 * @param buffers The dynamic buffer sequence into which the data will be read. 282 * 283 * @param ec Set to indicate what error occurred, if any. 284 * 285 * @returns The number of bytes transferred. 286 * 287 * @note This overload is equivalent to calling: 288 * @code boost::asio::read( 289 * s, buffers, 290 * boost::asio::transfer_all(), ec); @endcode 291 */ 292 template <typename SyncReadStream, typename DynamicBuffer_v1> 293 std::size_t read(SyncReadStream& s, 294 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, 295 boost::system::error_code& ec, 296 typename constraint< 297 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value 298 >::type = 0, 299 typename constraint< 300 !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value 301 >::type = 0); 302 303 /// Attempt to read a certain amount of data from a stream before returning. 304 /** 305 * This function is used to read a certain number of bytes of data from a 306 * stream. The call will block until one of the following conditions is true: 307 * 308 * @li The specified dynamic buffer sequence is full (that is, it has reached 309 * maximum size). 310 * 311 * @li The completion_condition function object returns 0. 312 * 313 * This operation is implemented in terms of zero or more calls to the stream's 314 * read_some function. 315 * 316 * @param s The stream from which the data is to be read. The type must support 317 * the SyncReadStream concept. 318 * 319 * @param buffers The dynamic buffer sequence into which the data will be read. 320 * 321 * @param completion_condition The function object to be called to determine 322 * whether the read operation is complete. The signature of the function object 323 * must be: 324 * @code std::size_t completion_condition( 325 * // Result of latest read_some operation. 326 * const boost::system::error_code& error, 327 * 328 * // Number of bytes transferred so far. 329 * std::size_t bytes_transferred 330 * ); @endcode 331 * A return value of 0 indicates that the read operation is complete. A non-zero 332 * return value indicates the maximum number of bytes to be read on the next 333 * call to the stream's read_some function. 334 * 335 * @returns The number of bytes transferred. 336 * 337 * @throws boost::system::system_error Thrown on failure. 338 */ 339 template <typename SyncReadStream, typename DynamicBuffer_v1, 340 typename CompletionCondition> 341 std::size_t read(SyncReadStream& s, 342 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, 343 CompletionCondition completion_condition, 344 typename constraint< 345 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value 346 >::type = 0, 347 typename constraint< 348 !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value 349 >::type = 0); 350 351 /// Attempt to read a certain amount of data from a stream before returning. 352 /** 353 * This function is used to read a certain number of bytes of data from a 354 * stream. The call will block until one of the following conditions is true: 355 * 356 * @li The specified dynamic buffer sequence is full (that is, it has reached 357 * maximum size). 358 * 359 * @li The completion_condition function object returns 0. 360 * 361 * This operation is implemented in terms of zero or more calls to the stream's 362 * read_some function. 363 * 364 * @param s The stream from which the data is to be read. The type must support 365 * the SyncReadStream concept. 366 * 367 * @param buffers The dynamic buffer sequence into which the data will be read. 368 * 369 * @param completion_condition The function object to be called to determine 370 * whether the read operation is complete. The signature of the function object 371 * must be: 372 * @code std::size_t completion_condition( 373 * // Result of latest read_some operation. 374 * const boost::system::error_code& error, 375 * 376 * // Number of bytes transferred so far. 377 * std::size_t bytes_transferred 378 * ); @endcode 379 * A return value of 0 indicates that the read operation is complete. A non-zero 380 * return value indicates the maximum number of bytes to be read on the next 381 * call to the stream's read_some function. 382 * 383 * @param ec Set to indicate what error occurred, if any. 384 * 385 * @returns The number of bytes read. If an error occurs, returns the total 386 * number of bytes successfully transferred prior to the error. 387 */ 388 template <typename SyncReadStream, typename DynamicBuffer_v1, 389 typename CompletionCondition> 390 std::size_t read(SyncReadStream& s, 391 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, 392 CompletionCondition completion_condition, boost::system::error_code& ec, 393 typename constraint< 394 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value 395 >::type = 0, 396 typename constraint< 397 !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value 398 >::type = 0); 399 400 #if !defined(BOOST_ASIO_NO_EXTENSIONS) 401 #if !defined(BOOST_ASIO_NO_IOSTREAM) 402 403 /// Attempt to read a certain amount of data from a stream before returning. 404 /** 405 * This function is used to read a certain number of bytes of data from a 406 * stream. The call will block until one of the following conditions is true: 407 * 408 * @li The supplied buffer is full (that is, it has reached maximum size). 409 * 410 * @li An error occurred. 411 * 412 * This operation is implemented in terms of zero or more calls to the stream's 413 * read_some function. 414 * 415 * @param s The stream from which the data is to be read. The type must support 416 * the SyncReadStream concept. 417 * 418 * @param b The basic_streambuf object into which the data will be read. 419 * 420 * @returns The number of bytes transferred. 421 * 422 * @throws boost::system::system_error Thrown on failure. 423 * 424 * @note This overload is equivalent to calling: 425 * @code boost::asio::read( 426 * s, b, 427 * boost::asio::transfer_all()); @endcode 428 */ 429 template <typename SyncReadStream, typename Allocator> 430 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b); 431 432 /// Attempt to read a certain amount of data from a stream before returning. 433 /** 434 * This function is used to read a certain number of bytes of data from a 435 * stream. The call will block until one of the following conditions is true: 436 * 437 * @li The supplied buffer is full (that is, it has reached maximum size). 438 * 439 * @li An error occurred. 440 * 441 * This operation is implemented in terms of zero or more calls to the stream's 442 * read_some function. 443 * 444 * @param s The stream from which the data is to be read. The type must support 445 * the SyncReadStream concept. 446 * 447 * @param b The basic_streambuf object into which the data will be read. 448 * 449 * @param ec Set to indicate what error occurred, if any. 450 * 451 * @returns The number of bytes transferred. 452 * 453 * @note This overload is equivalent to calling: 454 * @code boost::asio::read( 455 * s, b, 456 * boost::asio::transfer_all(), ec); @endcode 457 */ 458 template <typename SyncReadStream, typename Allocator> 459 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, 460 boost::system::error_code& ec); 461 462 /// Attempt to read a certain amount of data from a stream before returning. 463 /** 464 * This function is used to read a certain number of bytes of data from a 465 * stream. The call will block until one of the following conditions is true: 466 * 467 * @li The supplied buffer is full (that is, it has reached maximum size). 468 * 469 * @li The completion_condition function object returns 0. 470 * 471 * This operation is implemented in terms of zero or more calls to the stream's 472 * read_some function. 473 * 474 * @param s The stream from which the data is to be read. The type must support 475 * the SyncReadStream concept. 476 * 477 * @param b The basic_streambuf object into which the data will be read. 478 * 479 * @param completion_condition The function object to be called to determine 480 * whether the read operation is complete. The signature of the function object 481 * must be: 482 * @code std::size_t completion_condition( 483 * // Result of latest read_some operation. 484 * const boost::system::error_code& error, 485 * 486 * // Number of bytes transferred so far. 487 * std::size_t bytes_transferred 488 * ); @endcode 489 * A return value of 0 indicates that the read operation is complete. A non-zero 490 * return value indicates the maximum number of bytes to be read on the next 491 * call to the stream's read_some function. 492 * 493 * @returns The number of bytes transferred. 494 * 495 * @throws boost::system::system_error Thrown on failure. 496 */ 497 template <typename SyncReadStream, typename Allocator, 498 typename CompletionCondition> 499 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, 500 CompletionCondition completion_condition); 501 502 /// Attempt to read a certain amount of data from a stream before returning. 503 /** 504 * This function is used to read a certain number of bytes of data from a 505 * stream. The call will block until one of the following conditions is true: 506 * 507 * @li The supplied buffer is full (that is, it has reached maximum size). 508 * 509 * @li The completion_condition function object returns 0. 510 * 511 * This operation is implemented in terms of zero or more calls to the stream's 512 * read_some function. 513 * 514 * @param s The stream from which the data is to be read. The type must support 515 * the SyncReadStream concept. 516 * 517 * @param b The basic_streambuf object into which the data will be read. 518 * 519 * @param completion_condition The function object to be called to determine 520 * whether the read operation is complete. The signature of the function object 521 * must be: 522 * @code std::size_t completion_condition( 523 * // Result of latest read_some operation. 524 * const boost::system::error_code& error, 525 * 526 * // Number of bytes transferred so far. 527 * std::size_t bytes_transferred 528 * ); @endcode 529 * A return value of 0 indicates that the read operation is complete. A non-zero 530 * return value indicates the maximum number of bytes to be read on the next 531 * call to the stream's read_some function. 532 * 533 * @param ec Set to indicate what error occurred, if any. 534 * 535 * @returns The number of bytes read. If an error occurs, returns the total 536 * number of bytes successfully transferred prior to the error. 537 */ 538 template <typename SyncReadStream, typename Allocator, 539 typename CompletionCondition> 540 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, 541 CompletionCondition completion_condition, boost::system::error_code& ec); 542 543 #endif // !defined(BOOST_ASIO_NO_IOSTREAM) 544 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) 545 #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) 546 547 /// Attempt to read a certain amount of data from a stream before returning. 548 /** 549 * This function is used to read a certain number of bytes of data from a 550 * stream. The call will block until one of the following conditions is true: 551 * 552 * @li The specified dynamic buffer sequence is full (that is, it has reached 553 * maximum size). 554 * 555 * @li An error occurred. 556 * 557 * This operation is implemented in terms of zero or more calls to the stream's 558 * read_some function. 559 * 560 * @param s The stream from which the data is to be read. The type must support 561 * the SyncReadStream concept. 562 * 563 * @param buffers The dynamic buffer sequence into which the data will be read. 564 * 565 * @returns The number of bytes transferred. 566 * 567 * @throws boost::system::system_error Thrown on failure. 568 * 569 * @note This overload is equivalent to calling: 570 * @code boost::asio::read( 571 * s, buffers, 572 * boost::asio::transfer_all()); @endcode 573 */ 574 template <typename SyncReadStream, typename DynamicBuffer_v2> 575 std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, 576 typename constraint< 577 is_dynamic_buffer_v2<DynamicBuffer_v2>::value 578 >::type = 0); 579 580 /// Attempt to read a certain amount of data from a stream before returning. 581 /** 582 * This function is used to read a certain number of bytes of data from a 583 * stream. The call will block until one of the following conditions is true: 584 * 585 * @li The supplied buffer is full (that is, it has reached maximum size). 586 * 587 * @li An error occurred. 588 * 589 * This operation is implemented in terms of zero or more calls to the stream's 590 * read_some function. 591 * 592 * @param s The stream from which the data is to be read. The type must support 593 * the SyncReadStream concept. 594 * 595 * @param buffers The dynamic buffer sequence into which the data will be read. 596 * 597 * @param ec Set to indicate what error occurred, if any. 598 * 599 * @returns The number of bytes transferred. 600 * 601 * @note This overload is equivalent to calling: 602 * @code boost::asio::read( 603 * s, buffers, 604 * boost::asio::transfer_all(), ec); @endcode 605 */ 606 template <typename SyncReadStream, typename DynamicBuffer_v2> 607 std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, 608 boost::system::error_code& ec, 609 typename constraint< 610 is_dynamic_buffer_v2<DynamicBuffer_v2>::value 611 >::type = 0); 612 613 /// Attempt to read a certain amount of data from a stream before returning. 614 /** 615 * This function is used to read a certain number of bytes of data from a 616 * stream. The call will block until one of the following conditions is true: 617 * 618 * @li The specified dynamic buffer sequence is full (that is, it has reached 619 * maximum size). 620 * 621 * @li The completion_condition function object returns 0. 622 * 623 * This operation is implemented in terms of zero or more calls to the stream's 624 * read_some function. 625 * 626 * @param s The stream from which the data is to be read. The type must support 627 * the SyncReadStream concept. 628 * 629 * @param buffers The dynamic buffer sequence into which the data will be read. 630 * 631 * @param completion_condition The function object to be called to determine 632 * whether the read operation is complete. The signature of the function object 633 * must be: 634 * @code std::size_t completion_condition( 635 * // Result of latest read_some operation. 636 * const boost::system::error_code& error, 637 * 638 * // Number of bytes transferred so far. 639 * std::size_t bytes_transferred 640 * ); @endcode 641 * A return value of 0 indicates that the read operation is complete. A non-zero 642 * return value indicates the maximum number of bytes to be read on the next 643 * call to the stream's read_some function. 644 * 645 * @returns The number of bytes transferred. 646 * 647 * @throws boost::system::system_error Thrown on failure. 648 */ 649 template <typename SyncReadStream, typename DynamicBuffer_v2, 650 typename CompletionCondition> 651 std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, 652 CompletionCondition completion_condition, 653 typename constraint< 654 is_dynamic_buffer_v2<DynamicBuffer_v2>::value 655 >::type = 0); 656 657 /// Attempt to read a certain amount of data from a stream before returning. 658 /** 659 * This function is used to read a certain number of bytes of data from a 660 * stream. The call will block until one of the following conditions is true: 661 * 662 * @li The specified dynamic buffer sequence is full (that is, it has reached 663 * maximum size). 664 * 665 * @li The completion_condition function object returns 0. 666 * 667 * This operation is implemented in terms of zero or more calls to the stream's 668 * read_some function. 669 * 670 * @param s The stream from which the data is to be read. The type must support 671 * the SyncReadStream concept. 672 * 673 * @param buffers The dynamic buffer sequence into which the data will be read. 674 * 675 * @param completion_condition The function object to be called to determine 676 * whether the read operation is complete. The signature of the function object 677 * must be: 678 * @code std::size_t completion_condition( 679 * // Result of latest read_some operation. 680 * const boost::system::error_code& error, 681 * 682 * // Number of bytes transferred so far. 683 * std::size_t bytes_transferred 684 * ); @endcode 685 * A return value of 0 indicates that the read operation is complete. A non-zero 686 * return value indicates the maximum number of bytes to be read on the next 687 * call to the stream's read_some function. 688 * 689 * @param ec Set to indicate what error occurred, if any. 690 * 691 * @returns The number of bytes read. If an error occurs, returns the total 692 * number of bytes successfully transferred prior to the error. 693 */ 694 template <typename SyncReadStream, typename DynamicBuffer_v2, 695 typename CompletionCondition> 696 std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, 697 CompletionCondition completion_condition, boost::system::error_code& ec, 698 typename constraint< 699 is_dynamic_buffer_v2<DynamicBuffer_v2>::value 700 >::type = 0); 701 702 /*@}*/ 703 /** 704 * @defgroup async_read boost::asio::async_read 705 * 706 * @brief The @c async_read function is a composed asynchronous operation that 707 * reads a certain amount of data from a stream before completion. 708 */ 709 /*@{*/ 710 711 /// Start an asynchronous operation to read a certain amount of data from a 712 /// stream. 713 /** 714 * This function is used to asynchronously read a certain number of bytes of 715 * data from a stream. The function call always returns immediately. The 716 * asynchronous operation will continue until one of the following conditions is 717 * true: 718 * 719 * @li The supplied buffers are full. That is, the bytes transferred is equal to 720 * the sum of the buffer sizes. 721 * 722 * @li An error occurred. 723 * 724 * This operation is implemented in terms of zero or more calls to the stream's 725 * async_read_some function, and is known as a <em>composed operation</em>. The 726 * program must ensure that the stream performs no other read operations (such 727 * as async_read, the stream's async_read_some function, or any other composed 728 * operations that perform reads) until this operation completes. 729 * 730 * @param s The stream from which the data is to be read. The type must support 731 * the AsyncReadStream concept. 732 * 733 * @param buffers One or more buffers into which the data will be read. The sum 734 * of the buffer sizes indicates the maximum number of bytes to read from the 735 * stream. Although the buffers object may be copied as necessary, ownership of 736 * the underlying memory blocks is retained by the caller, which must guarantee 737 * that they remain valid until the handler is called. 738 * 739 * @param handler The handler to be called when the read operation completes. 740 * Copies will be made of the handler as required. The function signature of the 741 * handler must be: 742 * @code void handler( 743 * const boost::system::error_code& error, // Result of operation. 744 * 745 * std::size_t bytes_transferred // Number of bytes copied into the 746 * // buffers. If an error occurred, 747 * // this will be the number of 748 * // bytes successfully transferred 749 * // prior to the error. 750 * ); @endcode 751 * Regardless of whether the asynchronous operation completes immediately or 752 * not, the handler will not be invoked from within this function. On 753 * immediate completion, invocation of the handler will be performed in a 754 * manner equivalent to using boost::asio::post(). 755 * 756 * @par Example 757 * To read into a single data buffer use the @ref buffer function as follows: 758 * @code 759 * boost::asio::async_read(s, boost::asio::buffer(data, size), handler); 760 * @endcode 761 * See the @ref buffer documentation for information on reading into multiple 762 * buffers in one go, and how to use it with arrays, boost::array or 763 * std::vector. 764 * 765 * @note This overload is equivalent to calling: 766 * @code boost::asio::async_read( 767 * s, buffers, 768 * boost::asio::transfer_all(), 769 * handler); @endcode 770 */ 771 template <typename AsyncReadStream, typename MutableBufferSequence, 772 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 773 std::size_t)) ReadHandler 774 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 775 typename AsyncReadStream::executor_type)> 776 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, 777 void (boost::system::error_code, std::size_t)) 778 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, 779 BOOST_ASIO_MOVE_ARG(ReadHandler) handler 780 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 781 typename AsyncReadStream::executor_type), 782 typename constraint< 783 is_mutable_buffer_sequence<MutableBufferSequence>::value 784 >::type = 0); 785 786 /// Start an asynchronous operation to read a certain amount of data from a 787 /// stream. 788 /** 789 * This function is used to asynchronously read a certain number of bytes of 790 * data from a stream. The function call always returns immediately. The 791 * asynchronous operation will continue until one of the following conditions is 792 * true: 793 * 794 * @li The supplied buffers are full. That is, the bytes transferred is equal to 795 * the sum of the buffer sizes. 796 * 797 * @li The completion_condition function object returns 0. 798 * 799 * @param s The stream from which the data is to be read. The type must support 800 * the AsyncReadStream concept. 801 * 802 * @param buffers One or more buffers into which the data will be read. The sum 803 * of the buffer sizes indicates the maximum number of bytes to read from the 804 * stream. Although the buffers object may be copied as necessary, ownership of 805 * the underlying memory blocks is retained by the caller, which must guarantee 806 * that they remain valid until the handler is called. 807 * 808 * @param completion_condition The function object to be called to determine 809 * whether the read operation is complete. The signature of the function object 810 * must be: 811 * @code std::size_t completion_condition( 812 * // Result of latest async_read_some operation. 813 * const boost::system::error_code& error, 814 * 815 * // Number of bytes transferred so far. 816 * std::size_t bytes_transferred 817 * ); @endcode 818 * A return value of 0 indicates that the read operation is complete. A non-zero 819 * return value indicates the maximum number of bytes to be read on the next 820 * call to the stream's async_read_some function. 821 * 822 * @param handler The handler to be called when the read operation completes. 823 * Copies will be made of the handler as required. The function signature of the 824 * handler must be: 825 * @code void handler( 826 * const boost::system::error_code& error, // Result of operation. 827 * 828 * std::size_t bytes_transferred // Number of bytes copied into the 829 * // buffers. If an error occurred, 830 * // this will be the number of 831 * // bytes successfully transferred 832 * // prior to the error. 833 * ); @endcode 834 * Regardless of whether the asynchronous operation completes immediately or 835 * not, the handler will not be invoked from within this function. On 836 * immediate completion, invocation of the handler will be performed in a 837 * manner equivalent to using boost::asio::post(). 838 * 839 * @par Example 840 * To read into a single data buffer use the @ref buffer function as follows: 841 * @code boost::asio::async_read(s, 842 * boost::asio::buffer(data, size), 843 * boost::asio::transfer_at_least(32), 844 * handler); @endcode 845 * See the @ref buffer documentation for information on reading into multiple 846 * buffers in one go, and how to use it with arrays, boost::array or 847 * std::vector. 848 */ 849 template <typename AsyncReadStream, 850 typename MutableBufferSequence, typename CompletionCondition, 851 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 852 std::size_t)) ReadHandler 853 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 854 typename AsyncReadStream::executor_type)> 855 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, 856 void (boost::system::error_code, std::size_t)) 857 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, 858 CompletionCondition completion_condition, 859 BOOST_ASIO_MOVE_ARG(ReadHandler) handler 860 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 861 typename AsyncReadStream::executor_type), 862 typename constraint< 863 is_mutable_buffer_sequence<MutableBufferSequence>::value 864 >::type = 0); 865 866 #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) 867 868 /// Start an asynchronous operation to read a certain amount of data from a 869 /// stream. 870 /** 871 * This function is used to asynchronously read a certain number of bytes of 872 * data from a stream. The function call always returns immediately. The 873 * asynchronous operation will continue until one of the following conditions is 874 * true: 875 * 876 * @li The specified dynamic buffer sequence is full (that is, it has reached 877 * maximum size). 878 * 879 * @li An error occurred. 880 * 881 * This operation is implemented in terms of zero or more calls to the stream's 882 * async_read_some function, and is known as a <em>composed operation</em>. The 883 * program must ensure that the stream performs no other read operations (such 884 * as async_read, the stream's async_read_some function, or any other composed 885 * operations that perform reads) until this operation completes. 886 * 887 * @param s The stream from which the data is to be read. The type must support 888 * the AsyncReadStream concept. 889 * 890 * @param buffers The dynamic buffer sequence into which the data will be read. 891 * Although the buffers object may be copied as necessary, ownership of the 892 * underlying memory blocks is retained by the caller, which must guarantee 893 * that they remain valid until the handler is called. 894 * 895 * @param handler The handler to be called when the read operation completes. 896 * Copies will be made of the handler as required. The function signature of the 897 * handler must be: 898 * @code void handler( 899 * const boost::system::error_code& error, // Result of operation. 900 * 901 * std::size_t bytes_transferred // Number of bytes copied into the 902 * // buffers. If an error occurred, 903 * // this will be the number of 904 * // bytes successfully transferred 905 * // prior to the error. 906 * ); @endcode 907 * Regardless of whether the asynchronous operation completes immediately or 908 * not, the handler will not be invoked from within this function. On 909 * immediate completion, invocation of the handler will be performed in a 910 * manner equivalent to using boost::asio::post(). 911 * 912 * @note This overload is equivalent to calling: 913 * @code boost::asio::async_read( 914 * s, buffers, 915 * boost::asio::transfer_all(), 916 * handler); @endcode 917 */ 918 template <typename AsyncReadStream, typename DynamicBuffer_v1, 919 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 920 std::size_t)) ReadHandler 921 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 922 typename AsyncReadStream::executor_type)> 923 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, 924 void (boost::system::error_code, std::size_t)) 925 async_read(AsyncReadStream& s, 926 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, 927 BOOST_ASIO_MOVE_ARG(ReadHandler) handler 928 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 929 typename AsyncReadStream::executor_type), 930 typename constraint< 931 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value 932 >::type = 0, 933 typename constraint< 934 !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value 935 >::type = 0); 936 937 /// Start an asynchronous operation to read a certain amount of data from a 938 /// stream. 939 /** 940 * This function is used to asynchronously read a certain number of bytes of 941 * data from a stream. The function call always returns immediately. The 942 * asynchronous operation will continue until one of the following conditions is 943 * true: 944 * 945 * @li The specified dynamic buffer sequence is full (that is, it has reached 946 * maximum size). 947 * 948 * @li The completion_condition function object returns 0. 949 * 950 * This operation is implemented in terms of zero or more calls to the stream's 951 * async_read_some function, and is known as a <em>composed operation</em>. The 952 * program must ensure that the stream performs no other read operations (such 953 * as async_read, the stream's async_read_some function, or any other composed 954 * operations that perform reads) until this operation completes. 955 * 956 * @param s The stream from which the data is to be read. The type must support 957 * the AsyncReadStream concept. 958 * 959 * @param buffers The dynamic buffer sequence into which the data will be read. 960 * Although the buffers object may be copied as necessary, ownership of the 961 * underlying memory blocks is retained by the caller, which must guarantee 962 * that they remain valid until the handler is called. 963 * 964 * @param completion_condition The function object to be called to determine 965 * whether the read operation is complete. The signature of the function object 966 * must be: 967 * @code std::size_t completion_condition( 968 * // Result of latest async_read_some operation. 969 * const boost::system::error_code& error, 970 * 971 * // Number of bytes transferred so far. 972 * std::size_t bytes_transferred 973 * ); @endcode 974 * A return value of 0 indicates that the read operation is complete. A non-zero 975 * return value indicates the maximum number of bytes to be read on the next 976 * call to the stream's async_read_some function. 977 * 978 * @param handler The handler to be called when the read operation completes. 979 * Copies will be made of the handler as required. The function signature of the 980 * handler must be: 981 * @code void handler( 982 * const boost::system::error_code& error, // Result of operation. 983 * 984 * std::size_t bytes_transferred // Number of bytes copied into the 985 * // buffers. If an error occurred, 986 * // this will be the number of 987 * // bytes successfully transferred 988 * // prior to the error. 989 * ); @endcode 990 * Regardless of whether the asynchronous operation completes immediately or 991 * not, the handler will not be invoked from within this function. On 992 * immediate completion, invocation of the handler will be performed in a 993 * manner equivalent to using boost::asio::post(). 994 */ 995 template <typename AsyncReadStream, 996 typename DynamicBuffer_v1, typename CompletionCondition, 997 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 998 std::size_t)) ReadHandler 999 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 1000 typename AsyncReadStream::executor_type)> 1001 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, 1002 void (boost::system::error_code, std::size_t)) 1003 async_read(AsyncReadStream& s, 1004 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, 1005 CompletionCondition completion_condition, 1006 BOOST_ASIO_MOVE_ARG(ReadHandler) handler 1007 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 1008 typename AsyncReadStream::executor_type), 1009 typename constraint< 1010 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value 1011 >::type = 0, 1012 typename constraint< 1013 !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value 1014 >::type = 0); 1015 1016 #if !defined(BOOST_ASIO_NO_EXTENSIONS) 1017 #if !defined(BOOST_ASIO_NO_IOSTREAM) 1018 1019 /// Start an asynchronous operation to read a certain amount of data from a 1020 /// stream. 1021 /** 1022 * This function is used to asynchronously read a certain number of bytes of 1023 * data from a stream. The function call always returns immediately. The 1024 * asynchronous operation will continue until one of the following conditions is 1025 * true: 1026 * 1027 * @li The supplied buffer is full (that is, it has reached maximum size). 1028 * 1029 * @li An error occurred. 1030 * 1031 * This operation is implemented in terms of zero or more calls to the stream's 1032 * async_read_some function, and is known as a <em>composed operation</em>. The 1033 * program must ensure that the stream performs no other read operations (such 1034 * as async_read, the stream's async_read_some function, or any other composed 1035 * operations that perform reads) until this operation completes. 1036 * 1037 * @param s The stream from which the data is to be read. The type must support 1038 * the AsyncReadStream concept. 1039 * 1040 * @param b A basic_streambuf object into which the data will be read. Ownership 1041 * of the streambuf is retained by the caller, which must guarantee that it 1042 * remains valid until the handler is called. 1043 * 1044 * @param handler The handler to be called when the read operation completes. 1045 * Copies will be made of the handler as required. The function signature of the 1046 * handler must be: 1047 * @code void handler( 1048 * const boost::system::error_code& error, // Result of operation. 1049 * 1050 * std::size_t bytes_transferred // Number of bytes copied into the 1051 * // buffers. If an error occurred, 1052 * // this will be the number of 1053 * // bytes successfully transferred 1054 * // prior to the error. 1055 * ); @endcode 1056 * Regardless of whether the asynchronous operation completes immediately or 1057 * not, the handler will not be invoked from within this function. On 1058 * immediate completion, invocation of the handler will be performed in a 1059 * manner equivalent to using boost::asio::post(). 1060 * 1061 * @note This overload is equivalent to calling: 1062 * @code boost::asio::async_read( 1063 * s, b, 1064 * boost::asio::transfer_all(), 1065 * handler); @endcode 1066 */ 1067 template <typename AsyncReadStream, typename Allocator, 1068 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 1069 std::size_t)) ReadHandler 1070 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 1071 typename AsyncReadStream::executor_type)> 1072 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, 1073 void (boost::system::error_code, std::size_t)) 1074 async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b, 1075 BOOST_ASIO_MOVE_ARG(ReadHandler) handler 1076 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 1077 typename AsyncReadStream::executor_type)); 1078 1079 /// Start an asynchronous operation to read a certain amount of data from a 1080 /// stream. 1081 /** 1082 * This function is used to asynchronously read a certain number of bytes of 1083 * data from a stream. The function call always returns immediately. The 1084 * asynchronous operation will continue until one of the following conditions is 1085 * true: 1086 * 1087 * @li The supplied buffer is full (that is, it has reached maximum size). 1088 * 1089 * @li The completion_condition function object returns 0. 1090 * 1091 * This operation is implemented in terms of zero or more calls to the stream's 1092 * async_read_some function, and is known as a <em>composed operation</em>. The 1093 * program must ensure that the stream performs no other read operations (such 1094 * as async_read, the stream's async_read_some function, or any other composed 1095 * operations that perform reads) until this operation completes. 1096 * 1097 * @param s The stream from which the data is to be read. The type must support 1098 * the AsyncReadStream concept. 1099 * 1100 * @param b A basic_streambuf object into which the data will be read. Ownership 1101 * of the streambuf is retained by the caller, which must guarantee that it 1102 * remains valid until the handler is called. 1103 * 1104 * @param completion_condition The function object to be called to determine 1105 * whether the read operation is complete. The signature of the function object 1106 * must be: 1107 * @code std::size_t completion_condition( 1108 * // Result of latest async_read_some operation. 1109 * const boost::system::error_code& error, 1110 * 1111 * // Number of bytes transferred so far. 1112 * std::size_t bytes_transferred 1113 * ); @endcode 1114 * A return value of 0 indicates that the read operation is complete. A non-zero 1115 * return value indicates the maximum number of bytes to be read on the next 1116 * call to the stream's async_read_some function. 1117 * 1118 * @param handler The handler to be called when the read operation completes. 1119 * Copies will be made of the handler as required. The function signature of the 1120 * handler must be: 1121 * @code void handler( 1122 * const boost::system::error_code& error, // Result of operation. 1123 * 1124 * std::size_t bytes_transferred // Number of bytes copied into the 1125 * // buffers. If an error occurred, 1126 * // this will be the number of 1127 * // bytes successfully transferred 1128 * // prior to the error. 1129 * ); @endcode 1130 * Regardless of whether the asynchronous operation completes immediately or 1131 * not, the handler will not be invoked from within this function. On 1132 * immediate completion, invocation of the handler will be performed in a 1133 * manner equivalent to using boost::asio::post(). 1134 */ 1135 template <typename AsyncReadStream, 1136 typename Allocator, typename CompletionCondition, 1137 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 1138 std::size_t)) ReadHandler 1139 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 1140 typename AsyncReadStream::executor_type)> 1141 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, 1142 void (boost::system::error_code, std::size_t)) 1143 async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b, 1144 CompletionCondition completion_condition, 1145 BOOST_ASIO_MOVE_ARG(ReadHandler) handler 1146 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 1147 typename AsyncReadStream::executor_type)); 1148 1149 #endif // !defined(BOOST_ASIO_NO_IOSTREAM) 1150 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) 1151 #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) 1152 1153 /// Start an asynchronous operation to read a certain amount of data from a 1154 /// stream. 1155 /** 1156 * This function is used to asynchronously read a certain number of bytes of 1157 * data from a stream. The function call always returns immediately. The 1158 * asynchronous operation will continue until one of the following conditions is 1159 * true: 1160 * 1161 * @li The specified dynamic buffer sequence is full (that is, it has reached 1162 * maximum size). 1163 * 1164 * @li An error occurred. 1165 * 1166 * This operation is implemented in terms of zero or more calls to the stream's 1167 * async_read_some function, and is known as a <em>composed operation</em>. The 1168 * program must ensure that the stream performs no other read operations (such 1169 * as async_read, the stream's async_read_some function, or any other composed 1170 * operations that perform reads) until this operation completes. 1171 * 1172 * @param s The stream from which the data is to be read. The type must support 1173 * the AsyncReadStream concept. 1174 * 1175 * @param buffers The dynamic buffer sequence into which the data will be read. 1176 * Although the buffers object may be copied as necessary, ownership of the 1177 * underlying memory blocks is retained by the caller, which must guarantee 1178 * that they remain valid until the handler is called. 1179 * 1180 * @param handler The handler to be called when the read operation completes. 1181 * Copies will be made of the handler as required. The function signature of the 1182 * handler must be: 1183 * @code void handler( 1184 * const boost::system::error_code& error, // Result of operation. 1185 * 1186 * std::size_t bytes_transferred // Number of bytes copied into the 1187 * // buffers. If an error occurred, 1188 * // this will be the number of 1189 * // bytes successfully transferred 1190 * // prior to the error. 1191 * ); @endcode 1192 * Regardless of whether the asynchronous operation completes immediately or 1193 * not, the handler will not be invoked from within this function. On 1194 * immediate completion, invocation of the handler will be performed in a 1195 * manner equivalent to using boost::asio::post(). 1196 * 1197 * @note This overload is equivalent to calling: 1198 * @code boost::asio::async_read( 1199 * s, buffers, 1200 * boost::asio::transfer_all(), 1201 * handler); @endcode 1202 */ 1203 template <typename AsyncReadStream, typename DynamicBuffer_v2, 1204 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 1205 std::size_t)) ReadHandler 1206 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 1207 typename AsyncReadStream::executor_type)> 1208 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, 1209 void (boost::system::error_code, std::size_t)) 1210 async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, 1211 BOOST_ASIO_MOVE_ARG(ReadHandler) handler 1212 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 1213 typename AsyncReadStream::executor_type), 1214 typename constraint< 1215 is_dynamic_buffer_v2<DynamicBuffer_v2>::value 1216 >::type = 0); 1217 1218 /// Start an asynchronous operation to read a certain amount of data from a 1219 /// stream. 1220 /** 1221 * This function is used to asynchronously read a certain number of bytes of 1222 * data from a stream. The function call always returns immediately. The 1223 * asynchronous operation will continue until one of the following conditions is 1224 * true: 1225 * 1226 * @li The specified dynamic buffer sequence is full (that is, it has reached 1227 * maximum size). 1228 * 1229 * @li The completion_condition function object returns 0. 1230 * 1231 * This operation is implemented in terms of zero or more calls to the stream's 1232 * async_read_some function, and is known as a <em>composed operation</em>. The 1233 * program must ensure that the stream performs no other read operations (such 1234 * as async_read, the stream's async_read_some function, or any other composed 1235 * operations that perform reads) until this operation completes. 1236 * 1237 * @param s The stream from which the data is to be read. The type must support 1238 * the AsyncReadStream concept. 1239 * 1240 * @param buffers The dynamic buffer sequence into which the data will be read. 1241 * Although the buffers object may be copied as necessary, ownership of the 1242 * underlying memory blocks is retained by the caller, which must guarantee 1243 * that they remain valid until the handler is called. 1244 * 1245 * @param completion_condition The function object to be called to determine 1246 * whether the read operation is complete. The signature of the function object 1247 * must be: 1248 * @code std::size_t completion_condition( 1249 * // Result of latest async_read_some operation. 1250 * const boost::system::error_code& error, 1251 * 1252 * // Number of bytes transferred so far. 1253 * std::size_t bytes_transferred 1254 * ); @endcode 1255 * A return value of 0 indicates that the read operation is complete. A non-zero 1256 * return value indicates the maximum number of bytes to be read on the next 1257 * call to the stream's async_read_some function. 1258 * 1259 * @param handler The handler to be called when the read operation completes. 1260 * Copies will be made of the handler as required. The function signature of the 1261 * handler must be: 1262 * @code void handler( 1263 * const boost::system::error_code& error, // Result of operation. 1264 * 1265 * std::size_t bytes_transferred // Number of bytes copied into the 1266 * // buffers. If an error occurred, 1267 * // this will be the number of 1268 * // bytes successfully transferred 1269 * // prior to the error. 1270 * ); @endcode 1271 * Regardless of whether the asynchronous operation completes immediately or 1272 * not, the handler will not be invoked from within this function. On 1273 * immediate completion, invocation of the handler will be performed in a 1274 * manner equivalent to using boost::asio::post(). 1275 */ 1276 template <typename AsyncReadStream, 1277 typename DynamicBuffer_v2, typename CompletionCondition, 1278 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 1279 std::size_t)) ReadHandler 1280 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 1281 typename AsyncReadStream::executor_type)> 1282 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, 1283 void (boost::system::error_code, std::size_t)) 1284 async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, 1285 CompletionCondition completion_condition, 1286 BOOST_ASIO_MOVE_ARG(ReadHandler) handler 1287 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 1288 typename AsyncReadStream::executor_type), 1289 typename constraint< 1290 is_dynamic_buffer_v2<DynamicBuffer_v2>::value 1291 >::type = 0); 1292 1293 /*@}*/ 1294 1295 } // namespace asio 1296 } // namespace boost 1297 1298 #include <boost/asio/detail/pop_options.hpp> 1299 1300 #include <boost/asio/impl/read.hpp> 1301 1302 #endif // BOOST_ASIO_READ_HPP 1303