Statistics
| Revision:

root / tmp / org.txm.statsengine.r.core.win32 / res / win32 / library / BH / include / boost / asio / write_at.hpp @ 2486

History | View | Annotate | Download (27.2 kB)

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