write_at.hpp 28 KB

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