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