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