read_at.hpp 27 KB

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