/Src/Dependencies/Boost/boost/asio/read_at.hpp

http://hadesmem.googlecode.com/ · C++ Header · 657 lines · 77 code · 28 blank · 552 comment · 1 complexity · abda62625f17f68ee28d408d37106702 MD5 · raw file

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