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_READ_AT_HPP
12
#define ASIO_READ_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 read_at asio::read_at
34
* @brief Attempt to read a certain amount of data at the specified offset
39
/// Attempt to read a certain amount of data at the specified offset before
42
* This function is used to read a certain number of bytes of data from a
43
* random access device at the specified offset. The call will block until one
44
* of the following conditions is true:
46
* @li The supplied buffers are full. That is, the bytes transferred is equal to
47
* the sum of the buffer sizes.
49
* @li An error occurred.
51
* This operation is implemented in terms of one or more calls to the device's
52
* read_some_at function.
54
* @param d The device from which the data is to be read. The type must support
55
* the SyncRandomAccessReadDevice concept.
57
* @param offset The offset at which the data will be read.
59
* @param buffers One or more buffers into which the data will be read. The sum
60
* of the buffer sizes indicates the maximum number of bytes to read from the
63
* @returns The number of bytes transferred.
65
* @throws asio::system_error Thrown on failure.
68
* To read into a single data buffer use the @ref buffer function as follows:
69
* @code asio::read_at(d, 42, asio::buffer(data, size)); @endcode
70
* See the @ref buffer documentation for information on reading into multiple
71
* buffers in one go, and how to use it with arrays, boost::array or
74
* @note This overload is equivalent to calling:
75
* @code asio::read_at(
77
* asio::transfer_all()); @endcode
79
template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence>
80
std::size_t read_at(SyncRandomAccessReadDevice& d,
81
boost::uint64_t offset, const MutableBufferSequence& buffers);
83
/// Attempt to read a certain amount of data at the specified offset before
86
* This function is used to read a certain number of bytes of data from a
87
* random access device at the specified offset. The call will block until one
88
* of the following conditions is true:
90
* @li The supplied buffers are full. That is, the bytes transferred is equal to
91
* the sum of the buffer sizes.
93
* @li The completion_condition function object returns true.
95
* This operation is implemented in terms of one or more calls to the device's
96
* read_some_at function.
98
* @param d The device from which the data is to be read. The type must support
99
* the SyncRandomAccessReadDevice concept.
101
* @param offset The offset at which the data will be read.
103
* @param buffers One or more buffers into which the data will be read. The sum
104
* of the buffer sizes indicates the maximum number of bytes to read from the
107
* @param completion_condition The function object to be called to determine
108
* whether the read operation is complete. The signature of the function object
110
* @code bool completion_condition(
111
* // Result of latest read_some_at operation.
112
* const asio::error_code& error,
114
* // Number of bytes transferred so far.
115
* std::size_t bytes_transferred
117
* A return value of true indicates that the read operation is complete. False
118
* indicates that further calls to the device's read_some_at function are
121
* @returns The number of bytes transferred.
123
* @throws asio::system_error Thrown on failure.
126
* To read into a single data buffer use the @ref buffer function as follows:
127
* @code asio::read_at(d, 42, asio::buffer(data, size),
128
* asio::transfer_at_least(32)); @endcode
129
* See the @ref buffer documentation for information on reading into multiple
130
* buffers in one go, and how to use it with arrays, boost::array or
133
template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence,
134
typename CompletionCondition>
135
std::size_t read_at(SyncRandomAccessReadDevice& d,
136
boost::uint64_t offset, const MutableBufferSequence& buffers,
137
CompletionCondition completion_condition);
139
/// Attempt to read a certain amount of data at the specified offset before
142
* This function is used to read a certain number of bytes of data from a
143
* random access device at the specified offset. The call will block until one
144
* of the following conditions is true:
146
* @li The supplied buffers are full. That is, the bytes transferred is equal to
147
* the sum of the buffer sizes.
149
* @li The completion_condition function object returns true.
151
* This operation is implemented in terms of one or more calls to the device's
152
* read_some_at function.
154
* @param d The device from which the data is to be read. The type must support
155
* the SyncRandomAccessReadDevice concept.
157
* @param offset The offset at which the data will be read.
159
* @param buffers One or more buffers into which the data will be read. The sum
160
* of the buffer sizes indicates the maximum number of bytes to read from the
163
* @param completion_condition The function object to be called to determine
164
* whether the read operation is complete. The signature of the function object
166
* @code bool completion_condition(
167
* const asio::error_code& error, // Result of latest read_some_at
170
* std::size_t bytes_transferred // Number of bytes transferred
173
* A return value of true indicates that the read operation is complete. False
174
* indicates that further calls to the device's read_some_at function are
177
* @param ec Set to indicate what error occurred, if any.
179
* @returns The number of bytes read. If an error occurs, returns the total
180
* number of bytes successfully transferred prior to the error.
182
template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence,
183
typename CompletionCondition>
184
std::size_t read_at(SyncRandomAccessReadDevice& d,
185
boost::uint64_t offset, const MutableBufferSequence& buffers,
186
CompletionCondition completion_condition, asio::error_code& ec);
188
/// Attempt to read a certain amount of data at the specified offset before
191
* This function is used to read a certain number of bytes of data from a
192
* random access device at the specified offset. The call will block until one
193
* of the following conditions is true:
195
* @li An error occurred.
197
* This operation is implemented in terms of one or more calls to the device's
198
* read_some_at function.
200
* @param d The device from which the data is to be read. The type must support
201
* the SyncRandomAccessReadDevice concept.
203
* @param offset The offset at which the data will be read.
205
* @param b The basic_streambuf object into which the data will be read.
207
* @returns The number of bytes transferred.
209
* @throws asio::system_error Thrown on failure.
211
* @note This overload is equivalent to calling:
212
* @code asio::read_at(
214
* asio::transfer_all()); @endcode
216
template <typename SyncRandomAccessReadDevice, typename Allocator>
217
std::size_t read_at(SyncRandomAccessReadDevice& d,
218
boost::uint64_t offset, basic_streambuf<Allocator>& b);
220
/// Attempt to read a certain amount of data at the specified offset before
223
* This function is used to read a certain number of bytes of data from a
224
* random access device at the specified offset. The call will block until one
225
* of the following conditions is true:
227
* @li The completion_condition function object returns true.
229
* This operation is implemented in terms of one or more calls to the device's
230
* read_some_at function.
232
* @param d The device from which the data is to be read. The type must support
233
* the SyncRandomAccessReadDevice concept.
235
* @param offset The offset at which the data will be read.
237
* @param b The basic_streambuf object into which the data will be read.
239
* @param completion_condition The function object to be called to determine
240
* whether the read operation is complete. The signature of the function object
242
* @code bool completion_condition(
243
* // Result of latest read_some_at operation.
244
* const asio::error_code& error,
246
* // Number of bytes transferred so far.
247
* std::size_t bytes_transferred
249
* A return value of true indicates that the read operation is complete. False
250
* indicates that further calls to the device's read_some_at function are
253
* @returns The number of bytes transferred.
255
* @throws asio::system_error Thrown on failure.
257
template <typename SyncRandomAccessReadDevice, typename Allocator,
258
typename CompletionCondition>
259
std::size_t read_at(SyncRandomAccessReadDevice& d,
260
boost::uint64_t offset, basic_streambuf<Allocator>& b,
261
CompletionCondition completion_condition);
263
/// Attempt to read a certain amount of data at the specified offset before
266
* This function is used to read a certain number of bytes of data from a
267
* random access device at the specified offset. The call will block until one
268
* of the following conditions is true:
270
* @li The completion_condition function object returns true.
272
* This operation is implemented in terms of one or more calls to the device's
273
* read_some_at function.
275
* @param d The device from which the data is to be read. The type must support
276
* the SyncRandomAccessReadDevice concept.
278
* @param offset The offset at which the data will be read.
280
* @param b The basic_streambuf object into which the data will be read.
282
* @param completion_condition The function object to be called to determine
283
* whether the read operation is complete. The signature of the function object
285
* @code bool completion_condition(
286
* // Result of latest read_some_at operation.
287
* const asio::error_code& error,
289
* // Number of bytes transferred so far.
290
* std::size_t bytes_transferred
292
* A return value of true indicates that the read operation is complete. False
293
* indicates that further calls to the device's read_some_at function are
296
* @param ec Set to indicate what error occurred, if any.
298
* @returns The number of bytes read. If an error occurs, returns the total
299
* number of bytes successfully transferred prior to the error.
301
template <typename SyncRandomAccessReadDevice, typename Allocator,
302
typename CompletionCondition>
303
std::size_t read_at(SyncRandomAccessReadDevice& d,
304
boost::uint64_t offset, basic_streambuf<Allocator>& b,
305
CompletionCondition completion_condition, asio::error_code& ec);
309
* @defgroup async_read_at asio::async_read_at
311
* @brief Start an asynchronous operation to read a certain amount of data at
312
* the specified offset.
316
/// Start an asynchronous operation to read a certain amount of data at the
317
/// specified offset.
319
* This function is used to asynchronously read a certain number of bytes of
320
* data from a random access device at the specified offset. The function call
321
* always returns immediately. The asynchronous operation will continue until
322
* one of the following conditions is true:
324
* @li The supplied buffers are full. That is, the bytes transferred is equal to
325
* the sum of the buffer sizes.
327
* @li An error occurred.
329
* This operation is implemented in terms of one or more calls to the device's
330
* async_read_some_at function.
332
* @param d The device from which the data is to be read. The type must support
333
* the AsyncRandomAccessReadDevice concept.
335
* @param offset The offset at which the data will be read.
337
* @param buffers One or more buffers into which the data will be read. The sum
338
* of the buffer sizes indicates the maximum number of bytes to read from the
339
* device. Although the buffers object may be copied as necessary, ownership of
340
* the underlying memory blocks is retained by the caller, which must guarantee
341
* that they remain valid until the handler is called.
343
* @param handler The handler to be called when the read operation completes.
344
* Copies will be made of the handler as required. The function signature of the
346
* @code void handler(
347
* // Result of operation.
348
* const asio::error_code& error,
350
* // Number of bytes copied into the buffers. If an error
351
* // occurred, this will be the number of bytes successfully
352
* // transferred prior to the error.
353
* std::size_t bytes_transferred
355
* Regardless of whether the asynchronous operation completes immediately or
356
* not, the handler will not be invoked from within this function. Invocation of
357
* the handler will be performed in a manner equivalent to using
358
* asio::io_service::post().
361
* To read into a single data buffer use the @ref buffer function as follows:
363
* asio::async_read_at(d, 42, asio::buffer(data, size), handler);
365
* See the @ref buffer documentation for information on reading into multiple
366
* buffers in one go, and how to use it with arrays, boost::array or
369
* @note This overload is equivalent to calling:
370
* @code asio::async_read_at(
372
* asio::transfer_all(),
375
template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
376
typename ReadHandler>
377
void async_read_at(AsyncRandomAccessReadDevice& d, boost::uint64_t offset,
378
const MutableBufferSequence& buffers, ReadHandler handler);
380
/// Start an asynchronous operation to read a certain amount of data at the
381
/// specified offset.
383
* This function is used to asynchronously read a certain number of bytes of
384
* data from a random access device at the specified offset. The function call
385
* always returns immediately. The asynchronous operation will continue until
386
* one of the following conditions is true:
388
* @li The supplied buffers are full. That is, the bytes transferred is equal to
389
* the sum of the buffer sizes.
391
* @li The completion_condition function object returns true.
393
* @param d The device from which the data is to be read. The type must support
394
* the AsyncRandomAccessReadDevice concept.
396
* @param offset The offset at which the data will be read.
398
* @param buffers One or more buffers into which the data will be read. The sum
399
* of the buffer sizes indicates the maximum number of bytes to read from the
400
* device. Although the buffers object may be copied as necessary, ownership of
401
* the underlying memory blocks is retained by the caller, which must guarantee
402
* that they remain valid until the handler is called.
404
* @param completion_condition The function object to be called to determine
405
* whether the read operation is complete. The signature of the function object
407
* @code bool completion_condition(
408
* // Result of latest read_some_at operation.
409
* const asio::error_code& error,
411
* // Number of bytes transferred so far.
412
* std::size_t bytes_transferred
414
* A return value of true indicates that the read operation is complete. False
415
* indicates that further calls to the device's async_read_some_at function are
418
* @param handler The handler to be called when the read operation completes.
419
* Copies will be made of the handler as required. The function signature of the
421
* @code void handler(
422
* // Result of operation.
423
* const asio::error_code& error,
425
* // Number of bytes copied into the buffers. If an error
426
* // occurred, this will be the number of bytes successfully
427
* // transferred prior to the error.
428
* std::size_t bytes_transferred
430
* Regardless of whether the asynchronous operation completes immediately or
431
* not, the handler will not be invoked from within this function. Invocation of
432
* the handler will be performed in a manner equivalent to using
433
* asio::io_service::post().
436
* To read into a single data buffer use the @ref buffer function as follows:
437
* @code asio::async_read_at(d, 42,
438
* asio::buffer(data, size),
439
* asio::transfer_at_least(32),
441
* See the @ref buffer documentation for information on reading into multiple
442
* buffers in one go, and how to use it with arrays, boost::array or
445
template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
446
typename CompletionCondition, typename ReadHandler>
447
void async_read_at(AsyncRandomAccessReadDevice& d,
448
boost::uint64_t offset, const MutableBufferSequence& buffers,
449
CompletionCondition completion_condition, ReadHandler handler);
451
/// Start an asynchronous operation to read a certain amount of data at the
452
/// specified offset.
454
* This function is used to asynchronously read a certain number of bytes of
455
* data from a random access device at the specified offset. The function call
456
* always returns immediately. The asynchronous operation will continue until
457
* one of the following conditions is true:
459
* @li An error occurred.
461
* This operation is implemented in terms of one or more calls to the device's
462
* async_read_some_at function.
464
* @param d The device from which the data is to be read. The type must support
465
* the AsyncRandomAccessReadDevice concept.
467
* @param offset The offset at which the data will be read.
469
* @param b A basic_streambuf object into which the data will be read. Ownership
470
* of the streambuf is retained by the caller, which must guarantee that it
471
* remains valid until the handler is called.
473
* @param handler The handler to be called when the read operation completes.
474
* Copies will be made of the handler as required. The function signature of the
476
* @code void handler(
477
* // Result of operation.
478
* const asio::error_code& error,
480
* // Number of bytes copied into the buffers. If an error
481
* // occurred, this will be the number of bytes successfully
482
* // transferred prior to the error.
483
* std::size_t bytes_transferred
485
* Regardless of whether the asynchronous operation completes immediately or
486
* not, the handler will not be invoked from within this function. Invocation of
487
* the handler will be performed in a manner equivalent to using
488
* asio::io_service::post().
490
* @note This overload is equivalent to calling:
491
* @code asio::async_read_at(
493
* asio::transfer_all(),
496
template <typename AsyncRandomAccessReadDevice, typename Allocator,
497
typename ReadHandler>
498
void async_read_at(AsyncRandomAccessReadDevice& d, boost::uint64_t offset,
499
basic_streambuf<Allocator>& b, ReadHandler handler);
501
/// Start an asynchronous operation to read a certain amount of data at the
502
/// specified offset.
504
* This function is used to asynchronously read a certain number of bytes of
505
* data from a random access device at the specified offset. The function call
506
* always returns immediately. The asynchronous operation will continue until
507
* one of the following conditions is true:
509
* @li The completion_condition function object returns true.
511
* This operation is implemented in terms of one or more calls to the device's
512
* async_read_some_at function.
514
* @param d The device from which the data is to be read. The type must support
515
* the AsyncRandomAccessReadDevice concept.
517
* @param offset The offset at which the data will be read.
519
* @param b A basic_streambuf object into which the data will be read. Ownership
520
* of the streambuf is retained by the caller, which must guarantee that it
521
* remains valid until the handler is called.
523
* @param completion_condition The function object to be called to determine
524
* whether the read operation is complete. The signature of the function object
526
* @code bool completion_condition(
527
* // Result of latest read_some_at operation.
528
* const asio::error_code& error,
530
* // Number of bytes transferred so far.
531
* std::size_t bytes_transferred
533
* A return value of true indicates that the read operation is complete. False
534
* indicates that further calls to the device's async_read_some_at function are
537
* @param handler The handler to be called when the read operation completes.
538
* Copies will be made of the handler as required. The function signature of the
540
* @code void handler(
541
* // Result of operation.
542
* const asio::error_code& error,
544
* // Number of bytes copied into the buffers. If an error
545
* // occurred, this will be the number of bytes successfully
546
* // transferred prior to the error.
547
* std::size_t bytes_transferred
549
* Regardless of whether the asynchronous operation completes immediately or
550
* not, the handler will not be invoked from within this function. Invocation of
551
* the handler will be performed in a manner equivalent to using
552
* asio::io_service::post().
554
template <typename AsyncRandomAccessReadDevice, typename Allocator,
555
typename CompletionCondition, typename ReadHandler>
556
void async_read_at(AsyncRandomAccessReadDevice& d,
557
boost::uint64_t offset, basic_streambuf<Allocator>& b,
558
CompletionCondition completion_condition, ReadHandler handler);
564
#include "asio/impl/read_at.ipp"
566
#include "asio/detail/pop_options.hpp"
568
#endif // ASIO_READ_AT_HPP
added
removed
include/libtorrent/asio/read_at.hpp
