Statistics
| Revision:

root / tmp / org.txm.statsengine.r.core.win32 / res / win32 / library / BH / include / boost / asio / read.hpp @ 2486

History | View | Annotate | Download (25.2 kB)

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