boost/asio/read_at.hpp

   1 //
   2 // read_at.hpp
   3 // ~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2017 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_AT_HPP
  12 #define BOOST_ASIO_READ_AT_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/basic_streambuf_fwd.hpp>
  22 #include <boost/asio/detail/cstdint.hpp>
  23 #include <boost/asio/error.hpp>
  24
  25 #include <boost/asio/detail/push_options.hpp>
  26
  27 namespace boost {
  28 namespace asio {
  29
  30 /**
  31  * @defgroup read_at boost::asio::read_at
  32  *
  33  * @brief Attempt to read a certain amount of data at the specified offset
  34  * before returning.
  35  */
  36 /*@{*/
  37
  38 /// Attempt to read a certain amount of data at the specified offset before
  39 /// returning.
  40 /**
  41  * This function is used to read a certain number of bytes of data from a
  42  * random access device at the specified offset. The call will block until one
  43  * of the following conditions is true:
  44  *
  45  * @li The supplied buffers are full. That is, the bytes transferred is equal to
  46  * the sum of the buffer sizes.
  47  *
  48  * @li An error occurred.
  49  *
  50  * This operation is implemented in terms of zero or more calls to the device's
  51  * read_some_at function.
  52  *
  53  * @param d The device from which the data is to be read. The type must support
  54  * the SyncRandomAccessReadDevice concept.
  55  *
  56  * @param offset The offset at which the data will be read.
  57  *
  58  * @param buffers One or more buffers into which the data will be read. The sum
  59  * of the buffer sizes indicates the maximum number of bytes to read from the
  60  * device.
  61  *
  62  * @returns The number of bytes transferred.
  63  *
  64  * @throws boost::system::system_error Thrown on failure.
  65  *
  66  * @par Example
  67  * To read into a single data buffer use the @ref buffer function as follows:
  68  * @code boost::asio::read_at(d, 42, boost::asio::buffer(data, size)); @endcode
  69  * See the @ref buffer documentation for information on reading into multiple
  70  * buffers in one go, and how to use it with arrays, boost::array or
  71  * std::vector.
  72  *
  73  * @note This overload is equivalent to calling:
  74  * @code boost::asio::read_at(
  75  *     d, 42, buffers,
  76  *     boost::asio::transfer_all()); @endcode
  77  */
  78 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence>
  79 std::size_t read_at(SyncRandomAccessReadDevice& d,
  80     uint64_t offset, const MutableBufferSequence& buffers);
  81
  82 /// Attempt to read a certain amount of data at the specified offset before
  83 /// returning.
  84 /**
  85  * This function is used to read a certain number of bytes of data from a
  86  * random access device at the specified offset. The call will block until one
  87  * of the following conditions is true:
  88  *
  89  * @li The supplied buffers are full. That is, the bytes transferred is equal to
  90  * the sum of the buffer sizes.
  91  *
  92  * @li An error occurred.
  93  *
  94  * This operation is implemented in terms of zero or more calls to the device's
  95  * read_some_at function.
  96  *
  97  * @param d The device from which the data is to be read. The type must support
  98  * the SyncRandomAccessReadDevice concept.
  99  *
 100  * @param offset The offset at which the data will be read.
 101  *
 102  * @param buffers One or more buffers into which the data will be read. The sum
 103  * of the buffer sizes indicates the maximum number of bytes to read from the
 104  * device.
 105  *
 106  * @param ec Set to indicate what error occurred, if any.
 107  *
 108  * @returns The number of bytes transferred.
 109  *
 110  * @par Example
 111  * To read into a single data buffer use the @ref buffer function as follows:
 112  * @code boost::asio::read_at(d, 42,
 113  *     boost::asio::buffer(data, size), ec); @endcode
 114  * See the @ref buffer documentation for information on reading into multiple
 115  * buffers in one go, and how to use it with arrays, boost::array or
 116  * std::vector.
 117  *
 118  * @note This overload is equivalent to calling:
 119  * @code boost::asio::read_at(
 120  *     d, 42, buffers,
 121  *     boost::asio::transfer_all(), ec); @endcode
 122  */
 123 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence>
 124 std::size_t read_at(SyncRandomAccessReadDevice& d,
 125     uint64_t offset, const MutableBufferSequence& buffers,
 126     boost::system::error_code& ec);
 127
 128 /// Attempt to read a certain amount of data at the specified offset before
 129 /// returning.
 130 /**
 131  * This function is used to read a certain number of bytes of data from a
 132  * random access device at the specified offset. The call will block until one
 133  * of the following conditions is true:
 134  *
 135  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 136  * the sum of the buffer sizes.
 137  *
 138  * @li The completion_condition function object returns 0.
 139  *
 140  * This operation is implemented in terms of zero or more calls to the device's
 141  * read_some_at function.
 142  *
 143  * @param d The device from which the data is to be read. The type must support
 144  * the SyncRandomAccessReadDevice concept.
 145  *
 146  * @param offset The offset at which the data will be read.
 147  *
 148  * @param buffers One or more buffers into which the data will be read. The sum
 149  * of the buffer sizes indicates the maximum number of bytes to read from the
 150  * device.
 151  *
 152  * @param completion_condition The function object to be called to determine
 153  * whether the read operation is complete. The signature of the function object
 154  * must be:
 155  * @code std::size_t completion_condition(
 156  *   // Result of latest read_some_at operation.
 157  *   const boost::system::error_code& error,
 158  *
 159  *   // Number of bytes transferred so far.
 160  *   std::size_t bytes_transferred
 161  * ); @endcode
 162  * A return value of 0 indicates that the read operation is complete. A non-zero
 163  * return value indicates the maximum number of bytes to be read on the next
 164  * call to the device's read_some_at function.
 165  *
 166  * @returns The number of bytes transferred.
 167  *
 168  * @throws boost::system::system_error Thrown on failure.
 169  *
 170  * @par Example
 171  * To read into a single data buffer use the @ref buffer function as follows:
 172  * @code boost::asio::read_at(d, 42, boost::asio::buffer(data, size),
 173  *     boost::asio::transfer_at_least(32)); @endcode
 174  * See the @ref buffer documentation for information on reading into multiple
 175  * buffers in one go, and how to use it with arrays, boost::array or
 176  * std::vector.
 177  */
 178 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence,
 179     typename CompletionCondition>
 180 std::size_t read_at(SyncRandomAccessReadDevice& d,
 181     uint64_t offset, const MutableBufferSequence& buffers,
 182     CompletionCondition completion_condition);
 183
 184 /// Attempt to read a certain amount of data at the specified offset before
 185 /// returning.
 186 /**
 187  * This function is used to read a certain number of bytes of data from a
 188  * random access device at the specified offset. The call will block until one
 189  * of the following conditions is true:
 190  *
 191  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 192  * the sum of the buffer sizes.
 193  *
 194  * @li The completion_condition function object returns 0.
 195  *
 196  * This operation is implemented in terms of zero or more calls to the device's
 197  * read_some_at function.
 198  *
 199  * @param d The device from which the data is to be read. The type must support
 200  * the SyncRandomAccessReadDevice concept.
 201  *
 202  * @param offset The offset at which the data will be read.
 203  *
 204  * @param buffers One or more buffers into which the data will be read. The sum
 205  * of the buffer sizes indicates the maximum number of bytes to read from the
 206  * device.
 207  *
 208  * @param completion_condition The function object to be called to determine
 209  * whether the read operation is complete. The signature of the function object
 210  * must be:
 211  * @code std::size_t completion_condition(
 212  *   // Result of latest read_some_at operation.
 213  *   const boost::system::error_code& error,
 214  *
 215  *   // Number of bytes transferred so far.
 216  *   std::size_t bytes_transferred
 217  * ); @endcode
 218  * A return value of 0 indicates that the read operation is complete. A non-zero
 219  * return value indicates the maximum number of bytes to be read on the next
 220  * call to the device's read_some_at function.
 221  *
 222  * @param ec Set to indicate what error occurred, if any.
 223  *
 224  * @returns The number of bytes read. If an error occurs, returns the total
 225  * number of bytes successfully transferred prior to the error.
 226  */
 227 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence,
 228     typename CompletionCondition>
 229 std::size_t read_at(SyncRandomAccessReadDevice& d,
 230     uint64_t offset, const MutableBufferSequence& buffers,
 231     CompletionCondition completion_condition, boost::system::error_code& ec);
 232
 233 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 234
 235 /// Attempt to read a certain amount of data at the specified offset before
 236 /// returning.
 237 /**
 238  * This function is used to read a certain number of bytes of data from a
 239  * random access device at the specified offset. The call will block until one
 240  * of the following conditions is true:
 241  *
 242  * @li An error occurred.
 243  *
 244  * This operation is implemented in terms of zero or more calls to the device's
 245  * read_some_at function.
 246  *
 247  * @param d The device from which the data is to be read. The type must support
 248  * the SyncRandomAccessReadDevice concept.
 249  *
 250  * @param offset The offset at which the data will be read.
 251  *
 252  * @param b The basic_streambuf object into which the data will be read.
 253  *
 254  * @returns The number of bytes transferred.
 255  *
 256  * @throws boost::system::system_error Thrown on failure.
 257  *
 258  * @note This overload is equivalent to calling:
 259  * @code boost::asio::read_at(
 260  *     d, 42, b,
 261  *     boost::asio::transfer_all()); @endcode
 262  */
 263 template <typename SyncRandomAccessReadDevice, typename Allocator>
 264 std::size_t read_at(SyncRandomAccessReadDevice& d,
 265     uint64_t offset, basic_streambuf<Allocator>& b);
 266
 267 /// Attempt to read a certain amount of data at the specified offset before
 268 /// returning.
 269 /**
 270  * This function is used to read a certain number of bytes of data from a
 271  * random access device at the specified offset. The call will block until one
 272  * of the following conditions is true:
 273  *
 274  * @li An error occurred.
 275  *
 276  * This operation is implemented in terms of zero or more calls to the device's
 277  * read_some_at function.
 278  *
 279  * @param d The device from which the data is to be read. The type must support
 280  * the SyncRandomAccessReadDevice concept.
 281  *
 282  * @param offset The offset at which the data will be read.
 283  *
 284  * @param b The basic_streambuf object into which the data will be read.
 285  *
 286  * @param ec Set to indicate what error occurred, if any.
 287  *
 288  * @returns The number of bytes transferred.
 289  *
 290  * @note This overload is equivalent to calling:
 291  * @code boost::asio::read_at(
 292  *     d, 42, b,
 293  *     boost::asio::transfer_all(), ec); @endcode
 294  */
 295 template <typename SyncRandomAccessReadDevice, typename Allocator>
 296 std::size_t read_at(SyncRandomAccessReadDevice& d,
 297     uint64_t offset, basic_streambuf<Allocator>& b,
 298     boost::system::error_code& ec);
 299
 300 /// Attempt to read a certain amount of data at the specified offset before
 301 /// returning.
 302 /**
 303  * This function is used to read a certain number of bytes of data from a
 304  * random access device at the specified offset. The call will block until one
 305  * of the following conditions is true:
 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 device's
 310  * read_some_at function.
 311  *
 312  * @param d The device from which the data is to be read. The type must support
 313  * the SyncRandomAccessReadDevice concept.
 314  *
 315  * @param offset The offset at which the data will be read.
 316  *
 317  * @param b The basic_streambuf object into which the data will be read.
 318  *
 319  * @param completion_condition The function object to be called to determine
 320  * whether the read operation is complete. The signature of the function object
 321  * must be:
 322  * @code std::size_t completion_condition(
 323  *   // Result of latest read_some_at operation.
 324  *   const boost::system::error_code& error,
 325  *
 326  *   // Number of bytes transferred so far.
 327  *   std::size_t bytes_transferred
 328  * ); @endcode
 329  * A return value of 0 indicates that the read operation is complete. A non-zero
 330  * return value indicates the maximum number of bytes to be read on the next
 331  * call to the device's read_some_at function.
 332  *
 333  * @returns The number of bytes transferred.
 334  *
 335  * @throws boost::system::system_error Thrown on failure.
 336  */
 337 template <typename SyncRandomAccessReadDevice, typename Allocator,
 338     typename CompletionCondition>
 339 std::size_t read_at(SyncRandomAccessReadDevice& d,
 340     uint64_t offset, basic_streambuf<Allocator>& b,
 341     CompletionCondition completion_condition);
 342
 343 /// Attempt to read a certain amount of data at the specified offset before
 344 /// returning.
 345 /**
 346  * This function is used to read a certain number of bytes of data from a
 347  * random access device at the specified offset. The call will block until one
 348  * of the following conditions is true:
 349  *
 350  * @li The completion_condition function object returns 0.
 351  *
 352  * This operation is implemented in terms of zero or more calls to the device's
 353  * read_some_at function.
 354  *
 355  * @param d The device from which the data is to be read. The type must support
 356  * the SyncRandomAccessReadDevice concept.
 357  *
 358  * @param offset The offset at which the data will be read.
 359  *
 360  * @param b The basic_streambuf object into which the data will be read.
 361  *
 362  * @param completion_condition The function object to be called to determine
 363  * whether the read operation is complete. The signature of the function object
 364  * must be:
 365  * @code std::size_t completion_condition(
 366  *   // Result of latest read_some_at operation.
 367  *   const boost::system::error_code& error,
 368  *
 369  *   // Number of bytes transferred so far.
 370  *   std::size_t bytes_transferred
 371  * ); @endcode
 372  * A return value of 0 indicates that the read operation is complete. A non-zero
 373  * return value indicates the maximum number of bytes to be read on the next
 374  * call to the device's read_some_at function.
 375  *
 376  * @param ec Set to indicate what error occurred, if any.
 377  *
 378  * @returns The number of bytes read. If an error occurs, returns the total
 379  * number of bytes successfully transferred prior to the error.
 380  */
 381 template <typename SyncRandomAccessReadDevice, typename Allocator,
 382     typename CompletionCondition>
 383 std::size_t read_at(SyncRandomAccessReadDevice& d,
 384     uint64_t offset, basic_streambuf<Allocator>& b,
 385     CompletionCondition completion_condition, boost::system::error_code& ec);
 386
 387 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 388
 389 /*@}*/
 390 /**
 391  * @defgroup async_read_at boost::asio::async_read_at
 392  *
 393  * @brief Start an asynchronous operation to read a certain amount of data at
 394  * the specified offset.
 395  */
 396 /*@{*/
 397
 398 /// Start an asynchronous operation to read a certain amount of data at the
 399 /// specified offset.
 400 /**
 401  * This function is used to asynchronously read a certain number of bytes of
 402  * data from a random access device at the specified offset. The function call
 403  * always returns immediately. The asynchronous operation will continue until
 404  * one of the following conditions is true:
 405  *
 406  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 407  * the sum of the buffer sizes.
 408  *
 409  * @li An error occurred.
 410  *
 411  * This operation is implemented in terms of zero or more calls to the device's
 412  * async_read_some_at function.
 413  *
 414  * @param d The device from which the data is to be read. The type must support
 415  * the AsyncRandomAccessReadDevice concept.
 416  *
 417  * @param offset The offset at which the data will be read.
 418  *
 419  * @param buffers One or more buffers into which the data will be read. The sum
 420  * of the buffer sizes indicates the maximum number of bytes to read from the
 421  * device. Although the buffers object may be copied as necessary, ownership of
 422  * the underlying memory blocks is retained by the caller, which must guarantee
 423  * that they remain valid until the handler is called.
 424  *
 425  * @param handler The handler to be called when the read operation completes.
 426  * Copies will be made of the handler as required. The function signature of the
 427  * handler must be:
 428  * @code void handler(
 429  *   // Result of operation.
 430  *   const boost::system::error_code& error,
 431  *
 432  *   // Number of bytes copied into the buffers. If an error
 433  *   // occurred, this will be the number of bytes successfully
 434  *   // transferred prior to the error.
 435  *   std::size_t bytes_transferred
 436  * ); @endcode
 437  * Regardless of whether the asynchronous operation completes immediately or
 438  * not, the handler will not be invoked from within this function. Invocation of
 439  * the handler will be performed in a manner equivalent to using
 440  * boost::asio::io_service::post().
 441  *
 442  * @par Example
 443  * To read into a single data buffer use the @ref buffer function as follows:
 444  * @code
 445  * boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), handler);
 446  * @endcode
 447  * See the @ref buffer documentation for information on reading into multiple
 448  * buffers in one go, and how to use it with arrays, boost::array or
 449  * std::vector.
 450  *
 451  * @note This overload is equivalent to calling:
 452  * @code boost::asio::async_read_at(
 453  *     d, 42, buffers,
 454  *     boost::asio::transfer_all(),
 455  *     handler); @endcode
 456  */
 457 template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
 458     typename ReadHandler>
 459 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 460     void (boost::system::error_code, std::size_t))
 461 async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset,
 462     const MutableBufferSequence& buffers,
 463     BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
 464
 465 /// Start an asynchronous operation to read a certain amount of data at the
 466 /// specified offset.
 467 /**
 468  * This function is used to asynchronously read a certain number of bytes of
 469  * data from a random access device at the specified offset. The function call
 470  * always returns immediately. The asynchronous operation will continue until
 471  * one of the following conditions is true:
 472  *
 473  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 474  * the sum of the buffer sizes.
 475  *
 476  * @li The completion_condition function object returns 0.
 477  *
 478  * @param d The device from which the data is to be read. The type must support
 479  * the AsyncRandomAccessReadDevice concept.
 480  *
 481  * @param offset The offset at which the data will be read.
 482  *
 483  * @param buffers One or more buffers into which the data will be read. The sum
 484  * of the buffer sizes indicates the maximum number of bytes to read from the
 485  * device. Although the buffers object may be copied as necessary, ownership of
 486  * the underlying memory blocks is retained by the caller, which must guarantee
 487  * that they remain valid until the handler is called.
 488  *
 489  * @param completion_condition The function object to be called to determine
 490  * whether the read operation is complete. The signature of the function object
 491  * must be:
 492  * @code std::size_t completion_condition(
 493  *   // Result of latest async_read_some_at operation.
 494  *   const boost::system::error_code& error,
 495  *
 496  *   // Number of bytes transferred so far.
 497  *   std::size_t bytes_transferred
 498  * ); @endcode
 499  * A return value of 0 indicates that the read operation is complete. A non-zero
 500  * return value indicates the maximum number of bytes to be read on the next
 501  * call to the device's async_read_some_at function.
 502  *
 503  * @param handler The handler to be called when the read operation completes.
 504  * Copies will be made of the handler as required. The function signature of the
 505  * handler must be:
 506  * @code void handler(
 507  *   // Result of operation.
 508  *   const boost::system::error_code& error,
 509  *
 510  *   // Number of bytes copied into the buffers. If an error
 511  *   // occurred, this will be the number of bytes successfully
 512  *   // transferred prior to the error.
 513  *   std::size_t bytes_transferred
 514  * ); @endcode
 515  * Regardless of whether the asynchronous operation completes immediately or
 516  * not, the handler will not be invoked from within this function. Invocation of
 517  * the handler will be performed in a manner equivalent to using
 518  * boost::asio::io_service::post().
 519  *
 520  * @par Example
 521  * To read into a single data buffer use the @ref buffer function as follows:
 522  * @code boost::asio::async_read_at(d, 42,
 523  *     boost::asio::buffer(data, size),
 524  *     boost::asio::transfer_at_least(32),
 525  *     handler); @endcode
 526  * See the @ref buffer documentation for information on reading into multiple
 527  * buffers in one go, and how to use it with arrays, boost::array or
 528  * std::vector.
 529  */
 530 template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
 531     typename CompletionCondition, typename ReadHandler>
 532 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 533     void (boost::system::error_code, std::size_t))
 534 async_read_at(AsyncRandomAccessReadDevice& d,
 535     uint64_t offset, const MutableBufferSequence& buffers,
 536     CompletionCondition completion_condition,
 537     BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
 538
 539 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 540
 541 /// Start an asynchronous operation to read a certain amount of data at the
 542 /// specified offset.
 543 /**
 544  * This function is used to asynchronously read a certain number of bytes of
 545  * data from a random access device at the specified offset. The function call
 546  * always returns immediately. The asynchronous operation will continue until
 547  * one of the following conditions is true:
 548  *
 549  * @li An error occurred.
 550  *
 551  * This operation is implemented in terms of zero or more calls to the device's
 552  * async_read_some_at function.
 553  *
 554  * @param d The device from which the data is to be read. The type must support
 555  * the AsyncRandomAccessReadDevice concept.
 556  *
 557  * @param offset The offset at which the data will be read.
 558  *
 559  * @param b A basic_streambuf object into which the data will be read. Ownership
 560  * of the streambuf is retained by the caller, which must guarantee that it
 561  * remains valid until the handler is called.
 562  *
 563  * @param handler The handler to be called when the read operation completes.
 564  * Copies will be made of the handler as required. The function signature of the
 565  * handler must be:
 566  * @code void handler(
 567  *   // Result of operation.
 568  *   const boost::system::error_code& error,
 569  *
 570  *   // Number of bytes copied into the buffers. If an error
 571  *   // occurred, this will be the number of bytes successfully
 572  *   // transferred prior to the error.
 573  *   std::size_t bytes_transferred
 574  * ); @endcode
 575  * Regardless of whether the asynchronous operation completes immediately or
 576  * not, the handler will not be invoked from within this function. Invocation of
 577  * the handler will be performed in a manner equivalent to using
 578  * boost::asio::io_service::post().
 579  *
 580  * @note This overload is equivalent to calling:
 581  * @code boost::asio::async_read_at(
 582  *     d, 42, b,
 583  *     boost::asio::transfer_all(),
 584  *     handler); @endcode
 585  */
 586 template <typename AsyncRandomAccessReadDevice, typename Allocator,
 587     typename ReadHandler>
 588 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 589     void (boost::system::error_code, std::size_t))
 590 async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset,
 591     basic_streambuf<Allocator>& b, BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
 592
 593 /// Start an asynchronous operation to read a certain amount of data at the
 594 /// specified offset.
 595 /**
 596  * This function is used to asynchronously read a certain number of bytes of
 597  * data from a random access device at the specified offset. The function call
 598  * always returns immediately. The asynchronous operation will continue until
 599  * one of the following conditions is true:
 600  *
 601  * @li The completion_condition function object returns 0.
 602  *
 603  * This operation is implemented in terms of zero or more calls to the device's
 604  * async_read_some_at function.
 605  *
 606  * @param d The device from which the data is to be read. The type must support
 607  * the AsyncRandomAccessReadDevice concept.
 608  *
 609  * @param offset The offset at which the data will be read.
 610  *
 611  * @param b A basic_streambuf object into which the data will be read. Ownership
 612  * of the streambuf is retained by the caller, which must guarantee that it
 613  * remains valid until the handler is called.
 614  *
 615  * @param completion_condition The function object to be called to determine
 616  * whether the read operation is complete. The signature of the function object
 617  * must be:
 618  * @code std::size_t completion_condition(
 619  *   // Result of latest async_read_some_at operation.
 620  *   const boost::system::error_code& error,
 621  *
 622  *   // Number of bytes transferred so far.
 623  *   std::size_t bytes_transferred
 624  * ); @endcode
 625  * A return value of 0 indicates that the read operation is complete. A non-zero
 626  * return value indicates the maximum number of bytes to be read on the next
 627  * call to the device's async_read_some_at function.
 628  *
 629  * @param handler The handler to be called when the read operation completes.
 630  * Copies will be made of the handler as required. The function signature of the
 631  * handler must be:
 632  * @code void handler(
 633  *   // Result of operation.
 634  *   const boost::system::error_code& error,
 635  *
 636  *   // Number of bytes copied into the buffers. If an error
 637  *   // occurred, this will be the number of bytes successfully
 638  *   // transferred prior to the error.
 639  *   std::size_t bytes_transferred
 640  * ); @endcode
 641  * Regardless of whether the asynchronous operation completes immediately or
 642  * not, the handler will not be invoked from within this function. Invocation of
 643  * the handler will be performed in a manner equivalent to using
 644  * boost::asio::io_service::post().
 645  */
 646 template <typename AsyncRandomAccessReadDevice, typename Allocator,
 647     typename CompletionCondition, typename ReadHandler>
 648 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 649     void (boost::system::error_code, std::size_t))
 650 async_read_at(AsyncRandomAccessReadDevice& d,
 651     uint64_t offset, basic_streambuf<Allocator>& b,
 652     CompletionCondition completion_condition,
 653     BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
 654
 655 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 656
 657 /*@}*/
 658
 659 } // namespace asio
 660 } // namespace boost
 661
 662 #include <boost/asio/detail/pop_options.hpp>
 663
 664 #include <boost/asio/impl/read_at.hpp>
 665
 666 #endif // BOOST_ASIO_READ_AT_HPP