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

source code of boost/libs/asio/include/boost/asio/write_at.hpp