]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // |
2 | // read.hpp | |
3 | // ~~~~~~~~ | |
4 | // | |
92f5a8d4 | 5 | // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
7c673cae FG |
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_READ_HPP | |
12 | #define BOOST_ASIO_READ_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> | |
b32b8144 | 21 | #include <boost/asio/buffer.hpp> |
7c673cae FG |
22 | #include <boost/asio/error.hpp> |
23 | ||
b32b8144 FG |
24 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) |
25 | # include <boost/asio/basic_streambuf_fwd.hpp> | |
26 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) | |
27 | ||
7c673cae FG |
28 | #include <boost/asio/detail/push_options.hpp> |
29 | ||
30 | namespace boost { | |
31 | namespace asio { | |
32 | ||
33 | /** | |
34 | * @defgroup read boost::asio::read | |
35 | * | |
92f5a8d4 TL |
36 | * @brief The @c read function is a composed operation that reads a certain |
37 | * amount of data from a stream before returning. | |
7c673cae FG |
38 | */ |
39 | /*@{*/ | |
40 | ||
41 | /// Attempt to read a certain amount of data from a stream before returning. | |
42 | /** | |
43 | * This function is used to read a certain number of bytes of data from a | |
44 | * stream. The call will block until one of the following conditions is true: | |
45 | * | |
46 | * @li The supplied buffers are full. That is, the bytes transferred is equal to | |
47 | * the sum of the buffer sizes. | |
48 | * | |
49 | * @li An error occurred. | |
50 | * | |
51 | * This operation is implemented in terms of zero or more calls to the stream's | |
52 | * read_some function. | |
53 | * | |
54 | * @param s The stream from which the data is to be read. The type must support | |
55 | * the SyncReadStream concept. | |
56 | * | |
57 | * @param buffers One or more buffers into which the data will be read. The sum | |
58 | * of the buffer sizes indicates the maximum number of bytes to read from the | |
59 | * stream. | |
60 | * | |
61 | * @returns The number of bytes transferred. | |
62 | * | |
63 | * @throws boost::system::system_error Thrown on failure. | |
64 | * | |
65 | * @par Example | |
66 | * To read into a single data buffer use the @ref buffer function as follows: | |
67 | * @code boost::asio::read(s, boost::asio::buffer(data, size)); @endcode | |
68 | * See the @ref buffer documentation for information on reading into multiple | |
69 | * buffers in one go, and how to use it with arrays, boost::array or | |
70 | * std::vector. | |
71 | * | |
72 | * @note This overload is equivalent to calling: | |
73 | * @code boost::asio::read( | |
74 | * s, buffers, | |
75 | * boost::asio::transfer_all()); @endcode | |
76 | */ | |
77 | template <typename SyncReadStream, typename MutableBufferSequence> | |
b32b8144 FG |
78 | std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, |
79 | typename enable_if< | |
80 | is_mutable_buffer_sequence<MutableBufferSequence>::value | |
81 | >::type* = 0); | |
7c673cae FG |
82 | |
83 | /// Attempt to read a certain amount of data from a stream before returning. | |
84 | /** | |
85 | * This function is used to read a certain number of bytes of data from a | |
86 | * stream. The call will block until one of the following conditions is true: | |
87 | * | |
88 | * @li The supplied buffers are full. That is, the bytes transferred is equal to | |
89 | * the sum of the buffer sizes. | |
90 | * | |
91 | * @li An error occurred. | |
92 | * | |
93 | * This operation is implemented in terms of zero or more calls to the stream's | |
94 | * read_some function. | |
95 | * | |
96 | * @param s The stream from which the data is to be read. The type must support | |
97 | * the SyncReadStream concept. | |
98 | * | |
99 | * @param buffers One or more buffers into which the data will be read. The sum | |
100 | * of the buffer sizes indicates the maximum number of bytes to read from the | |
101 | * stream. | |
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 read into a single data buffer use the @ref buffer function as follows: | |
109 | * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode | |
110 | * See the @ref buffer documentation for information on reading into multiple | |
111 | * buffers in one go, and how to use it with arrays, boost::array or | |
112 | * std::vector. | |
113 | * | |
114 | * @note This overload is equivalent to calling: | |
115 | * @code boost::asio::read( | |
116 | * s, buffers, | |
117 | * boost::asio::transfer_all(), ec); @endcode | |
118 | */ | |
119 | template <typename SyncReadStream, typename MutableBufferSequence> | |
120 | std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, | |
b32b8144 FG |
121 | boost::system::error_code& ec, |
122 | typename enable_if< | |
123 | is_mutable_buffer_sequence<MutableBufferSequence>::value | |
124 | >::type* = 0); | |
7c673cae FG |
125 | |
126 | /// Attempt to read a certain amount of data from a stream before returning. | |
127 | /** | |
128 | * This function is used to read a certain number of bytes of data from a | |
129 | * stream. The call will block until one of the following conditions is true: | |
130 | * | |
131 | * @li The supplied buffers are full. That is, the bytes transferred is equal to | |
132 | * 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 stream's | |
137 | * read_some function. | |
138 | * | |
139 | * @param s The stream from which the data is to be read. The type must support | |
140 | * the SyncReadStream concept. | |
141 | * | |
142 | * @param buffers One or more buffers into which the data will be read. The sum | |
143 | * of the buffer sizes indicates the maximum number of bytes to read from the | |
144 | * stream. | |
145 | * | |
146 | * @param completion_condition The function object to be called to determine | |
147 | * whether the read operation is complete. The signature of the function object | |
148 | * must be: | |
149 | * @code std::size_t completion_condition( | |
150 | * // Result of latest read_some operation. | |
151 | * const boost::system::error_code& error, | |
152 | * | |
153 | * // Number of bytes transferred so far. | |
154 | * std::size_t bytes_transferred | |
155 | * ); @endcode | |
156 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
157 | * return value indicates the maximum number of bytes to be read on the next | |
158 | * call to the stream's read_some function. | |
159 | * | |
160 | * @returns The number of bytes transferred. | |
161 | * | |
162 | * @throws boost::system::system_error Thrown on failure. | |
163 | * | |
164 | * @par Example | |
165 | * To read into a single data buffer use the @ref buffer function as follows: | |
166 | * @code boost::asio::read(s, boost::asio::buffer(data, size), | |
167 | * boost::asio::transfer_at_least(32)); @endcode | |
168 | * See the @ref buffer documentation for information on reading into multiple | |
169 | * buffers in one go, and how to use it with arrays, boost::array or | |
170 | * std::vector. | |
171 | */ | |
172 | template <typename SyncReadStream, typename MutableBufferSequence, | |
173 | typename CompletionCondition> | |
174 | std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, | |
b32b8144 FG |
175 | CompletionCondition completion_condition, |
176 | typename enable_if< | |
177 | is_mutable_buffer_sequence<MutableBufferSequence>::value | |
178 | >::type* = 0); | |
7c673cae FG |
179 | |
180 | /// Attempt to read a certain amount of data from a stream before returning. | |
181 | /** | |
182 | * This function is used to read a certain number of bytes of data from a | |
183 | * stream. The call will block until one of the following conditions is true: | |
184 | * | |
185 | * @li The supplied buffers are full. That is, the bytes transferred is equal to | |
186 | * the sum of the buffer sizes. | |
187 | * | |
188 | * @li The completion_condition function object returns 0. | |
189 | * | |
190 | * This operation is implemented in terms of zero or more calls to the stream's | |
191 | * read_some function. | |
192 | * | |
193 | * @param s The stream from which the data is to be read. The type must support | |
194 | * the SyncReadStream concept. | |
195 | * | |
196 | * @param buffers One or more buffers into which the data will be read. The sum | |
197 | * of the buffer sizes indicates the maximum number of bytes to read from the | |
198 | * stream. | |
199 | * | |
200 | * @param completion_condition The function object to be called to determine | |
201 | * whether the read operation is complete. The signature of the function object | |
202 | * must be: | |
203 | * @code std::size_t completion_condition( | |
204 | * // Result of latest read_some operation. | |
205 | * const boost::system::error_code& error, | |
206 | * | |
207 | * // Number of bytes transferred so far. | |
208 | * std::size_t bytes_transferred | |
209 | * ); @endcode | |
210 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
211 | * return value indicates the maximum number of bytes to be read on the next | |
212 | * call to the stream's read_some function. | |
213 | * | |
214 | * @param ec Set to indicate what error occurred, if any. | |
215 | * | |
216 | * @returns The number of bytes read. If an error occurs, returns the total | |
217 | * number of bytes successfully transferred prior to the error. | |
218 | */ | |
219 | template <typename SyncReadStream, typename MutableBufferSequence, | |
220 | typename CompletionCondition> | |
221 | std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, | |
b32b8144 FG |
222 | CompletionCondition completion_condition, boost::system::error_code& ec, |
223 | typename enable_if< | |
224 | is_mutable_buffer_sequence<MutableBufferSequence>::value | |
225 | >::type* = 0); | |
226 | ||
92f5a8d4 TL |
227 | #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
228 | ||
b32b8144 FG |
229 | /// Attempt to read a certain amount of data from a stream before returning. |
230 | /** | |
231 | * This function is used to read a certain number of bytes of data from a | |
232 | * stream. The call will block until one of the following conditions is true: | |
233 | * | |
234 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
235 | * maximum size). | |
236 | * | |
237 | * @li An error occurred. | |
238 | * | |
239 | * This operation is implemented in terms of zero or more calls to the stream's | |
240 | * read_some function. | |
241 | * | |
242 | * @param s The stream from which the data is to be read. The type must support | |
243 | * the SyncReadStream concept. | |
244 | * | |
245 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
246 | * | |
247 | * @returns The number of bytes transferred. | |
248 | * | |
249 | * @throws boost::system::system_error Thrown on failure. | |
250 | * | |
251 | * @note This overload is equivalent to calling: | |
252 | * @code boost::asio::read( | |
253 | * s, buffers, | |
254 | * boost::asio::transfer_all()); @endcode | |
255 | */ | |
92f5a8d4 | 256 | template <typename SyncReadStream, typename DynamicBuffer_v1> |
b32b8144 | 257 | std::size_t read(SyncReadStream& s, |
92f5a8d4 | 258 | BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, |
b32b8144 | 259 | typename enable_if< |
92f5a8d4 TL |
260 | is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value |
261 | && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value | |
b32b8144 FG |
262 | >::type* = 0); |
263 | ||
264 | /// Attempt to read a certain amount of data from a stream before returning. | |
265 | /** | |
266 | * This function is used to read a certain number of bytes of data from a | |
267 | * stream. The call will block until one of the following conditions is true: | |
268 | * | |
269 | * @li The supplied buffer is full (that is, it has reached maximum size). | |
270 | * | |
271 | * @li An error occurred. | |
272 | * | |
273 | * This operation is implemented in terms of zero or more calls to the stream's | |
274 | * read_some function. | |
275 | * | |
276 | * @param s The stream from which the data is to be read. The type must support | |
277 | * the SyncReadStream concept. | |
278 | * | |
279 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
280 | * | |
281 | * @param ec Set to indicate what error occurred, if any. | |
282 | * | |
283 | * @returns The number of bytes transferred. | |
284 | * | |
285 | * @note This overload is equivalent to calling: | |
286 | * @code boost::asio::read( | |
287 | * s, buffers, | |
288 | * boost::asio::transfer_all(), ec); @endcode | |
289 | */ | |
92f5a8d4 | 290 | template <typename SyncReadStream, typename DynamicBuffer_v1> |
b32b8144 | 291 | std::size_t read(SyncReadStream& s, |
92f5a8d4 | 292 | BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, |
b32b8144 FG |
293 | boost::system::error_code& ec, |
294 | typename enable_if< | |
92f5a8d4 TL |
295 | is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value |
296 | && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value | |
b32b8144 FG |
297 | >::type* = 0); |
298 | ||
299 | /// Attempt to read a certain amount of data from a stream before returning. | |
300 | /** | |
301 | * This function is used to read a certain number of bytes of data from a | |
302 | * stream. The call will block until one of the following conditions is true: | |
303 | * | |
304 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
305 | * maximum size). | |
306 | * | |
307 | * @li The completion_condition function object returns 0. | |
308 | * | |
309 | * This operation is implemented in terms of zero or more calls to the stream's | |
310 | * read_some function. | |
311 | * | |
312 | * @param s The stream from which the data is to be read. The type must support | |
313 | * the SyncReadStream concept. | |
314 | * | |
315 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
316 | * | |
317 | * @param completion_condition The function object to be called to determine | |
318 | * whether the read operation is complete. The signature of the function object | |
319 | * must be: | |
320 | * @code std::size_t completion_condition( | |
321 | * // Result of latest read_some 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 read operation is complete. A non-zero | |
328 | * return value indicates the maximum number of bytes to be read on the next | |
329 | * call to the stream's read_some function. | |
330 | * | |
331 | * @returns The number of bytes transferred. | |
332 | * | |
333 | * @throws boost::system::system_error Thrown on failure. | |
334 | */ | |
92f5a8d4 | 335 | template <typename SyncReadStream, typename DynamicBuffer_v1, |
b32b8144 FG |
336 | typename CompletionCondition> |
337 | std::size_t read(SyncReadStream& s, | |
92f5a8d4 | 338 | BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, |
b32b8144 FG |
339 | CompletionCondition completion_condition, |
340 | typename enable_if< | |
92f5a8d4 TL |
341 | is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value |
342 | && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value | |
b32b8144 | 343 | >::type* = 0); |
7c673cae | 344 | |
b32b8144 FG |
345 | /// Attempt to read a certain amount of data from a stream before returning. |
346 | /** | |
347 | * This function is used to read a certain number of bytes of data from a | |
348 | * stream. The call will block until one of the following conditions is true: | |
349 | * | |
350 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
351 | * maximum size). | |
352 | * | |
353 | * @li The completion_condition function object returns 0. | |
354 | * | |
355 | * This operation is implemented in terms of zero or more calls to the stream's | |
356 | * read_some function. | |
357 | * | |
358 | * @param s The stream from which the data is to be read. The type must support | |
359 | * the SyncReadStream concept. | |
360 | * | |
361 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
362 | * | |
363 | * @param completion_condition The function object to be called to determine | |
364 | * whether the read operation is complete. The signature of the function object | |
365 | * must be: | |
366 | * @code std::size_t completion_condition( | |
367 | * // Result of latest read_some operation. | |
368 | * const boost::system::error_code& error, | |
369 | * | |
370 | * // Number of bytes transferred so far. | |
371 | * std::size_t bytes_transferred | |
372 | * ); @endcode | |
373 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
374 | * return value indicates the maximum number of bytes to be read on the next | |
375 | * call to the stream's read_some function. | |
376 | * | |
377 | * @param ec Set to indicate what error occurred, if any. | |
378 | * | |
379 | * @returns The number of bytes read. If an error occurs, returns the total | |
380 | * number of bytes successfully transferred prior to the error. | |
381 | */ | |
92f5a8d4 | 382 | template <typename SyncReadStream, typename DynamicBuffer_v1, |
b32b8144 FG |
383 | typename CompletionCondition> |
384 | std::size_t read(SyncReadStream& s, | |
92f5a8d4 | 385 | BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, |
b32b8144 FG |
386 | CompletionCondition completion_condition, boost::system::error_code& ec, |
387 | typename enable_if< | |
92f5a8d4 TL |
388 | is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value |
389 | && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value | |
b32b8144 FG |
390 | >::type* = 0); |
391 | ||
392 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) | |
7c673cae FG |
393 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
394 | ||
395 | /// Attempt to read a certain amount of data from a stream before returning. | |
396 | /** | |
397 | * This function is used to read a certain number of bytes of data from a | |
398 | * stream. The call will block until one of the following conditions is true: | |
399 | * | |
400 | * @li The supplied buffer is full (that is, it has reached maximum size). | |
401 | * | |
402 | * @li An error occurred. | |
403 | * | |
404 | * This operation is implemented in terms of zero or more calls to the stream's | |
405 | * read_some function. | |
406 | * | |
407 | * @param s The stream from which the data is to be read. The type must support | |
408 | * the SyncReadStream concept. | |
409 | * | |
410 | * @param b The basic_streambuf object into which the data will be read. | |
411 | * | |
412 | * @returns The number of bytes transferred. | |
413 | * | |
414 | * @throws boost::system::system_error Thrown on failure. | |
415 | * | |
416 | * @note This overload is equivalent to calling: | |
417 | * @code boost::asio::read( | |
418 | * s, b, | |
419 | * boost::asio::transfer_all()); @endcode | |
420 | */ | |
421 | template <typename SyncReadStream, typename Allocator> | |
422 | std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b); | |
423 | ||
424 | /// Attempt to read a certain amount of data from a stream before returning. | |
425 | /** | |
426 | * This function is used to read a certain number of bytes of data from a | |
427 | * stream. The call will block until one of the following conditions is true: | |
428 | * | |
429 | * @li The supplied buffer is full (that is, it has reached maximum size). | |
430 | * | |
431 | * @li An error occurred. | |
432 | * | |
433 | * This operation is implemented in terms of zero or more calls to the stream's | |
434 | * read_some function. | |
435 | * | |
436 | * @param s The stream from which the data is to be read. The type must support | |
437 | * the SyncReadStream concept. | |
438 | * | |
439 | * @param b The basic_streambuf object into which the data will be read. | |
440 | * | |
441 | * @param ec Set to indicate what error occurred, if any. | |
442 | * | |
443 | * @returns The number of bytes transferred. | |
444 | * | |
445 | * @note This overload is equivalent to calling: | |
446 | * @code boost::asio::read( | |
447 | * s, b, | |
448 | * boost::asio::transfer_all(), ec); @endcode | |
449 | */ | |
450 | template <typename SyncReadStream, typename Allocator> | |
451 | std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, | |
452 | boost::system::error_code& ec); | |
453 | ||
454 | /// Attempt to read a certain amount of data from a stream before returning. | |
455 | /** | |
456 | * This function is used to read a certain number of bytes of data from a | |
457 | * stream. The call will block until one of the following conditions is true: | |
458 | * | |
459 | * @li The supplied buffer is full (that is, it has reached maximum size). | |
460 | * | |
461 | * @li The completion_condition function object returns 0. | |
462 | * | |
463 | * This operation is implemented in terms of zero or more calls to the stream's | |
464 | * read_some function. | |
465 | * | |
466 | * @param s The stream from which the data is to be read. The type must support | |
467 | * the SyncReadStream concept. | |
468 | * | |
469 | * @param b The basic_streambuf object into which the data will be read. | |
470 | * | |
471 | * @param completion_condition The function object to be called to determine | |
472 | * whether the read operation is complete. The signature of the function object | |
473 | * must be: | |
474 | * @code std::size_t completion_condition( | |
475 | * // Result of latest read_some operation. | |
476 | * const boost::system::error_code& error, | |
477 | * | |
478 | * // Number of bytes transferred so far. | |
479 | * std::size_t bytes_transferred | |
480 | * ); @endcode | |
481 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
482 | * return value indicates the maximum number of bytes to be read on the next | |
483 | * call to the stream's read_some function. | |
484 | * | |
485 | * @returns The number of bytes transferred. | |
486 | * | |
487 | * @throws boost::system::system_error Thrown on failure. | |
488 | */ | |
489 | template <typename SyncReadStream, typename Allocator, | |
490 | typename CompletionCondition> | |
491 | std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, | |
492 | CompletionCondition completion_condition); | |
493 | ||
494 | /// Attempt to read a certain amount of data from a stream before returning. | |
495 | /** | |
496 | * This function is used to read a certain number of bytes of data from a | |
497 | * stream. The call will block until one of the following conditions is true: | |
498 | * | |
499 | * @li The supplied buffer is full (that is, it has reached maximum size). | |
500 | * | |
501 | * @li The completion_condition function object returns 0. | |
502 | * | |
503 | * This operation is implemented in terms of zero or more calls to the stream's | |
504 | * read_some function. | |
505 | * | |
506 | * @param s The stream from which the data is to be read. The type must support | |
507 | * the SyncReadStream concept. | |
508 | * | |
509 | * @param b The basic_streambuf object into which the data will be read. | |
510 | * | |
511 | * @param completion_condition The function object to be called to determine | |
512 | * whether the read operation is complete. The signature of the function object | |
513 | * must be: | |
514 | * @code std::size_t completion_condition( | |
515 | * // Result of latest read_some operation. | |
516 | * const boost::system::error_code& error, | |
517 | * | |
518 | * // Number of bytes transferred so far. | |
519 | * std::size_t bytes_transferred | |
520 | * ); @endcode | |
521 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
522 | * return value indicates the maximum number of bytes to be read on the next | |
523 | * call to the stream's read_some function. | |
524 | * | |
525 | * @param ec Set to indicate what error occurred, if any. | |
526 | * | |
527 | * @returns The number of bytes read. If an error occurs, returns the total | |
528 | * number of bytes successfully transferred prior to the error. | |
529 | */ | |
530 | template <typename SyncReadStream, typename Allocator, | |
531 | typename CompletionCondition> | |
532 | std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, | |
533 | CompletionCondition completion_condition, boost::system::error_code& ec); | |
534 | ||
535 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) | |
b32b8144 | 536 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) |
92f5a8d4 TL |
537 | #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
538 | ||
539 | /// Attempt to read a certain amount of data from a stream before returning. | |
540 | /** | |
541 | * This function is used to read a certain number of bytes of data from a | |
542 | * stream. The call will block until one of the following conditions is true: | |
543 | * | |
544 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
545 | * maximum size). | |
546 | * | |
547 | * @li An error occurred. | |
548 | * | |
549 | * This operation is implemented in terms of zero or more calls to the stream's | |
550 | * read_some function. | |
551 | * | |
552 | * @param s The stream from which the data is to be read. The type must support | |
553 | * the SyncReadStream concept. | |
554 | * | |
555 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
556 | * | |
557 | * @returns The number of bytes transferred. | |
558 | * | |
559 | * @throws boost::system::system_error Thrown on failure. | |
560 | * | |
561 | * @note This overload is equivalent to calling: | |
562 | * @code boost::asio::read( | |
563 | * s, buffers, | |
564 | * boost::asio::transfer_all()); @endcode | |
565 | */ | |
566 | template <typename SyncReadStream, typename DynamicBuffer_v2> | |
567 | std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, | |
568 | typename enable_if< | |
569 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value | |
570 | >::type* = 0); | |
571 | ||
572 | /// Attempt to read a certain amount of data from a stream before returning. | |
573 | /** | |
574 | * This function is used to read a certain number of bytes of data from a | |
575 | * stream. The call will block until one of the following conditions is true: | |
576 | * | |
577 | * @li The supplied buffer is full (that is, it has reached maximum size). | |
578 | * | |
579 | * @li An error occurred. | |
580 | * | |
581 | * This operation is implemented in terms of zero or more calls to the stream's | |
582 | * read_some function. | |
583 | * | |
584 | * @param s The stream from which the data is to be read. The type must support | |
585 | * the SyncReadStream concept. | |
586 | * | |
587 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
588 | * | |
589 | * @param ec Set to indicate what error occurred, if any. | |
590 | * | |
591 | * @returns The number of bytes transferred. | |
592 | * | |
593 | * @note This overload is equivalent to calling: | |
594 | * @code boost::asio::read( | |
595 | * s, buffers, | |
596 | * boost::asio::transfer_all(), ec); @endcode | |
597 | */ | |
598 | template <typename SyncReadStream, typename DynamicBuffer_v2> | |
599 | std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, | |
600 | boost::system::error_code& ec, | |
601 | typename enable_if< | |
602 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value | |
603 | >::type* = 0); | |
604 | ||
605 | /// Attempt to read a certain amount of data from a stream before returning. | |
606 | /** | |
607 | * This function is used to read a certain number of bytes of data from a | |
608 | * stream. The call will block until one of the following conditions is true: | |
609 | * | |
610 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
611 | * maximum size). | |
612 | * | |
613 | * @li The completion_condition function object returns 0. | |
614 | * | |
615 | * This operation is implemented in terms of zero or more calls to the stream's | |
616 | * read_some function. | |
617 | * | |
618 | * @param s The stream from which the data is to be read. The type must support | |
619 | * the SyncReadStream concept. | |
620 | * | |
621 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
622 | * | |
623 | * @param completion_condition The function object to be called to determine | |
624 | * whether the read operation is complete. The signature of the function object | |
625 | * must be: | |
626 | * @code std::size_t completion_condition( | |
627 | * // Result of latest read_some 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 read operation is complete. A non-zero | |
634 | * return value indicates the maximum number of bytes to be read on the next | |
635 | * call to the stream's read_some function. | |
636 | * | |
637 | * @returns The number of bytes transferred. | |
638 | * | |
639 | * @throws boost::system::system_error Thrown on failure. | |
640 | */ | |
641 | template <typename SyncReadStream, typename DynamicBuffer_v2, | |
642 | typename CompletionCondition> | |
643 | std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, | |
644 | CompletionCondition completion_condition, | |
645 | typename enable_if< | |
646 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value | |
647 | >::type* = 0); | |
648 | ||
649 | /// Attempt to read a certain amount of data from a stream before returning. | |
650 | /** | |
651 | * This function is used to read a certain number of bytes of data from a | |
652 | * stream. The call will block until one of the following conditions is true: | |
653 | * | |
654 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
655 | * maximum size). | |
656 | * | |
657 | * @li The completion_condition function object returns 0. | |
658 | * | |
659 | * This operation is implemented in terms of zero or more calls to the stream's | |
660 | * read_some function. | |
661 | * | |
662 | * @param s The stream from which the data is to be read. The type must support | |
663 | * the SyncReadStream concept. | |
664 | * | |
665 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
666 | * | |
667 | * @param completion_condition The function object to be called to determine | |
668 | * whether the read operation is complete. The signature of the function object | |
669 | * must be: | |
670 | * @code std::size_t completion_condition( | |
671 | * // Result of latest read_some operation. | |
672 | * const boost::system::error_code& error, | |
673 | * | |
674 | * // Number of bytes transferred so far. | |
675 | * std::size_t bytes_transferred | |
676 | * ); @endcode | |
677 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
678 | * return value indicates the maximum number of bytes to be read on the next | |
679 | * call to the stream's read_some function. | |
680 | * | |
681 | * @param ec Set to indicate what error occurred, if any. | |
682 | * | |
683 | * @returns The number of bytes read. If an error occurs, returns the total | |
684 | * number of bytes successfully transferred prior to the error. | |
685 | */ | |
686 | template <typename SyncReadStream, typename DynamicBuffer_v2, | |
687 | typename CompletionCondition> | |
688 | std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers, | |
689 | CompletionCondition completion_condition, boost::system::error_code& ec, | |
690 | typename enable_if< | |
691 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value | |
692 | >::type* = 0); | |
7c673cae FG |
693 | |
694 | /*@}*/ | |
695 | /** | |
696 | * @defgroup async_read boost::asio::async_read | |
697 | * | |
92f5a8d4 TL |
698 | * @brief The @c async_read function is a composed asynchronous operation that |
699 | * reads a certain amount of data from a stream before completion. | |
7c673cae FG |
700 | */ |
701 | /*@{*/ | |
702 | ||
703 | /// Start an asynchronous operation to read a certain amount of data from a | |
704 | /// stream. | |
705 | /** | |
706 | * This function is used to asynchronously read a certain number of bytes of | |
707 | * data from a stream. The function call always returns immediately. The | |
708 | * asynchronous operation will continue until one of the following conditions is | |
709 | * true: | |
710 | * | |
711 | * @li The supplied buffers are full. That is, the bytes transferred is equal to | |
712 | * the sum of the buffer sizes. | |
713 | * | |
714 | * @li An error occurred. | |
715 | * | |
716 | * This operation is implemented in terms of zero or more calls to the stream's | |
717 | * async_read_some function, and is known as a <em>composed operation</em>. The | |
718 | * program must ensure that the stream performs no other read operations (such | |
719 | * as async_read, the stream's async_read_some function, or any other composed | |
720 | * operations that perform reads) until this operation completes. | |
721 | * | |
722 | * @param s The stream from which the data is to be read. The type must support | |
723 | * the AsyncReadStream concept. | |
724 | * | |
725 | * @param buffers One or more buffers into which the data will be read. The sum | |
726 | * of the buffer sizes indicates the maximum number of bytes to read from the | |
727 | * stream. Although the buffers object may be copied as necessary, ownership of | |
728 | * the underlying memory blocks is retained by the caller, which must guarantee | |
729 | * that they remain valid until the handler is called. | |
730 | * | |
731 | * @param handler The handler to be called when the read operation completes. | |
732 | * Copies will be made of the handler as required. The function signature of the | |
733 | * handler must be: | |
734 | * @code void handler( | |
735 | * const boost::system::error_code& error, // Result of operation. | |
736 | * | |
737 | * std::size_t bytes_transferred // Number of bytes copied into the | |
738 | * // buffers. If an error occurred, | |
739 | * // this will be the number of | |
740 | * // bytes successfully transferred | |
741 | * // prior to the error. | |
742 | * ); @endcode | |
743 | * Regardless of whether the asynchronous operation completes immediately or | |
92f5a8d4 TL |
744 | * not, the handler will not be invoked from within this function. On |
745 | * immediate completion, invocation of the handler will be performed in a | |
746 | * manner equivalent to using boost::asio::post(). | |
7c673cae FG |
747 | * |
748 | * @par Example | |
749 | * To read into a single data buffer use the @ref buffer function as follows: | |
750 | * @code | |
751 | * boost::asio::async_read(s, boost::asio::buffer(data, size), handler); | |
752 | * @endcode | |
753 | * See the @ref buffer documentation for information on reading into multiple | |
754 | * buffers in one go, and how to use it with arrays, boost::array or | |
755 | * std::vector. | |
756 | * | |
757 | * @note This overload is equivalent to calling: | |
758 | * @code boost::asio::async_read( | |
759 | * s, buffers, | |
760 | * boost::asio::transfer_all(), | |
761 | * handler); @endcode | |
762 | */ | |
763 | template <typename AsyncReadStream, typename MutableBufferSequence, | |
92f5a8d4 TL |
764 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
765 | std::size_t)) ReadHandler | |
766 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( | |
767 | typename AsyncReadStream::executor_type)> | |
768 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, | |
7c673cae FG |
769 | void (boost::system::error_code, std::size_t)) |
770 | async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, | |
92f5a8d4 TL |
771 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler |
772 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( | |
773 | typename AsyncReadStream::executor_type), | |
b32b8144 FG |
774 | typename enable_if< |
775 | is_mutable_buffer_sequence<MutableBufferSequence>::value | |
776 | >::type* = 0); | |
7c673cae FG |
777 | |
778 | /// Start an asynchronous operation to read a certain amount of data from a | |
779 | /// stream. | |
780 | /** | |
781 | * This function is used to asynchronously read a certain number of bytes of | |
782 | * data from a stream. The function call always returns immediately. The | |
783 | * asynchronous operation will continue until one of the following conditions is | |
784 | * true: | |
785 | * | |
786 | * @li The supplied buffers are full. That is, the bytes transferred is equal to | |
787 | * the sum of the buffer sizes. | |
788 | * | |
789 | * @li The completion_condition function object returns 0. | |
790 | * | |
791 | * @param s The stream from which the data is to be read. The type must support | |
792 | * the AsyncReadStream concept. | |
793 | * | |
794 | * @param buffers One or more buffers into which the data will be read. The sum | |
795 | * of the buffer sizes indicates the maximum number of bytes to read from the | |
796 | * stream. Although the buffers object may be copied as necessary, ownership of | |
797 | * the underlying memory blocks is retained by the caller, which must guarantee | |
798 | * that they remain valid until the handler is called. | |
799 | * | |
800 | * @param completion_condition The function object to be called to determine | |
801 | * whether the read operation is complete. The signature of the function object | |
802 | * must be: | |
803 | * @code std::size_t completion_condition( | |
804 | * // Result of latest async_read_some operation. | |
805 | * const boost::system::error_code& error, | |
806 | * | |
807 | * // Number of bytes transferred so far. | |
808 | * std::size_t bytes_transferred | |
809 | * ); @endcode | |
810 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
811 | * return value indicates the maximum number of bytes to be read on the next | |
812 | * call to the stream's async_read_some function. | |
813 | * | |
814 | * @param handler The handler to be called when the read operation completes. | |
815 | * Copies will be made of the handler as required. The function signature of the | |
816 | * handler must be: | |
817 | * @code void handler( | |
818 | * const boost::system::error_code& error, // Result of operation. | |
819 | * | |
820 | * std::size_t bytes_transferred // Number of bytes copied into the | |
821 | * // buffers. If an error occurred, | |
822 | * // this will be the number of | |
823 | * // bytes successfully transferred | |
824 | * // prior to the error. | |
825 | * ); @endcode | |
826 | * Regardless of whether the asynchronous operation completes immediately or | |
92f5a8d4 TL |
827 | * not, the handler will not be invoked from within this function. On |
828 | * immediate completion, invocation of the handler will be performed in a | |
829 | * manner equivalent to using boost::asio::post(). | |
7c673cae FG |
830 | * |
831 | * @par Example | |
832 | * To read into a single data buffer use the @ref buffer function as follows: | |
833 | * @code boost::asio::async_read(s, | |
834 | * boost::asio::buffer(data, size), | |
835 | * boost::asio::transfer_at_least(32), | |
836 | * handler); @endcode | |
837 | * See the @ref buffer documentation for information on reading into multiple | |
838 | * buffers in one go, and how to use it with arrays, boost::array or | |
839 | * std::vector. | |
840 | */ | |
92f5a8d4 TL |
841 | template <typename AsyncReadStream, |
842 | typename MutableBufferSequence, typename CompletionCondition, | |
843 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, | |
844 | std::size_t)) ReadHandler | |
845 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( | |
846 | typename AsyncReadStream::executor_type)> | |
847 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, | |
7c673cae FG |
848 | void (boost::system::error_code, std::size_t)) |
849 | async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, | |
850 | CompletionCondition completion_condition, | |
92f5a8d4 TL |
851 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler |
852 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( | |
853 | typename AsyncReadStream::executor_type), | |
b32b8144 FG |
854 | typename enable_if< |
855 | is_mutable_buffer_sequence<MutableBufferSequence>::value | |
856 | >::type* = 0); | |
857 | ||
92f5a8d4 TL |
858 | #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
859 | ||
b32b8144 FG |
860 | /// Start an asynchronous operation to read a certain amount of data from a |
861 | /// stream. | |
862 | /** | |
863 | * This function is used to asynchronously read a certain number of bytes of | |
864 | * data from a stream. The function call always returns immediately. The | |
865 | * asynchronous operation will continue until one of the following conditions is | |
866 | * true: | |
867 | * | |
868 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
869 | * maximum size). | |
870 | * | |
871 | * @li An error occurred. | |
872 | * | |
873 | * This operation is implemented in terms of zero or more calls to the stream's | |
874 | * async_read_some function, and is known as a <em>composed operation</em>. The | |
875 | * program must ensure that the stream performs no other read operations (such | |
876 | * as async_read, the stream's async_read_some function, or any other composed | |
877 | * operations that perform reads) until this operation completes. | |
878 | * | |
879 | * @param s The stream from which the data is to be read. The type must support | |
880 | * the AsyncReadStream concept. | |
881 | * | |
882 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
883 | * Although the buffers object may be copied as necessary, ownership of the | |
884 | * underlying memory blocks is retained by the caller, which must guarantee | |
885 | * that they remain valid until the handler is called. | |
886 | * | |
887 | * @param handler The handler to be called when the read operation completes. | |
888 | * Copies will be made of the handler as required. The function signature of the | |
889 | * handler must be: | |
890 | * @code void handler( | |
891 | * const boost::system::error_code& error, // Result of operation. | |
892 | * | |
893 | * std::size_t bytes_transferred // Number of bytes copied into the | |
894 | * // buffers. If an error occurred, | |
895 | * // this will be the number of | |
896 | * // bytes successfully transferred | |
897 | * // prior to the error. | |
898 | * ); @endcode | |
899 | * Regardless of whether the asynchronous operation completes immediately or | |
92f5a8d4 TL |
900 | * not, the handler will not be invoked from within this function. On |
901 | * immediate completion, invocation of the handler will be performed in a | |
902 | * manner equivalent to using boost::asio::post(). | |
b32b8144 FG |
903 | * |
904 | * @note This overload is equivalent to calling: | |
905 | * @code boost::asio::async_read( | |
906 | * s, buffers, | |
907 | * boost::asio::transfer_all(), | |
908 | * handler); @endcode | |
909 | */ | |
92f5a8d4 TL |
910 | template <typename AsyncReadStream, typename DynamicBuffer_v1, |
911 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, | |
912 | std::size_t)) ReadHandler | |
913 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( | |
914 | typename AsyncReadStream::executor_type)> | |
915 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, | |
b32b8144 FG |
916 | void (boost::system::error_code, std::size_t)) |
917 | async_read(AsyncReadStream& s, | |
92f5a8d4 TL |
918 | BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, |
919 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler | |
920 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( | |
921 | typename AsyncReadStream::executor_type), | |
b32b8144 | 922 | typename enable_if< |
92f5a8d4 TL |
923 | is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value |
924 | && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value | |
b32b8144 FG |
925 | >::type* = 0); |
926 | ||
927 | /// Start an asynchronous operation to read a certain amount of data from a | |
928 | /// stream. | |
929 | /** | |
930 | * This function is used to asynchronously read a certain number of bytes of | |
931 | * data from a stream. The function call always returns immediately. The | |
932 | * asynchronous operation will continue until one of the following conditions is | |
933 | * true: | |
934 | * | |
935 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
936 | * maximum size). | |
937 | * | |
938 | * @li The completion_condition function object returns 0. | |
939 | * | |
940 | * This operation is implemented in terms of zero or more calls to the stream's | |
941 | * async_read_some function, and is known as a <em>composed operation</em>. The | |
942 | * program must ensure that the stream performs no other read operations (such | |
943 | * as async_read, the stream's async_read_some function, or any other composed | |
944 | * operations that perform reads) until this operation completes. | |
945 | * | |
946 | * @param s The stream from which the data is to be read. The type must support | |
947 | * the AsyncReadStream concept. | |
948 | * | |
949 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
950 | * Although the buffers object may be copied as necessary, ownership of the | |
951 | * underlying memory blocks is retained by the caller, which must guarantee | |
952 | * that they remain valid until the handler is called. | |
953 | * | |
954 | * @param completion_condition The function object to be called to determine | |
955 | * whether the read operation is complete. The signature of the function object | |
956 | * must be: | |
957 | * @code std::size_t completion_condition( | |
958 | * // Result of latest async_read_some operation. | |
959 | * const boost::system::error_code& error, | |
960 | * | |
961 | * // Number of bytes transferred so far. | |
962 | * std::size_t bytes_transferred | |
963 | * ); @endcode | |
964 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
965 | * return value indicates the maximum number of bytes to be read on the next | |
966 | * call to the stream's async_read_some function. | |
967 | * | |
968 | * @param handler The handler to be called when the read operation completes. | |
969 | * Copies will be made of the handler as required. The function signature of the | |
970 | * handler must be: | |
971 | * @code void handler( | |
972 | * const boost::system::error_code& error, // Result of operation. | |
973 | * | |
974 | * std::size_t bytes_transferred // Number of bytes copied into the | |
975 | * // buffers. If an error occurred, | |
976 | * // this will be the number of | |
977 | * // bytes successfully transferred | |
978 | * // prior to the error. | |
979 | * ); @endcode | |
980 | * Regardless of whether the asynchronous operation completes immediately or | |
92f5a8d4 TL |
981 | * not, the handler will not be invoked from within this function. On |
982 | * immediate completion, invocation of the handler will be performed in a | |
983 | * manner equivalent to using boost::asio::post(). | |
b32b8144 | 984 | */ |
92f5a8d4 TL |
985 | template <typename AsyncReadStream, |
986 | typename DynamicBuffer_v1, typename CompletionCondition, | |
987 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, | |
988 | std::size_t)) ReadHandler | |
989 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( | |
990 | typename AsyncReadStream::executor_type)> | |
991 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, | |
b32b8144 FG |
992 | void (boost::system::error_code, std::size_t)) |
993 | async_read(AsyncReadStream& s, | |
92f5a8d4 | 994 | BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, |
b32b8144 | 995 | CompletionCondition completion_condition, |
92f5a8d4 TL |
996 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler |
997 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( | |
998 | typename AsyncReadStream::executor_type), | |
b32b8144 | 999 | typename enable_if< |
92f5a8d4 TL |
1000 | is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value |
1001 | && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value | |
b32b8144 | 1002 | >::type* = 0); |
7c673cae | 1003 | |
b32b8144 | 1004 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) |
7c673cae FG |
1005 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
1006 | ||
1007 | /// Start an asynchronous operation to read a certain amount of data from a | |
1008 | /// stream. | |
1009 | /** | |
1010 | * This function is used to asynchronously read a certain number of bytes of | |
1011 | * data from a stream. The function call always returns immediately. The | |
1012 | * asynchronous operation will continue until one of the following conditions is | |
1013 | * true: | |
1014 | * | |
1015 | * @li The supplied buffer is full (that is, it has reached maximum size). | |
1016 | * | |
1017 | * @li An error occurred. | |
1018 | * | |
1019 | * This operation is implemented in terms of zero or more calls to the stream's | |
1020 | * async_read_some function, and is known as a <em>composed operation</em>. The | |
1021 | * program must ensure that the stream performs no other read operations (such | |
1022 | * as async_read, the stream's async_read_some function, or any other composed | |
1023 | * operations that perform reads) until this operation completes. | |
1024 | * | |
1025 | * @param s The stream from which the data is to be read. The type must support | |
1026 | * the AsyncReadStream concept. | |
1027 | * | |
1028 | * @param b A basic_streambuf object into which the data will be read. Ownership | |
1029 | * of the streambuf is retained by the caller, which must guarantee that it | |
1030 | * remains valid until the handler is called. | |
1031 | * | |
1032 | * @param handler The handler to be called when the read operation completes. | |
1033 | * Copies will be made of the handler as required. The function signature of the | |
1034 | * handler must be: | |
1035 | * @code void handler( | |
1036 | * const boost::system::error_code& error, // Result of operation. | |
1037 | * | |
1038 | * std::size_t bytes_transferred // Number of bytes copied into the | |
1039 | * // buffers. If an error occurred, | |
1040 | * // this will be the number of | |
1041 | * // bytes successfully transferred | |
1042 | * // prior to the error. | |
1043 | * ); @endcode | |
1044 | * Regardless of whether the asynchronous operation completes immediately or | |
92f5a8d4 TL |
1045 | * not, the handler will not be invoked from within this function. On |
1046 | * immediate completion, invocation of the handler will be performed in a | |
1047 | * manner equivalent to using boost::asio::post(). | |
7c673cae FG |
1048 | * |
1049 | * @note This overload is equivalent to calling: | |
1050 | * @code boost::asio::async_read( | |
1051 | * s, b, | |
1052 | * boost::asio::transfer_all(), | |
1053 | * handler); @endcode | |
1054 | */ | |
92f5a8d4 TL |
1055 | template <typename AsyncReadStream, typename Allocator, |
1056 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, | |
1057 | std::size_t)) ReadHandler | |
1058 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( | |
1059 | typename AsyncReadStream::executor_type)> | |
1060 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, | |
7c673cae FG |
1061 | void (boost::system::error_code, std::size_t)) |
1062 | async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b, | |
92f5a8d4 TL |
1063 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler |
1064 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( | |
1065 | typename AsyncReadStream::executor_type)); | |
7c673cae FG |
1066 | |
1067 | /// Start an asynchronous operation to read a certain amount of data from a | |
1068 | /// stream. | |
1069 | /** | |
1070 | * This function is used to asynchronously read a certain number of bytes of | |
1071 | * data from a stream. The function call always returns immediately. The | |
1072 | * asynchronous operation will continue until one of the following conditions is | |
1073 | * true: | |
1074 | * | |
1075 | * @li The supplied buffer is full (that is, it has reached maximum size). | |
1076 | * | |
1077 | * @li The completion_condition function object returns 0. | |
1078 | * | |
1079 | * This operation is implemented in terms of zero or more calls to the stream's | |
1080 | * async_read_some function, and is known as a <em>composed operation</em>. The | |
1081 | * program must ensure that the stream performs no other read operations (such | |
1082 | * as async_read, the stream's async_read_some function, or any other composed | |
1083 | * operations that perform reads) until this operation completes. | |
1084 | * | |
1085 | * @param s The stream from which the data is to be read. The type must support | |
1086 | * the AsyncReadStream concept. | |
1087 | * | |
1088 | * @param b A basic_streambuf object into which the data will be read. Ownership | |
1089 | * of the streambuf is retained by the caller, which must guarantee that it | |
1090 | * remains valid until the handler is called. | |
1091 | * | |
1092 | * @param completion_condition The function object to be called to determine | |
1093 | * whether the read operation is complete. The signature of the function object | |
1094 | * must be: | |
1095 | * @code std::size_t completion_condition( | |
1096 | * // Result of latest async_read_some operation. | |
1097 | * const boost::system::error_code& error, | |
1098 | * | |
1099 | * // Number of bytes transferred so far. | |
1100 | * std::size_t bytes_transferred | |
1101 | * ); @endcode | |
1102 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
1103 | * return value indicates the maximum number of bytes to be read on the next | |
1104 | * call to the stream's async_read_some function. | |
1105 | * | |
1106 | * @param handler The handler to be called when the read operation completes. | |
1107 | * Copies will be made of the handler as required. The function signature of the | |
1108 | * handler must be: | |
1109 | * @code void handler( | |
1110 | * const boost::system::error_code& error, // Result of operation. | |
1111 | * | |
1112 | * std::size_t bytes_transferred // Number of bytes copied into the | |
1113 | * // buffers. If an error occurred, | |
1114 | * // this will be the number of | |
1115 | * // bytes successfully transferred | |
1116 | * // prior to the error. | |
1117 | * ); @endcode | |
1118 | * Regardless of whether the asynchronous operation completes immediately or | |
92f5a8d4 TL |
1119 | * not, the handler will not be invoked from within this function. On |
1120 | * immediate completion, invocation of the handler will be performed in a | |
1121 | * manner equivalent to using boost::asio::post(). | |
7c673cae | 1122 | */ |
92f5a8d4 TL |
1123 | template <typename AsyncReadStream, |
1124 | typename Allocator, typename CompletionCondition, | |
1125 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, | |
1126 | std::size_t)) ReadHandler | |
1127 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( | |
1128 | typename AsyncReadStream::executor_type)> | |
1129 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, | |
7c673cae FG |
1130 | void (boost::system::error_code, std::size_t)) |
1131 | async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b, | |
1132 | CompletionCondition completion_condition, | |
92f5a8d4 TL |
1133 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler |
1134 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( | |
1135 | typename AsyncReadStream::executor_type)); | |
7c673cae FG |
1136 | |
1137 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) | |
b32b8144 | 1138 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) |
92f5a8d4 TL |
1139 | #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
1140 | ||
1141 | /// Start an asynchronous operation to read a certain amount of data from a | |
1142 | /// stream. | |
1143 | /** | |
1144 | * This function is used to asynchronously read a certain number of bytes of | |
1145 | * data from a stream. The function call always returns immediately. The | |
1146 | * asynchronous operation will continue until one of the following conditions is | |
1147 | * true: | |
1148 | * | |
1149 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
1150 | * maximum size). | |
1151 | * | |
1152 | * @li An error occurred. | |
1153 | * | |
1154 | * This operation is implemented in terms of zero or more calls to the stream's | |
1155 | * async_read_some function, and is known as a <em>composed operation</em>. The | |
1156 | * program must ensure that the stream performs no other read operations (such | |
1157 | * as async_read, the stream's async_read_some function, or any other composed | |
1158 | * operations that perform reads) until this operation completes. | |
1159 | * | |
1160 | * @param s The stream from which the data is to be read. The type must support | |
1161 | * the AsyncReadStream concept. | |
1162 | * | |
1163 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
1164 | * Although the buffers object may be copied as necessary, ownership of the | |
1165 | * underlying memory blocks is retained by the caller, which must guarantee | |
1166 | * that they remain valid until the handler is called. | |
1167 | * | |
1168 | * @param handler The handler to be called when the read operation completes. | |
1169 | * Copies will be made of the handler as required. The function signature of the | |
1170 | * handler must be: | |
1171 | * @code void handler( | |
1172 | * const boost::system::error_code& error, // Result of operation. | |
1173 | * | |
1174 | * std::size_t bytes_transferred // Number of bytes copied into the | |
1175 | * // buffers. If an error occurred, | |
1176 | * // this will be the number of | |
1177 | * // bytes successfully transferred | |
1178 | * // prior to the error. | |
1179 | * ); @endcode | |
1180 | * Regardless of whether the asynchronous operation completes immediately or | |
1181 | * not, the handler will not be invoked from within this function. On | |
1182 | * immediate completion, invocation of the handler will be performed in a | |
1183 | * manner equivalent to using boost::asio::post(). | |
1184 | * | |
1185 | * @note This overload is equivalent to calling: | |
1186 | * @code boost::asio::async_read( | |
1187 | * s, buffers, | |
1188 | * boost::asio::transfer_all(), | |
1189 | * handler); @endcode | |
1190 | */ | |
1191 | template <typename AsyncReadStream, typename DynamicBuffer_v2, | |
1192 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, | |
1193 | std::size_t)) ReadHandler | |
1194 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( | |
1195 | typename AsyncReadStream::executor_type)> | |
1196 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, | |
1197 | void (boost::system::error_code, std::size_t)) | |
1198 | async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, | |
1199 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler | |
1200 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( | |
1201 | typename AsyncReadStream::executor_type), | |
1202 | typename enable_if< | |
1203 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value | |
1204 | >::type* = 0); | |
1205 | ||
1206 | /// Start an asynchronous operation to read a certain amount of data from a | |
1207 | /// stream. | |
1208 | /** | |
1209 | * This function is used to asynchronously read a certain number of bytes of | |
1210 | * data from a stream. The function call always returns immediately. The | |
1211 | * asynchronous operation will continue until one of the following conditions is | |
1212 | * true: | |
1213 | * | |
1214 | * @li The specified dynamic buffer sequence is full (that is, it has reached | |
1215 | * maximum size). | |
1216 | * | |
1217 | * @li The completion_condition function object returns 0. | |
1218 | * | |
1219 | * This operation is implemented in terms of zero or more calls to the stream's | |
1220 | * async_read_some function, and is known as a <em>composed operation</em>. The | |
1221 | * program must ensure that the stream performs no other read operations (such | |
1222 | * as async_read, the stream's async_read_some function, or any other composed | |
1223 | * operations that perform reads) until this operation completes. | |
1224 | * | |
1225 | * @param s The stream from which the data is to be read. The type must support | |
1226 | * the AsyncReadStream concept. | |
1227 | * | |
1228 | * @param buffers The dynamic buffer sequence into which the data will be read. | |
1229 | * Although the buffers object may be copied as necessary, ownership of the | |
1230 | * underlying memory blocks is retained by the caller, which must guarantee | |
1231 | * that they remain valid until the handler is called. | |
1232 | * | |
1233 | * @param completion_condition The function object to be called to determine | |
1234 | * whether the read operation is complete. The signature of the function object | |
1235 | * must be: | |
1236 | * @code std::size_t completion_condition( | |
1237 | * // Result of latest async_read_some operation. | |
1238 | * const boost::system::error_code& error, | |
1239 | * | |
1240 | * // Number of bytes transferred so far. | |
1241 | * std::size_t bytes_transferred | |
1242 | * ); @endcode | |
1243 | * A return value of 0 indicates that the read operation is complete. A non-zero | |
1244 | * return value indicates the maximum number of bytes to be read on the next | |
1245 | * call to the stream's async_read_some function. | |
1246 | * | |
1247 | * @param handler The handler to be called when the read operation completes. | |
1248 | * Copies will be made of the handler as required. The function signature of the | |
1249 | * handler must be: | |
1250 | * @code void handler( | |
1251 | * const boost::system::error_code& error, // Result of operation. | |
1252 | * | |
1253 | * std::size_t bytes_transferred // Number of bytes copied into the | |
1254 | * // buffers. If an error occurred, | |
1255 | * // this will be the number of | |
1256 | * // bytes successfully transferred | |
1257 | * // prior to the error. | |
1258 | * ); @endcode | |
1259 | * Regardless of whether the asynchronous operation completes immediately or | |
1260 | * not, the handler will not be invoked from within this function. On | |
1261 | * immediate completion, invocation of the handler will be performed in a | |
1262 | * manner equivalent to using boost::asio::post(). | |
1263 | */ | |
1264 | template <typename AsyncReadStream, | |
1265 | typename DynamicBuffer_v2, typename CompletionCondition, | |
1266 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, | |
1267 | std::size_t)) ReadHandler | |
1268 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( | |
1269 | typename AsyncReadStream::executor_type)> | |
1270 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler, | |
1271 | void (boost::system::error_code, std::size_t)) | |
1272 | async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers, | |
1273 | CompletionCondition completion_condition, | |
1274 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler | |
1275 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( | |
1276 | typename AsyncReadStream::executor_type), | |
1277 | typename enable_if< | |
1278 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value | |
1279 | >::type* = 0); | |
7c673cae FG |
1280 | |
1281 | /*@}*/ | |
1282 | ||
1283 | } // namespace asio | |
1284 | } // namespace boost | |
1285 | ||
1286 | #include <boost/asio/detail/pop_options.hpp> | |
1287 | ||
1288 | #include <boost/asio/impl/read.hpp> | |
1289 | ||
1290 | #endif // BOOST_ASIO_READ_HPP |