write_at.hpp 27 KB

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