5
// Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11
#ifndef ASIO_WRITE_AT_HPP
12
#define ASIO_WRITE_AT_HPP
14
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
16
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18
#include "asio/detail/push_options.hpp"
20
#include "asio/detail/push_options.hpp"
22
#include <boost/config.hpp>
23
#include <boost/cstdint.hpp>
24
#include "asio/detail/pop_options.hpp"
26
#include "asio/basic_streambuf.hpp"
27
#include "asio/error.hpp"
32
* @defgroup write_at asio::write_at
34
* @brief Write a certain amount of data at a specified offset before returning.
38
/// Write all of the supplied data at the specified offset before returning.
40
* This function is used to write a certain number of bytes of data to a random
41
* access device at a specified offset. The call will block until one of the
42
* following conditions is true:
44
* @li All of the data in the supplied buffers has been written. That is, the
45
* bytes transferred is equal to the sum of the buffer sizes.
47
* @li An error occurred.
49
* This operation is implemented in terms of one or more calls to the device's
50
* write_some_at function.
52
* @param d The device to which the data is to be written. The type must support
53
* the SyncRandomAccessWriteDevice concept.
55
* @param offset The offset at which the data will be written.
57
* @param buffers One or more buffers containing the data to be written. The sum
58
* of the buffer sizes indicates the maximum number of bytes to write to the
61
* @returns The number of bytes transferred.
63
* @throws asio::system_error Thrown on failure.
66
* To write a single data buffer use the @ref buffer function as follows:
67
* @code asio::write_at(d, 42, asio::buffer(data, size)); @endcode
68
* See the @ref buffer documentation for information on writing multiple
69
* buffers in one go, and how to use it with arrays, boost::array or
72
* @note This overload is equivalent to calling:
73
* @code asio::write_at(
75
* asio::transfer_all()); @endcode
77
template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence>
78
std::size_t write_at(SyncRandomAccessWriteDevice& d,
79
boost::uint64_t offset, const ConstBufferSequence& buffers);
81
/// Write a certain amount of data at a specified offset before returning.
83
* This function is used to write a certain number of bytes of data to a random
84
* access device at a specified offset. The call will block until one of the
85
* following conditions is true:
87
* @li All of the data in the supplied buffers has been written. That is, the
88
* bytes transferred is equal to the sum of the buffer sizes.
90
* @li The completion_condition function object returns true.
92
* This operation is implemented in terms of one or more calls to the device's
93
* write_some_at function.
95
* @param d The device to which the data is to be written. The type must support
96
* the SyncRandomAccessWriteDevice concept.
98
* @param offset The offset at which the data will be written.
100
* @param buffers One or more buffers containing the data to be written. The sum
101
* of the buffer sizes indicates the maximum number of bytes to write to the
104
* @param completion_condition The function object to be called to determine
105
* whether the write operation is complete. The signature of the function object
107
* @code bool completion_condition(
108
* // Result of latest write_some_at operation.
109
* const asio::error_code& error,
111
* // Number of bytes transferred so far.
112
* std::size_t bytes_transferred
114
* A return value of true indicates that the write operation is complete. False
115
* indicates that further calls to the device's write_some_at function are
118
* @returns The number of bytes transferred.
120
* @throws asio::system_error Thrown on failure.
123
* To write a single data buffer use the @ref buffer function as follows:
124
* @code asio::write_at(d, 42, asio::buffer(data, size),
125
* asio::transfer_at_least(32)); @endcode
126
* See the @ref buffer documentation for information on writing multiple
127
* buffers in one go, and how to use it with arrays, boost::array or
130
template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence,
131
typename CompletionCondition>
132
std::size_t write_at(SyncRandomAccessWriteDevice& d,
133
boost::uint64_t offset, const ConstBufferSequence& buffers,
134
CompletionCondition completion_condition);
136
/// Write a certain amount of data at a specified offset before returning.
138
* This function is used to write a certain number of bytes of data to a random
139
* access device at a specified offset. The call will block until one of the
140
* following conditions is true:
142
* @li All of the data in the supplied buffers has been written. That is, the
143
* bytes transferred is equal to the sum of the buffer sizes.
145
* @li The completion_condition function object returns true.
147
* This operation is implemented in terms of one or more calls to the device's
148
* write_some_at function.
150
* @param d The device to which the data is to be written. The type must support
151
* the SyncRandomAccessWriteDevice concept.
153
* @param offset The offset at which the data will be written.
155
* @param buffers One or more buffers containing the data to be written. The sum
156
* of the buffer sizes indicates the maximum number of bytes to write to the
159
* @param completion_condition The function object to be called to determine
160
* whether the write operation is complete. The signature of the function object
162
* @code bool completion_condition(
163
* // Result of latest write_some_at operation.
164
* const asio::error_code& error,
166
* // Number of bytes transferred so far.
167
* std::size_t bytes_transferred
169
* A return value of true indicates that the write operation is complete. False
170
* indicates that further calls to the device's write_some_at function are
173
* @param ec Set to indicate what error occurred, if any.
175
* @returns The number of bytes written. If an error occurs, returns the total
176
* number of bytes successfully transferred prior to the error.
178
template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence,
179
typename CompletionCondition>
180
std::size_t write_at(SyncRandomAccessWriteDevice& d,
181
boost::uint64_t offset, const ConstBufferSequence& buffers,
182
CompletionCondition completion_condition, asio::error_code& ec);
184
/// Write all of the supplied data at the specified offset before returning.
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:
190
* @li All of the data in the supplied basic_streambuf has been written.
192
* @li An error occurred.
194
* This operation is implemented in terms of one or more calls to the device's
195
* write_some_at function.
197
* @param d The device to which the data is to be written. The type must support
198
* the SyncRandomAccessWriteDevice concept.
200
* @param offset The offset at which the data will be written.
202
* @param b The basic_streambuf object from which data will be written.
204
* @returns The number of bytes transferred.
206
* @throws asio::system_error Thrown on failure.
208
* @note This overload is equivalent to calling:
209
* @code asio::write_at(
211
* asio::transfer_all()); @endcode
213
template <typename SyncRandomAccessWriteDevice, typename Allocator>
214
std::size_t write_at(SyncRandomAccessWriteDevice& d,
215
boost::uint64_t offset, basic_streambuf<Allocator>& b);
217
/// Write a certain amount of data at a specified offset before returning.
219
* This function is used to write a certain number of bytes of data to a random
220
* access device at a specified offset. The call will block until one of the
221
* following conditions is true:
223
* @li All of the data in the supplied basic_streambuf has been written.
225
* @li The completion_condition function object returns true.
227
* This operation is implemented in terms of one or more calls to the device's
228
* write_some_at function.
230
* @param d The device to which the data is to be written. The type must support
231
* the SyncRandomAccessWriteDevice concept.
233
* @param offset The offset at which the data will be written.
235
* @param b The basic_streambuf object from which data will be written.
237
* @param completion_condition The function object to be called to determine
238
* whether the write operation is complete. The signature of the function object
240
* @code bool completion_condition(
241
* // Result of latest write_some_at operation.
242
* const asio::error_code& error,
244
* // Number of bytes transferred so far.
245
* std::size_t bytes_transferred
247
* A return value of true indicates that the write operation is complete. False
248
* indicates that further calls to the device's write_some_at function are
251
* @returns The number of bytes transferred.
253
* @throws asio::system_error Thrown on failure.
255
template <typename SyncRandomAccessWriteDevice, typename Allocator,
256
typename CompletionCondition>
257
std::size_t write_at(SyncRandomAccessWriteDevice& d, boost::uint64_t offset,
258
basic_streambuf<Allocator>& b, CompletionCondition completion_condition);
260
/// Write a certain amount of data at a specified offset before returning.
262
* This function is used to write a certain number of bytes of data to a random
263
* access device at a specified offset. The call will block until one of the
264
* following conditions is true:
266
* @li All of the data in the supplied basic_streambuf has been written.
268
* @li The completion_condition function object returns true.
270
* This operation is implemented in terms of one or more calls to the device's
271
* write_some_at function.
273
* @param d The device to which the data is to be written. The type must support
274
* the SyncRandomAccessWriteDevice concept.
276
* @param offset The offset at which the data will be written.
278
* @param b The basic_streambuf object from which data will be written.
280
* @param completion_condition The function object to be called to determine
281
* whether the write operation is complete. The signature of the function object
283
* @code bool completion_condition(
284
* // Result of latest write_some_at operation.
285
* const asio::error_code& error,
287
* // Number of bytes transferred so far.
288
* std::size_t bytes_transferred
290
* A return value of true indicates that the write operation is complete. False
291
* indicates that further calls to the device's write_some_at function are
294
* @param ec Set to indicate what error occurred, if any.
296
* @returns The number of bytes written. If an error occurs, returns the total
297
* number of bytes successfully transferred prior to the error.
299
template <typename SyncRandomAccessWriteDevice, typename Allocator,
300
typename CompletionCondition>
301
std::size_t write_at(SyncRandomAccessWriteDevice& d, boost::uint64_t offset,
302
basic_streambuf<Allocator>& b, CompletionCondition completion_condition,
303
asio::error_code& ec);
307
* @defgroup async_write_at asio::async_write_at
309
* @brief Start an asynchronous operation to write a certain amount of data at
310
* the specified offset.
314
/// Start an asynchronous operation to write all of the supplied data at the
315
/// specified offset.
317
* This function is used to asynchronously write a certain number of bytes of
318
* data to a random access device at a specified offset. The function call
319
* always returns immediately. The asynchronous operation will continue until
320
* one of the following conditions is true:
322
* @li All of the data in the supplied buffers has been written. That is, the
323
* bytes transferred is equal to the sum of the buffer sizes.
325
* @li An error occurred.
327
* This operation is implemented in terms of one or more calls to the device's
328
* async_write_some_at function.
330
* @param d The device to which the data is to be written. The type must support
331
* the AsyncRandomAccessWriteDevice concept.
333
* @param offset The offset at which the data will be written.
335
* @param buffers One or more buffers containing the data to be written.
336
* Although the buffers object may be copied as necessary, ownership of the
337
* underlying memory blocks is retained by the caller, which must guarantee
338
* that they remain valid until the handler is called.
340
* @param handler The handler to be called when the write operation completes.
341
* Copies will be made of the handler as required. The function signature of
342
* the handler must be:
343
* @code void handler(
344
* // Result of operation.
345
* const asio::error_code& error,
347
* // Number of bytes written from the buffers. If an error
348
* // occurred, this will be less than the sum of the buffer sizes.
349
* std::size_t bytes_transferred
351
* Regardless of whether the asynchronous operation completes immediately or
352
* not, the handler will not be invoked from within this function. Invocation of
353
* the handler will be performed in a manner equivalent to using
354
* asio::io_service::post().
357
* To write a single data buffer use the @ref buffer function as follows:
359
* asio::async_write_at(d, 42, asio::buffer(data, size), handler);
361
* See the @ref buffer documentation for information on writing multiple
362
* buffers in one go, and how to use it with arrays, boost::array or
365
template <typename AsyncRandomAccessWriteDevice, typename ConstBufferSequence,
366
typename WriteHandler>
367
void async_write_at(AsyncRandomAccessWriteDevice& d, boost::uint64_t offset,
368
const ConstBufferSequence& buffers, WriteHandler handler);
370
/// Start an asynchronous operation to write a certain amount of data at the
371
/// specified offset.
373
* This function is used to asynchronously write a certain number of bytes of
374
* data to a random access device at a specified offset. The function call
375
* always returns immediately. The asynchronous operation will continue until
376
* one of the following conditions is true:
378
* @li All of the data in the supplied buffers has been written. That is, the
379
* bytes transferred is equal to the sum of the buffer sizes.
381
* @li The completion_condition function object returns true.
383
* This operation is implemented in terms of one or more calls to the device's
384
* async_write_some_at function.
386
* @param d The device to which the data is to be written. The type must support
387
* the AsyncRandomAccessWriteDevice concept.
389
* @param offset The offset at which the data will be written.
391
* @param buffers One or more buffers containing the data to be written.
392
* Although the buffers object may be copied as necessary, ownership of the
393
* underlying memory blocks is retained by the caller, which must guarantee
394
* that they remain valid until the handler is called.
396
* @param completion_condition The function object to be called to determine
397
* whether the write operation is complete. The signature of the function object
399
* @code bool completion_condition(
400
* // Result of latest write_some_at operation.
401
* const asio::error_code& error,
403
* // Number of bytes transferred so far.
404
* std::size_t bytes_transferred
406
* A return value of true indicates that the write operation is complete. False
407
* indicates that further calls to the device's async_write_some_at function are
410
* @param handler The handler to be called when the write operation completes.
411
* Copies will be made of the handler as required. The function signature of the
413
* @code void handler(
414
* // Result of operation.
415
* const asio::error_code& error,
417
* // Number of bytes written from the buffers. If an error
418
* // occurred, this will be less than the sum of the buffer sizes.
419
* std::size_t bytes_transferred
421
* Regardless of whether the asynchronous operation completes immediately or
422
* not, the handler will not be invoked from within this function. Invocation of
423
* the handler will be performed in a manner equivalent to using
424
* asio::io_service::post().
427
* To write a single data buffer use the @ref buffer function as follows:
428
* @code asio::async_write_at(d, 42,
429
* asio::buffer(data, size),
430
* asio::transfer_at_least(32),
432
* See the @ref buffer documentation for information on writing multiple
433
* buffers in one go, and how to use it with arrays, boost::array or
436
template <typename AsyncRandomAccessWriteDevice, typename ConstBufferSequence,
437
typename CompletionCondition, typename WriteHandler>
438
void async_write_at(AsyncRandomAccessWriteDevice& d,
439
boost::uint64_t offset, const ConstBufferSequence& buffers,
440
CompletionCondition completion_condition, WriteHandler handler);
442
/// Start an asynchronous operation to write all of the supplied data at the
443
/// specified offset.
445
* This function is used to asynchronously write a certain number of bytes of
446
* data to a random access device at a specified offset. The function call
447
* always returns immediately. The asynchronous operation will continue until
448
* one of the following conditions is true:
450
* @li All of the data in the supplied basic_streambuf has been written.
452
* @li An error occurred.
454
* This operation is implemented in terms of one or more calls to the device's
455
* async_write_some_at function.
457
* @param d The device to which the data is to be written. The type must support
458
* the AsyncRandomAccessWriteDevice concept.
460
* @param offset The offset at which the data will be written.
462
* @param b A basic_streambuf object from which data will be written. Ownership
463
* of the streambuf is retained by the caller, which must guarantee that it
464
* remains valid until the handler is called.
466
* @param handler The handler to be called when the write operation completes.
467
* Copies will be made of the handler as required. The function signature of the
469
* @code void handler(
470
* // Result of operation.
471
* const asio::error_code& error,
473
* // Number of bytes written from the buffers. If an error
474
* // occurred, this will be less than the sum of the buffer sizes.
475
* std::size_t bytes_transferred
477
* Regardless of whether the asynchronous operation completes immediately or
478
* not, the handler will not be invoked from within this function. Invocation of
479
* the handler will be performed in a manner equivalent to using
480
* asio::io_service::post().
482
template <typename AsyncRandomAccessWriteDevice, typename Allocator,
483
typename WriteHandler>
484
void async_write_at(AsyncRandomAccessWriteDevice& d, boost::uint64_t offset,
485
basic_streambuf<Allocator>& b, WriteHandler handler);
487
/// Start an asynchronous operation to write a certain amount of data at the
488
/// specified offset.
490
* This function is used to asynchronously write a certain number of bytes of
491
* data to a random access device at a specified offset. The function call
492
* always returns immediately. The asynchronous operation will continue until
493
* one of the following conditions is true:
495
* @li All of the data in the supplied basic_streambuf has been written.
497
* @li The completion_condition function object returns true.
499
* This operation is implemented in terms of one or more calls to the device's
500
* async_write_some_at function.
502
* @param d The device to which the data is to be written. The type must support
503
* the AsyncRandomAccessWriteDevice concept.
505
* @param offset The offset at which the data will be written.
507
* @param b A basic_streambuf object from which data will be written. Ownership
508
* of the streambuf is retained by the caller, which must guarantee that it
509
* remains valid until the handler is called.
511
* @param completion_condition The function object to be called to determine
512
* whether the write operation is complete. The signature of the function object
514
* @code bool completion_condition(
515
* // Result of latest async_write_some_at operation.
516
* const asio::error_code& error,
518
* // Number of bytes transferred so far.
519
* std::size_t bytes_transferred
521
* A return value of true indicates that the write operation is complete. False
522
* indicates that further calls to the device's async_write_some_at function are
525
* @param handler The handler to be called when the write operation completes.
526
* Copies will be made of the handler as required. The function signature of the
528
* @code void handler(
529
* // Result of operation.
530
* const asio::error_code& error,
532
* // Number of bytes written from the buffers. If an error
533
* // occurred, this will be less than the sum of the buffer sizes.
534
* std::size_t bytes_transferred
536
* Regardless of whether the asynchronous operation completes immediately or
537
* not, the handler will not be invoked from within this function. Invocation of
538
* the handler will be performed in a manner equivalent to using
539
* asio::io_service::post().
541
template <typename AsyncRandomAccessWriteDevice, typename Allocator,
542
typename CompletionCondition, typename WriteHandler>
543
void async_write_at(AsyncRandomAccessWriteDevice& d, boost::uint64_t offset,
544
basic_streambuf<Allocator>& b, CompletionCondition completion_condition,
545
WriteHandler handler);
551
#include "asio/impl/write_at.ipp"
553
#include "asio/detail/pop_options.hpp"
555
#endif // ASIO_WRITE_AT_HPP
added
removed
include/libtorrent/asio/write_at.hpp
