1 | // |
2 | // read.hpp |
3 | // ~~~~~~~~ |
4 | // |
5 | // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
6 | // |
7 | // Distributed under the Boost Software License, Version 1.0. (See accompanying |
8 | // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
9 | // |
10 | |
11 | #ifndef BOOST_ASIO_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> |
21 | #include <boost/asio/basic_streambuf_fwd.hpp> |
22 | #include <boost/asio/error.hpp> |
23 | |
24 | #include <boost/asio/detail/push_options.hpp> |
25 | |
26 | namespace boost { |
27 | namespace asio { |
28 | |
29 | /** |
30 | * @defgroup read boost::asio::read |
31 | * |
32 | * @brief Attempt to read a certain amount of data from a stream before |
33 | * returning. |
34 | */ |
35 | /*@{*/ |
36 | |
37 | /// Attempt to read a certain amount of data from a stream before returning. |
38 | /** |
39 | * This function is used to read a certain number of bytes of data from a |
40 | * stream. The call will block until one of the following conditions is true: |
41 | * |
42 | * @li The supplied buffers are full. That is, the bytes transferred is equal to |
43 | * the sum of the buffer sizes. |
44 | * |
45 | * @li An error occurred. |
46 | * |
47 | * This operation is implemented in terms of zero or more calls to the stream's |
48 | * read_some function. |
49 | * |
50 | * @param s The stream from which the data is to be read. The type must support |
51 | * the SyncReadStream concept. |
52 | * |
53 | * @param buffers One or more buffers into which the data will be read. The sum |
54 | * of the buffer sizes indicates the maximum number of bytes to read from the |
55 | * stream. |
56 | * |
57 | * @returns The number of bytes transferred. |
58 | * |
59 | * @throws boost::system::system_error Thrown on failure. |
60 | * |
61 | * @par Example |
62 | * To read into a single data buffer use the @ref buffer function as follows: |
63 | * @code boost::asio::read(s, boost::asio::buffer(data, size)); @endcode |
64 | * See the @ref buffer documentation for information on reading into multiple |
65 | * buffers in one go, and how to use it with arrays, boost::array or |
66 | * std::vector. |
67 | * |
68 | * @note This overload is equivalent to calling: |
69 | * @code boost::asio::read( |
70 | * s, buffers, |
71 | * boost::asio::transfer_all()); @endcode |
72 | */ |
73 | template <typename SyncReadStream, typename MutableBufferSequence> |
74 | std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers); |
75 | |
76 | /// Attempt to read a certain amount of data from a stream before returning. |
77 | /** |
78 | * This function is used to read a certain number of bytes of data from a |
79 | * stream. The call will block until one of the following conditions is true: |
80 | * |
81 | * @li The supplied buffers are full. That is, the bytes transferred is equal to |
82 | * the sum of the buffer sizes. |
83 | * |
84 | * @li An error occurred. |
85 | * |
86 | * This operation is implemented in terms of zero or more calls to the stream's |
87 | * read_some function. |
88 | * |
89 | * @param s The stream from which the data is to be read. The type must support |
90 | * the SyncReadStream concept. |
91 | * |
92 | * @param buffers One or more buffers into which the data will be read. The sum |
93 | * of the buffer sizes indicates the maximum number of bytes to read from the |
94 | * stream. |
95 | * |
96 | * @param ec Set to indicate what error occurred, if any. |
97 | * |
98 | * @returns The number of bytes transferred. |
99 | * |
100 | * @par Example |
101 | * To read into a single data buffer use the @ref buffer function as follows: |
102 | * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode |
103 | * See the @ref buffer documentation for information on reading into multiple |
104 | * buffers in one go, and how to use it with arrays, boost::array or |
105 | * std::vector. |
106 | * |
107 | * @note This overload is equivalent to calling: |
108 | * @code boost::asio::read( |
109 | * s, buffers, |
110 | * boost::asio::transfer_all(), ec); @endcode |
111 | */ |
112 | template <typename SyncReadStream, typename MutableBufferSequence> |
113 | std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, |
114 | boost::system::error_code& ec); |
115 | |
116 | /// Attempt to read a certain amount of data from a stream before returning. |
117 | /** |
118 | * This function is used to read a certain number of bytes of data from a |
119 | * stream. The call will block until one of the following conditions is true: |
120 | * |
121 | * @li The supplied buffers are full. That is, the bytes transferred is equal to |
122 | * the sum of the buffer sizes. |
123 | * |
124 | * @li The completion_condition function object returns 0. |
125 | * |
126 | * This operation is implemented in terms of zero or more calls to the stream's |
127 | * read_some function. |
128 | * |
129 | * @param s The stream from which the data is to be read. The type must support |
130 | * the SyncReadStream concept. |
131 | * |
132 | * @param buffers One or more buffers into which the data will be read. The sum |
133 | * of the buffer sizes indicates the maximum number of bytes to read from the |
134 | * stream. |
135 | * |
136 | * @param completion_condition The function object to be called to determine |
137 | * whether the read operation is complete. The signature of the function object |
138 | * must be: |
139 | * @code std::size_t completion_condition( |
140 | * // Result of latest read_some operation. |
141 | * const boost::system::error_code& error, |
142 | * |
143 | * // Number of bytes transferred so far. |
144 | * std::size_t bytes_transferred |
145 | * ); @endcode |
146 | * A return value of 0 indicates that the read operation is complete. A non-zero |
147 | * return value indicates the maximum number of bytes to be read on the next |
148 | * call to the stream's read_some function. |
149 | * |
150 | * @returns The number of bytes transferred. |
151 | * |
152 | * @throws boost::system::system_error Thrown on failure. |
153 | * |
154 | * @par Example |
155 | * To read into a single data buffer use the @ref buffer function as follows: |
156 | * @code boost::asio::read(s, boost::asio::buffer(data, size), |
157 | * boost::asio::transfer_at_least(32)); @endcode |
158 | * See the @ref buffer documentation for information on reading into multiple |
159 | * buffers in one go, and how to use it with arrays, boost::array or |
160 | * std::vector. |
161 | */ |
162 | template <typename SyncReadStream, typename MutableBufferSequence, |
163 | typename CompletionCondition> |
164 | std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, |
165 | CompletionCondition completion_condition); |
166 | |
167 | /// Attempt to read a certain amount of data from a stream before returning. |
168 | /** |
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: |
171 | * |
172 | * @li The supplied buffers are full. That is, the bytes transferred is equal to |
173 | * the sum of the buffer sizes. |
174 | * |
175 | * @li The completion_condition function object returns 0. |
176 | * |
177 | * This operation is implemented in terms of zero or more calls to the stream's |
178 | * read_some function. |
179 | * |
180 | * @param s The stream from which the data is to be read. The type must support |
181 | * the SyncReadStream concept. |
182 | * |
183 | * @param buffers One or more buffers into which the data will be read. The sum |
184 | * of the buffer sizes indicates the maximum number of bytes to read from the |
185 | * stream. |
186 | * |
187 | * @param completion_condition The function object to be called to determine |
188 | * whether the read operation is complete. The signature of the function object |
189 | * must be: |
190 | * @code std::size_t completion_condition( |
191 | * // Result of latest read_some operation. |
192 | * const boost::system::error_code& error, |
193 | * |
194 | * // Number of bytes transferred so far. |
195 | * std::size_t bytes_transferred |
196 | * ); @endcode |
197 | * A return value of 0 indicates that the read operation is complete. A non-zero |
198 | * return value indicates the maximum number of bytes to be read on the next |
199 | * call to the stream's read_some function. |
200 | * |
201 | * @param ec Set to indicate what error occurred, if any. |
202 | * |
203 | * @returns The number of bytes read. If an error occurs, returns the total |
204 | * number of bytes successfully transferred prior to the error. |
205 | */ |
206 | template <typename SyncReadStream, typename MutableBufferSequence, |
207 | typename CompletionCondition> |
208 | std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, |
209 | CompletionCondition completion_condition, boost::system::error_code& ec); |
210 | |
211 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
212 | |
213 | /// Attempt to read a certain amount of data from a stream before returning. |
214 | /** |
215 | * This function is used to read a certain number of bytes of data from a |
216 | * stream. The call will block until one of the following conditions is true: |
217 | * |
218 | * @li The supplied buffer is full (that is, it has reached maximum size). |
219 | * |
220 | * @li An error occurred. |
221 | * |
222 | * This operation is implemented in terms of zero or more calls to the stream's |
223 | * read_some function. |
224 | * |
225 | * @param s The stream from which the data is to be read. The type must support |
226 | * the SyncReadStream concept. |
227 | * |
228 | * @param b The basic_streambuf object into which the data will be read. |
229 | * |
230 | * @returns The number of bytes transferred. |
231 | * |
232 | * @throws boost::system::system_error Thrown on failure. |
233 | * |
234 | * @note This overload is equivalent to calling: |
235 | * @code boost::asio::read( |
236 | * s, b, |
237 | * boost::asio::transfer_all()); @endcode |
238 | */ |
239 | template <typename SyncReadStream, typename Allocator> |
240 | std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b); |
241 | |
242 | /// Attempt to read a certain amount of data from a stream before returning. |
243 | /** |
244 | * This function is used to read a certain number of bytes of data from a |
245 | * stream. The call will block until one of the following conditions is true: |
246 | * |
247 | * @li The supplied buffer is full (that is, it has reached maximum size). |
248 | * |
249 | * @li An error occurred. |
250 | * |
251 | * This operation is implemented in terms of zero or more calls to the stream's |
252 | * read_some function. |
253 | * |
254 | * @param s The stream from which the data is to be read. The type must support |
255 | * the SyncReadStream concept. |
256 | * |
257 | * @param b The basic_streambuf object into which the data will be read. |
258 | * |
259 | * @param ec Set to indicate what error occurred, if any. |
260 | * |
261 | * @returns The number of bytes transferred. |
262 | * |
263 | * @note This overload is equivalent to calling: |
264 | * @code boost::asio::read( |
265 | * s, b, |
266 | * boost::asio::transfer_all(), ec); @endcode |
267 | */ |
268 | template <typename SyncReadStream, typename Allocator> |
269 | std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, |
270 | boost::system::error_code& ec); |
271 | |
272 | /// Attempt to read a certain amount of data from a stream before returning. |
273 | /** |
274 | * This function is used to read a certain number of bytes of data from a |
275 | * stream. The call will block until one of the following conditions is true: |
276 | * |
277 | * @li The supplied buffer is full (that is, it has reached maximum size). |
278 | * |
279 | * @li The completion_condition function object returns 0. |
280 | * |
281 | * This operation is implemented in terms of zero or more calls to the stream's |
282 | * read_some function. |
283 | * |
284 | * @param s The stream from which the data is to be read. The type must support |
285 | * the SyncReadStream concept. |
286 | * |
287 | * @param b The basic_streambuf object into which the data will be read. |
288 | * |
289 | * @param completion_condition The function object to be called to determine |
290 | * whether the read operation is complete. The signature of the function object |
291 | * must be: |
292 | * @code std::size_t completion_condition( |
293 | * // Result of latest read_some operation. |
294 | * const boost::system::error_code& error, |
295 | * |
296 | * // Number of bytes transferred so far. |
297 | * std::size_t bytes_transferred |
298 | * ); @endcode |
299 | * A return value of 0 indicates that the read operation is complete. A non-zero |
300 | * return value indicates the maximum number of bytes to be read on the next |
301 | * call to the stream's read_some function. |
302 | * |
303 | * @returns The number of bytes transferred. |
304 | * |
305 | * @throws boost::system::system_error Thrown on failure. |
306 | */ |
307 | template <typename SyncReadStream, typename Allocator, |
308 | typename CompletionCondition> |
309 | std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, |
310 | CompletionCondition completion_condition); |
311 | |
312 | /// Attempt to read a certain amount of data from a stream before returning. |
313 | /** |
314 | * This function is used to read a certain number of bytes of data from a |
315 | * stream. The call will block until one of the following conditions is true: |
316 | * |
317 | * @li The supplied buffer is full (that is, it has reached maximum size). |
318 | * |
319 | * @li The completion_condition function object returns 0. |
320 | * |
321 | * This operation is implemented in terms of zero or more calls to the stream's |
322 | * read_some function. |
323 | * |
324 | * @param s The stream from which the data is to be read. The type must support |
325 | * the SyncReadStream concept. |
326 | * |
327 | * @param b The basic_streambuf object into which the data will be read. |
328 | * |
329 | * @param completion_condition The function object to be called to determine |
330 | * whether the read operation is complete. The signature of the function object |
331 | * must be: |
332 | * @code std::size_t completion_condition( |
333 | * // Result of latest read_some operation. |
334 | * const boost::system::error_code& error, |
335 | * |
336 | * // Number of bytes transferred so far. |
337 | * std::size_t bytes_transferred |
338 | * ); @endcode |
339 | * A return value of 0 indicates that the read operation is complete. A non-zero |
340 | * return value indicates the maximum number of bytes to be read on the next |
341 | * call to the stream's read_some function. |
342 | * |
343 | * @param ec Set to indicate what error occurred, if any. |
344 | * |
345 | * @returns The number of bytes read. If an error occurs, returns the total |
346 | * number of bytes successfully transferred prior to the error. |
347 | */ |
348 | template <typename SyncReadStream, typename Allocator, |
349 | typename CompletionCondition> |
350 | std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b, |
351 | CompletionCondition completion_condition, boost::system::error_code& ec); |
352 | |
353 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) |
354 | |
355 | /*@}*/ |
356 | /** |
357 | * @defgroup async_read boost::asio::async_read |
358 | * |
359 | * @brief Start an asynchronous operation to read a certain amount of data from |
360 | * a stream. |
361 | */ |
362 | /*@{*/ |
363 | |
364 | /// Start an asynchronous operation to read a certain amount of data from a |
365 | /// stream. |
366 | /** |
367 | * This function is used to asynchronously read a certain number of bytes of |
368 | * data from a stream. The function call always returns immediately. The |
369 | * asynchronous operation will continue until one of the following conditions is |
370 | * true: |
371 | * |
372 | * @li The supplied buffers are full. That is, the bytes transferred is equal to |
373 | * the sum of the buffer sizes. |
374 | * |
375 | * @li An error occurred. |
376 | * |
377 | * This operation is implemented in terms of zero or more calls to the stream's |
378 | * async_read_some function, and is known as a <em>composed operation</em>. The |
379 | * program must ensure that the stream performs no other read operations (such |
380 | * as async_read, the stream's async_read_some function, or any other composed |
381 | * operations that perform reads) until this operation completes. |
382 | * |
383 | * @param s The stream from which the data is to be read. The type must support |
384 | * the AsyncReadStream concept. |
385 | * |
386 | * @param buffers One or more buffers into which the data will be read. The sum |
387 | * of the buffer sizes indicates the maximum number of bytes to read from the |
388 | * stream. Although the buffers object may be copied as necessary, ownership of |
389 | * the underlying memory blocks is retained by the caller, which must guarantee |
390 | * that they remain valid until the handler is called. |
391 | * |
392 | * @param handler The handler to be called when the read operation completes. |
393 | * Copies will be made of the handler as required. The function signature of the |
394 | * handler must be: |
395 | * @code void handler( |
396 | * const boost::system::error_code& error, // Result of operation. |
397 | * |
398 | * std::size_t bytes_transferred // Number of bytes copied into the |
399 | * // buffers. If an error occurred, |
400 | * // this will be the number of |
401 | * // bytes successfully transferred |
402 | * // prior to the error. |
403 | * ); @endcode |
404 | * Regardless of whether the asynchronous operation completes immediately or |
405 | * not, the handler will not be invoked from within this function. Invocation of |
406 | * the handler will be performed in a manner equivalent to using |
407 | * boost::asio::io_service::post(). |
408 | * |
409 | * @par Example |
410 | * To read into a single data buffer use the @ref buffer function as follows: |
411 | * @code |
412 | * boost::asio::async_read(s, boost::asio::buffer(data, size), handler); |
413 | * @endcode |
414 | * See the @ref buffer documentation for information on reading into multiple |
415 | * buffers in one go, and how to use it with arrays, boost::array or |
416 | * std::vector. |
417 | * |
418 | * @note This overload is equivalent to calling: |
419 | * @code boost::asio::async_read( |
420 | * s, buffers, |
421 | * boost::asio::transfer_all(), |
422 | * handler); @endcode |
423 | */ |
424 | template <typename AsyncReadStream, typename MutableBufferSequence, |
425 | typename ReadHandler> |
426 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, |
427 | void (boost::system::error_code, std::size_t)) |
428 | async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, |
429 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler); |
430 | |
431 | /// Start an asynchronous operation to read a certain amount of data from a |
432 | /// stream. |
433 | /** |
434 | * This function is used to asynchronously read a certain number of bytes of |
435 | * data from a stream. The function call always returns immediately. The |
436 | * asynchronous operation will continue until one of the following conditions is |
437 | * true: |
438 | * |
439 | * @li The supplied buffers are full. That is, the bytes transferred is equal to |
440 | * the sum of the buffer sizes. |
441 | * |
442 | * @li The completion_condition function object returns 0. |
443 | * |
444 | * @param s The stream from which the data is to be read. The type must support |
445 | * the AsyncReadStream concept. |
446 | * |
447 | * @param buffers One or more buffers into which the data will be read. The sum |
448 | * of the buffer sizes indicates the maximum number of bytes to read from the |
449 | * stream. Although the buffers object may be copied as necessary, ownership of |
450 | * the underlying memory blocks is retained by the caller, which must guarantee |
451 | * that they remain valid until the handler is called. |
452 | * |
453 | * @param completion_condition The function object to be called to determine |
454 | * whether the read operation is complete. The signature of the function object |
455 | * must be: |
456 | * @code std::size_t completion_condition( |
457 | * // Result of latest async_read_some operation. |
458 | * const boost::system::error_code& error, |
459 | * |
460 | * // Number of bytes transferred so far. |
461 | * std::size_t bytes_transferred |
462 | * ); @endcode |
463 | * A return value of 0 indicates that the read operation is complete. A non-zero |
464 | * return value indicates the maximum number of bytes to be read on the next |
465 | * call to the stream's async_read_some function. |
466 | * |
467 | * @param handler The handler to be called when the read operation completes. |
468 | * Copies will be made of the handler as required. The function signature of the |
469 | * handler must be: |
470 | * @code void handler( |
471 | * const boost::system::error_code& error, // Result of operation. |
472 | * |
473 | * std::size_t bytes_transferred // Number of bytes copied into the |
474 | * // buffers. If an error occurred, |
475 | * // this will be the number of |
476 | * // bytes successfully transferred |
477 | * // prior to the error. |
478 | * ); @endcode |
479 | * Regardless of whether the asynchronous operation completes immediately or |
480 | * not, the handler will not be invoked from within this function. Invocation of |
481 | * the handler will be performed in a manner equivalent to using |
482 | * boost::asio::io_service::post(). |
483 | * |
484 | * @par Example |
485 | * To read into a single data buffer use the @ref buffer function as follows: |
486 | * @code boost::asio::async_read(s, |
487 | * boost::asio::buffer(data, size), |
488 | * boost::asio::transfer_at_least(32), |
489 | * handler); @endcode |
490 | * See the @ref buffer documentation for information on reading into multiple |
491 | * buffers in one go, and how to use it with arrays, boost::array or |
492 | * std::vector. |
493 | */ |
494 | template <typename AsyncReadStream, typename MutableBufferSequence, |
495 | typename CompletionCondition, typename ReadHandler> |
496 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, |
497 | void (boost::system::error_code, std::size_t)) |
498 | async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, |
499 | CompletionCondition completion_condition, |
500 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler); |
501 | |
502 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
503 | |
504 | /// Start an asynchronous operation to read a certain amount of data from a |
505 | /// stream. |
506 | /** |
507 | * This function is used to asynchronously read a certain number of bytes of |
508 | * data from a stream. The function call always returns immediately. The |
509 | * asynchronous operation will continue until one of the following conditions is |
510 | * true: |
511 | * |
512 | * @li The supplied buffer is full (that is, it has reached maximum size). |
513 | * |
514 | * @li An error occurred. |
515 | * |
516 | * This operation is implemented in terms of zero or more calls to the stream's |
517 | * async_read_some function, and is known as a <em>composed operation</em>. The |
518 | * program must ensure that the stream performs no other read operations (such |
519 | * as async_read, the stream's async_read_some function, or any other composed |
520 | * operations that perform reads) until this operation completes. |
521 | * |
522 | * @param s The stream from which the data is to be read. The type must support |
523 | * the AsyncReadStream concept. |
524 | * |
525 | * @param b A basic_streambuf object into which the data will be read. Ownership |
526 | * of the streambuf is retained by the caller, which must guarantee that it |
527 | * remains valid until the handler is called. |
528 | * |
529 | * @param handler The handler to be called when the read operation completes. |
530 | * Copies will be made of the handler as required. The function signature of the |
531 | * handler must be: |
532 | * @code void handler( |
533 | * const boost::system::error_code& error, // Result of operation. |
534 | * |
535 | * std::size_t bytes_transferred // Number of bytes copied into the |
536 | * // buffers. If an error occurred, |
537 | * // this will be the number of |
538 | * // bytes successfully transferred |
539 | * // prior to the error. |
540 | * ); @endcode |
541 | * Regardless of whether the asynchronous operation completes immediately or |
542 | * not, the handler will not be invoked from within this function. Invocation of |
543 | * the handler will be performed in a manner equivalent to using |
544 | * boost::asio::io_service::post(). |
545 | * |
546 | * @note This overload is equivalent to calling: |
547 | * @code boost::asio::async_read( |
548 | * s, b, |
549 | * boost::asio::transfer_all(), |
550 | * handler); @endcode |
551 | */ |
552 | template <typename AsyncReadStream, typename Allocator, typename ReadHandler> |
553 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, |
554 | void (boost::system::error_code, std::size_t)) |
555 | async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b, |
556 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler); |
557 | |
558 | /// Start an asynchronous operation to read a certain amount of data from a |
559 | /// stream. |
560 | /** |
561 | * This function is used to asynchronously read a certain number of bytes of |
562 | * data from a stream. The function call always returns immediately. The |
563 | * asynchronous operation will continue until one of the following conditions is |
564 | * true: |
565 | * |
566 | * @li The supplied buffer is full (that is, it has reached maximum size). |
567 | * |
568 | * @li The completion_condition function object returns 0. |
569 | * |
570 | * This operation is implemented in terms of zero or more calls to the stream's |
571 | * async_read_some function, and is known as a <em>composed operation</em>. The |
572 | * program must ensure that the stream performs no other read operations (such |
573 | * as async_read, the stream's async_read_some function, or any other composed |
574 | * operations that perform reads) until this operation completes. |
575 | * |
576 | * @param s The stream from which the data is to be read. The type must support |
577 | * the AsyncReadStream concept. |
578 | * |
579 | * @param b A basic_streambuf object into which the data will be read. Ownership |
580 | * of the streambuf is retained by the caller, which must guarantee that it |
581 | * remains valid until the handler is called. |
582 | * |
583 | * @param completion_condition The function object to be called to determine |
584 | * whether the read operation is complete. The signature of the function object |
585 | * must be: |
586 | * @code std::size_t completion_condition( |
587 | * // Result of latest async_read_some operation. |
588 | * const boost::system::error_code& error, |
589 | * |
590 | * // Number of bytes transferred so far. |
591 | * std::size_t bytes_transferred |
592 | * ); @endcode |
593 | * A return value of 0 indicates that the read operation is complete. A non-zero |
594 | * return value indicates the maximum number of bytes to be read on the next |
595 | * call to the stream's async_read_some function. |
596 | * |
597 | * @param handler The handler to be called when the read operation completes. |
598 | * Copies will be made of the handler as required. The function signature of the |
599 | * handler must be: |
600 | * @code void handler( |
601 | * const boost::system::error_code& error, // Result of operation. |
602 | * |
603 | * std::size_t bytes_transferred // Number of bytes copied into the |
604 | * // buffers. If an error occurred, |
605 | * // this will be the number of |
606 | * // bytes successfully transferred |
607 | * // prior to the error. |
608 | * ); @endcode |
609 | * Regardless of whether the asynchronous operation completes immediately or |
610 | * not, the handler will not be invoked from within this function. Invocation of |
611 | * the handler will be performed in a manner equivalent to using |
612 | * boost::asio::io_service::post(). |
613 | */ |
614 | template <typename AsyncReadStream, typename Allocator, |
615 | typename CompletionCondition, typename ReadHandler> |
616 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, |
617 | void (boost::system::error_code, std::size_t)) |
618 | async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b, |
619 | CompletionCondition completion_condition, |
620 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler); |
621 | |
622 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) |
623 | |
624 | /*@}*/ |
625 | |
626 | } // namespace asio |
627 | } // namespace boost |
628 | |
629 | #include <boost/asio/detail/pop_options.hpp> |
630 | |
631 | #include <boost/asio/impl/read.hpp> |
632 | |
633 | #endif // BOOST_ASIO_READ_HPP |
634 | |