boost/asio/read_at.hpp

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