boost/asio/read.hpp

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