write_at.hpp 27 KB

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