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)
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 "asio/detail/pop_options.hpp"
25
#include "asio/basic_streambuf.hpp"
26
#include "asio/error.hpp"
31
* @defgroup read asio::read
35
/// Attempt to read a certain amount of data from a stream before returning.
37
* This function is used to read a certain number of bytes of data from a
38
* stream. The call will block until one of the following conditions is true:
40
* @li The supplied buffers are full. That is, the bytes transferred is equal to
41
* the sum of the buffer sizes.
43
* @li An error occurred.
45
* This operation is implemented in terms of one or more calls to the stream's
48
* @param s The stream from which the data is to be read. The type must support
49
* the SyncReadStream concept.
51
* @param buffers One or more buffers into which the data will be read. The sum
52
* of the buffer sizes indicates the maximum number of bytes to read from the
55
* @returns The number of bytes transferred.
57
* @throws asio::system_error Thrown on failure.
60
* To read into a single data buffer use the @ref buffer function as follows:
61
* @code asio::read(s, asio::buffer(data, size)); @endcode
62
* See the @ref buffer documentation for information on reading into multiple
63
* buffers in one go, and how to use it with arrays, boost::array or
66
* @note This overload is equivalent to calling:
69
* asio::transfer_all()); @endcode
71
template <typename SyncReadStream, typename MutableBufferSequence>
72
std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers);
74
/// Attempt to read a certain amount of data from a stream before returning.
76
* This function is used to read a certain number of bytes of data from a
77
* stream. The call will block until one of the following conditions is true:
79
* @li The supplied buffers are full. That is, the bytes transferred is equal to
80
* the sum of the buffer sizes.
82
* @li The completion_condition function object returns true.
84
* This operation is implemented in terms of one or more calls to the stream's
87
* @param s The stream from which the data is to be read. The type must support
88
* the SyncReadStream concept.
90
* @param buffers One or more buffers into which the data will be read. The sum
91
* of the buffer sizes indicates the maximum number of bytes to read from the
94
* @param completion_condition The function object to be called to determine
95
* whether the read operation is complete. The signature of the function object
97
* @code bool completion_condition(
98
* const asio::error_code& error, // Result of latest read_some
101
* std::size_t bytes_transferred // Number of bytes transferred
104
* A return value of true indicates that the read operation is complete. False
105
* indicates that further calls to the stream's read_some function are required.
107
* @returns The number of bytes transferred.
109
* @throws asio::system_error Thrown on failure.
112
* To read into a single data buffer use the @ref buffer function as follows:
113
* @code asio::read(s, asio::buffer(data, size),
114
* asio::transfer_at_least(32)); @endcode
115
* See the @ref buffer documentation for information on reading into multiple
116
* buffers in one go, and how to use it with arrays, boost::array or
119
template <typename SyncReadStream, typename MutableBufferSequence,
120
typename CompletionCondition>
121
std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
122
CompletionCondition completion_condition);
124
/// Attempt to read a certain amount of data from a stream before returning.
126
* This function is used to read a certain number of bytes of data from a
127
* stream. The call will block until one of the following conditions is true:
129
* @li The supplied buffers are full. That is, the bytes transferred is equal to
130
* the sum of the buffer sizes.
132
* @li The completion_condition function object returns true.
134
* This operation is implemented in terms of one or more calls to the stream's
135
* read_some function.
137
* @param s The stream from which the data is to be read. The type must support
138
* the SyncReadStream concept.
140
* @param buffers One or more buffers into which the data will be read. The sum
141
* of the buffer sizes indicates the maximum number of bytes to read from the
144
* @param completion_condition The function object to be called to determine
145
* whether the read operation is complete. The signature of the function object
147
* @code bool completion_condition(
148
* const asio::error_code& error, // Result of latest read_some
151
* std::size_t bytes_transferred // Number of bytes transferred
154
* A return value of true indicates that the read operation is complete. False
155
* indicates that further calls to the stream's read_some function are required.
157
* @param ec Set to indicate what error occurred, if any.
159
* @returns The number of bytes read. If an error occurs, returns the total
160
* number of bytes successfully transferred prior to the error.
162
template <typename SyncReadStream, typename MutableBufferSequence,
163
typename CompletionCondition>
164
std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
165
CompletionCondition completion_condition, asio::error_code& ec);
167
/// Attempt to read a certain amount of data from a stream before returning.
169
* This function is used to read a certain number of bytes of data from a
170
* stream. The call will block until one of the following conditions is true:
172
* @li An error occurred.
174
* This operation is implemented in terms of one or more calls to the stream's
175
* read_some function.
177
* @param s The stream from which the data is to be read. The type must support
178
* the SyncReadStream concept.
180
* @param b The basic_streambuf object into which the data will be read.
182
* @returns The number of bytes transferred.
184
* @throws asio::system_error Thrown on failure.
186
* @note This overload is equivalent to calling:
189
* asio::transfer_all()); @endcode
191
template <typename SyncReadStream, typename Allocator>
192
std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
194
/// Attempt to read a certain amount of data from a stream before returning.
196
* This function is used to read a certain number of bytes of data from a
197
* stream. The call will block until one of the following conditions is true:
199
* @li The completion_condition function object returns true.
201
* This operation is implemented in terms of one or more calls to the stream's
202
* read_some function.
204
* @param s The stream from which the data is to be read. The type must support
205
* the SyncReadStream concept.
207
* @param b The basic_streambuf object into which the data will be read.
209
* @param completion_condition The function object to be called to determine
210
* whether the read operation is complete. The signature of the function object
212
* @code bool completion_condition(
213
* const asio::error_code& error, // Result of latest read_some
216
* std::size_t bytes_transferred // Number of bytes transferred
219
* A return value of true indicates that the read operation is complete. False
220
* indicates that further calls to the stream's read_some function are required.
222
* @returns The number of bytes transferred.
224
* @throws asio::system_error Thrown on failure.
226
template <typename SyncReadStream, typename Allocator,
227
typename CompletionCondition>
228
std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
229
CompletionCondition completion_condition);
231
/// Attempt to read a certain amount of data from a stream before returning.
233
* This function is used to read a certain number of bytes of data from a
234
* stream. The call will block until one of the following conditions is true:
236
* @li The completion_condition function object returns true.
238
* This operation is implemented in terms of one or more calls to the stream's
239
* read_some function.
241
* @param s The stream from which the data is to be read. The type must support
242
* the SyncReadStream concept.
244
* @param b The basic_streambuf object into which the data will be read.
246
* @param completion_condition The function object to be called to determine
247
* whether the read operation is complete. The signature of the function object
249
* @code bool completion_condition(
250
* const asio::error_code& error, // Result of latest read_some
253
* std::size_t bytes_transferred // Number of bytes transferred
256
* A return value of true indicates that the read operation is complete. False
257
* indicates that further calls to the stream's read_some function are required.
259
* @param ec Set to indicate what error occurred, if any.
261
* @returns The number of bytes read. If an error occurs, returns the total
262
* number of bytes successfully transferred prior to the error.
264
template <typename SyncReadStream, typename Allocator,
265
typename CompletionCondition>
266
std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
267
CompletionCondition completion_condition, asio::error_code& ec);
271
* @defgroup async_read asio::async_read
275
/// Start an asynchronous operation to read a certain amount of data from a
278
* This function is used to asynchronously read a certain number of bytes of
279
* data from a stream. The function call always returns immediately. The
280
* asynchronous operation will continue until one of the following conditions is
283
* @li The supplied buffers are full. That is, the bytes transferred is equal to
284
* the sum of the buffer sizes.
286
* @li An error occurred.
288
* This operation is implemented in terms of one or more calls to the stream's
289
* async_read_some function.
291
* @param s The stream from which the data is to be read. The type must support
292
* the AsyncReadStream concept.
294
* @param buffers One or more buffers into which the data will be read. The sum
295
* of the buffer sizes indicates the maximum number of bytes to read from the
296
* stream. Although the buffers object may be copied as necessary, ownership of
297
* the underlying memory blocks is retained by the caller, which must guarantee
298
* that they remain valid until the handler is called.
300
* @param handler The handler to be called when the read operation completes.
301
* Copies will be made of the handler as required. The function signature of the
303
* @code void handler(
304
* const asio::error_code& error, // Result of operation.
306
* std::size_t bytes_transferred // Number of bytes copied into the
307
* // buffers. If an error occurred,
308
* // this will be the number of
309
* // bytes successfully transferred
310
* // prior to the error.
312
* Regardless of whether the asynchronous operation completes immediately or
313
* not, the handler will not be invoked from within this function. Invocation of
314
* the handler will be performed in a manner equivalent to using
315
* asio::io_service::post().
318
* To read into a single data buffer use the @ref buffer function as follows:
320
* asio::async_read(s, asio::buffer(data, size), handler);
322
* See the @ref buffer documentation for information on reading into multiple
323
* buffers in one go, and how to use it with arrays, boost::array or
326
* @note This overload is equivalent to calling:
327
* @code asio::async_read(
329
* asio::transfer_all(),
332
template <typename AsyncReadStream, typename MutableBufferSequence,
333
typename ReadHandler>
334
void async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
335
ReadHandler handler);
337
/// Start an asynchronous operation to read a certain amount of data from a
340
* This function is used to asynchronously read a certain number of bytes of
341
* data from a stream. The function call always returns immediately. The
342
* asynchronous operation will continue until one of the following conditions is
345
* @li The supplied buffers are full. That is, the bytes transferred is equal to
346
* the sum of the buffer sizes.
348
* @li The completion_condition function object returns true.
350
* @param s The stream from which the data is to be read. The type must support
351
* the AsyncReadStream concept.
353
* @param buffers One or more buffers into which the data will be read. The sum
354
* of the buffer sizes indicates the maximum number of bytes to read from the
355
* stream. Although the buffers object may be copied as necessary, ownership of
356
* the underlying memory blocks is retained by the caller, which must guarantee
357
* that they remain valid until the handler is called.
359
* @param completion_condition The function object to be called to determine
360
* whether the read operation is complete. The signature of the function object
362
* @code bool completion_condition(
363
* const asio::error_code& error, // Result of latest read_some
366
* std::size_t bytes_transferred // Number of bytes transferred
369
* A return value of true indicates that the read operation is complete. False
370
* indicates that further calls to the stream's async_read_some function are
373
* @param handler The handler to be called when the read operation completes.
374
* Copies will be made of the handler as required. The function signature of the
376
* @code void handler(
377
* const asio::error_code& error, // Result of operation.
379
* std::size_t bytes_transferred // Number of bytes copied into the
380
* // buffers. If an error occurred,
381
* // this will be the number of
382
* // bytes successfully transferred
383
* // prior to the error.
385
* Regardless of whether the asynchronous operation completes immediately or
386
* not, the handler will not be invoked from within this function. Invocation of
387
* the handler will be performed in a manner equivalent to using
388
* asio::io_service::post().
391
* To read into a single data buffer use the @ref buffer function as follows:
392
* @code asio::async_read(s,
393
* asio::buffer(data, size),
394
* asio::transfer_at_least(32),
396
* See the @ref buffer documentation for information on reading into multiple
397
* buffers in one go, and how to use it with arrays, boost::array or
400
template <typename AsyncReadStream, typename MutableBufferSequence,
401
typename CompletionCondition, typename ReadHandler>
402
void async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
403
CompletionCondition completion_condition, ReadHandler handler);
405
/// Start an asynchronous operation to read a certain amount of data from a
408
* This function is used to asynchronously read a certain number of bytes of
409
* data from a stream. The function call always returns immediately. The
410
* asynchronous operation will continue until one of the following conditions is
413
* @li An error occurred.
415
* This operation is implemented in terms of one or more calls to the stream's
416
* async_read_some function.
418
* @param s The stream from which the data is to be read. The type must support
419
* the AsyncReadStream concept.
421
* @param b A basic_streambuf object into which the data will be read. Ownership
422
* of the streambuf is retained by the caller, which must guarantee that it
423
* remains valid until the handler is called.
425
* @param handler The handler to be called when the read operation completes.
426
* Copies will be made of the handler as required. The function signature of the
428
* @code void handler(
429
* const asio::error_code& error, // Result of operation.
431
* std::size_t bytes_transferred // Number of bytes copied into the
432
* // buffers. If an error occurred,
433
* // this will be the number of
434
* // bytes successfully transferred
435
* // prior to the error.
437
* Regardless of whether the asynchronous operation completes immediately or
438
* not, the handler will not be invoked from within this function. Invocation of
439
* the handler will be performed in a manner equivalent to using
440
* asio::io_service::post().
442
* @note This overload is equivalent to calling:
443
* @code asio::async_read(
445
* asio::transfer_all(),
448
template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
449
void async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
450
ReadHandler handler);
452
/// Start an asynchronous operation to read a certain amount of data from a
455
* This function is used to asynchronously read a certain number of bytes of
456
* data from a stream. The function call always returns immediately. The
457
* asynchronous operation will continue until one of the following conditions is
460
* @li The completion_condition function object returns true.
462
* This operation is implemented in terms of one or more calls to the stream's
463
* async_read_some function.
465
* @param s The stream from which the data is to be read. The type must support
466
* the AsyncReadStream concept.
468
* @param b A basic_streambuf object into which the data will be read. Ownership
469
* of the streambuf is retained by the caller, which must guarantee that it
470
* remains valid until the handler is called.
472
* @param completion_condition The function object to be called to determine
473
* whether the read operation is complete. The signature of the function object
475
* @code bool completion_condition(
476
* const asio::error_code& error, // Result of latest read_some
479
* std::size_t bytes_transferred // Number of bytes transferred
482
* A return value of true indicates that the read operation is complete. False
483
* indicates that further calls to the stream's async_read_some function are
486
* @param handler The handler to be called when the read operation completes.
487
* Copies will be made of the handler as required. The function signature of the
489
* @code void handler(
490
* const asio::error_code& error, // Result of operation.
492
* std::size_t bytes_transferred // Number of bytes copied into the
493
* // buffers. If an error occurred,
494
* // this will be the number of
495
* // bytes successfully transferred
496
* // prior to the error.
498
* Regardless of whether the asynchronous operation completes immediately or
499
* not, the handler will not be invoked from within this function. Invocation of
500
* the handler will be performed in a manner equivalent to using
501
* asio::io_service::post().
503
template <typename AsyncReadStream, typename Allocator,
504
typename CompletionCondition, typename ReadHandler>
505
void async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
506
CompletionCondition completion_condition, ReadHandler handler);
512
#include "asio/impl/read.ipp"
514
#include "asio/detail/pop_options.hpp"
516
#endif // ASIO_READ_HPP
added
removed
include/libtorrent/asio/read.hpp
