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 ASIO_READ_HPP
12 #define ASIO_READ_HPP
13 
14 
15 #include "asio/detail/config.hpp"
16 #include <cstddef>
17 #include "asio/async_result.hpp"
18 #include "asio/basic_streambuf_fwd.hpp"
19 #include "asio/error.hpp"
20 
21 #include "asio/detail/push_options.hpp"
22 
23 namespace asio {
24 
25 /**
26  * @defgroup read asio::read
27  *
28  * @brief Attempt to read a certain amount of data from a stream before
29  * returning.
30  */
31 /*@{*/
32 
33 /// Attempt to read a certain amount of data from a stream before returning.
34 /**
35  * This function is used to read a certain number of bytes of data from a
36  * stream. The call will block until one of the following conditions is true:
37  *
38  * @li The supplied buffers are full. That is, the bytes transferred is equal to
39  * the sum of the buffer sizes.
40  *
41  * @li An error occurred.
42  *
43  * This operation is implemented in terms of zero or more calls to the stream's
44  * read_some function.
45  *
46  * @param s The stream from which the data is to be read. The type must support
47  * the SyncReadStream concept.
48  *
49  * @param buffers One or more buffers into which the data will be read. The sum
50  * of the buffer sizes indicates the maximum number of bytes to read from the
51  * stream.
52  *
53  * @returns The number of bytes transferred.
54  *
55  * @throws asio::system_error Thrown on failure.
56  *
57  * @par Example
58  * To read into a single data buffer use the @ref buffer function as follows:
59  * @code asio::read(s, asio::buffer(data, size)); @endcode
60  * See the @ref buffer documentation for information on reading into multiple
61  * buffers in one go, and how to use it with arrays, boost::array or
62  * std::vector.
63  *
64  * @note This overload is equivalent to calling:
65  * @code asio::read(
66  *     s, buffers,
67  *     asio::transfer_all()); @endcode
68  */
69 template <typename SyncReadStream, typename MutableBufferSequence>
70 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers);
71 
72 /// Attempt to read a certain amount of data from a stream before returning.
73 /**
74  * This function is used to read a certain number of bytes of data from a
75  * stream. The call will block until one of the following conditions is true:
76  *
77  * @li The supplied buffers are full. That is, the bytes transferred is equal to
78  * the sum of the buffer sizes.
79  *
80  * @li An error occurred.
81  *
82  * This operation is implemented in terms of zero or more calls to the stream's
83  * read_some function.
84  *
85  * @param s The stream from which the data is to be read. The type must support
86  * the SyncReadStream concept.
87  *
88  * @param buffers One or more buffers into which the data will be read. The sum
89  * of the buffer sizes indicates the maximum number of bytes to read from the
90  * stream.
91  *
92  * @param ec Set to indicate what error occurred, if any.
93  *
94  * @returns The number of bytes transferred.
95  *
96  * @par Example
97  * To read into a single data buffer use the @ref buffer function as follows:
98  * @code asio::read(s, asio::buffer(data, size), ec); @endcode
99  * See the @ref buffer documentation for information on reading into multiple
100  * buffers in one go, and how to use it with arrays, boost::array or
101  * std::vector.
102  *
103  * @note This overload is equivalent to calling:
104  * @code asio::read(
105  *     s, buffers,
106  *     asio::transfer_all(), ec); @endcode
107  */
108 template <typename SyncReadStream, typename MutableBufferSequence>
109 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
110     asio::error_code& ec);
111 
112 /// Attempt to read a certain amount of data from a stream before returning.
113 /**
114  * This function is used to read a certain number of bytes of data from a
115  * stream. The call will block until one of the following conditions is true:
116  *
117  * @li The supplied buffers are full. That is, the bytes transferred is equal to
118  * the sum of the buffer sizes.
119  *
120  * @li The completion_condition function object returns 0.
121  *
122  * This operation is implemented in terms of zero or more calls to the stream's
123  * read_some function.
124  *
125  * @param s The stream from which the data is to be read. The type must support
126  * the SyncReadStream concept.
127  *
128  * @param buffers One or more buffers into which the data will be read. The sum
129  * of the buffer sizes indicates the maximum number of bytes to read from the
130  * stream.
131  *
132  * @param completion_condition The function object to be called to determine
133  * whether the read operation is complete. The signature of the function object
134  * must be:
135  * @code std::size_t completion_condition(
136  *   // Result of latest read_some operation.
137  *   const asio::error_code& error,
138  *
139  *   // Number of bytes transferred so far.
140  *   std::size_t bytes_transferred
141  * ); @endcode
142  * A return value of 0 indicates that the read operation is complete. A non-zero
143  * return value indicates the maximum number of bytes to be read on the next
144  * call to the stream's read_some function.
145  *
146  * @returns The number of bytes transferred.
147  *
148  * @throws asio::system_error Thrown on failure.
149  *
150  * @par Example
151  * To read into a single data buffer use the @ref buffer function as follows:
152  * @code asio::read(s, asio::buffer(data, size),
153  *     asio::transfer_at_least(32)); @endcode
154  * See the @ref buffer documentation for information on reading into multiple
155  * buffers in one go, and how to use it with arrays, boost::array or
156  * std::vector.
157  */
158 template <typename SyncReadStream, typename MutableBufferSequence,
159   typename CompletionCondition>
160 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
161     CompletionCondition completion_condition);
162 
163 /// Attempt to read a certain amount of data from a stream before returning.
164 /**
165  * This function is used to read a certain number of bytes of data from a
166  * stream. The call will block until one of the following conditions is true:
167  *
168  * @li The supplied buffers are full. That is, the bytes transferred is equal to
169  * the sum of the buffer sizes.
170  *
171  * @li The completion_condition function object returns 0.
172  *
173  * This operation is implemented in terms of zero or more calls to the stream's
174  * read_some function.
175  *
176  * @param s The stream from which the data is to be read. The type must support
177  * the SyncReadStream concept.
178  *
179  * @param buffers One or more buffers into which the data will be read. The sum
180  * of the buffer sizes indicates the maximum number of bytes to read from the
181  * stream.
182  *
183  * @param completion_condition The function object to be called to determine
184  * whether the read operation is complete. The signature of the function object
185  * must be:
186  * @code std::size_t completion_condition(
187  *   // Result of latest read_some operation.
188  *   const asio::error_code& error,
189  *
190  *   // Number of bytes transferred so far.
191  *   std::size_t bytes_transferred
192  * ); @endcode
193  * A return value of 0 indicates that the read operation is complete. A non-zero
194  * return value indicates the maximum number of bytes to be read on the next
195  * call to the stream's read_some function.
196  *
197  * @param ec Set to indicate what error occurred, if any.
198  *
199  * @returns The number of bytes read. If an error occurs, returns the total
200  * number of bytes successfully transferred prior to the error.
201  */
202 template <typename SyncReadStream, typename MutableBufferSequence,
203     typename CompletionCondition>
204 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
205     CompletionCondition completion_condition, asio::error_code& ec);
206 
207 
208 /*@}*/
209 /**
210  * @defgroup async_read asio::async_read
211  *
212  * @brief Start an asynchronous operation to read a certain amount of data from
213  * a stream.
214  */
215 /*@{*/
216 
217 /// Start an asynchronous operation to read a certain amount of data from a
218 /// stream.
219 /**
220  * This function is used to asynchronously read a certain number of bytes of
221  * data from a stream. The function call always returns immediately. The
222  * asynchronous operation will continue until one of the following conditions is
223  * true:
224  *
225  * @li The supplied buffers are full. That is, the bytes transferred is equal to
226  * the sum of the buffer sizes.
227  *
228  * @li An error occurred.
229  *
230  * This operation is implemented in terms of zero or more calls to the stream's
231  * async_read_some function, and is known as a <em>composed operation</em>. The
232  * program must ensure that the stream performs no other read operations (such
233  * as async_read, the stream's async_read_some function, or any other composed
234  * operations that perform reads) until this operation completes.
235  *
236  * @param s The stream from which the data is to be read. The type must support
237  * the AsyncReadStream concept.
238  *
239  * @param buffers One or more buffers into which the data will be read. The sum
240  * of the buffer sizes indicates the maximum number of bytes to read from the
241  * stream. Although the buffers object may be copied as necessary, ownership of
242  * the underlying memory blocks is retained by the caller, which must guarantee
243  * that they remain valid until the handler is called.
244  *
245  * @param handler The handler to be called when the read operation completes.
246  * Copies will be made of the handler as required. The function signature of the
247  * handler must be:
248  * @code void handler(
249  *   const asio::error_code& error, // Result of operation.
250  *
251  *   std::size_t bytes_transferred           // Number of bytes copied into the
252  *                                           // buffers. If an error occurred,
253  *                                           // this will be the  number of
254  *                                           // bytes successfully transferred
255  *                                           // prior to the error.
256  * ); @endcode
257  * Regardless of whether the asynchronous operation completes immediately or
258  * not, the handler will not be invoked from within this function. Invocation of
259  * the handler will be performed in a manner equivalent to using
260  * asio::io_service::post().
261  *
262  * @par Example
263  * To read into a single data buffer use the @ref buffer function as follows:
264  * @code
265  * asio::async_read(s, asio::buffer(data, size), handler);
266  * @endcode
267  * See the @ref buffer documentation for information on reading into multiple
268  * buffers in one go, and how to use it with arrays, boost::array or
269  * std::vector.
270  *
271  * @note This overload is equivalent to calling:
272  * @code asio::async_read(
273  *     s, buffers,
274  *     asio::transfer_all(),
275  *     handler); @endcode
276  */
277 template <typename AsyncReadStream, typename MutableBufferSequence,
278     typename ReadHandler>
279 ASIO_INITFN_RESULT_TYPE(ReadHandler,
280     void (asio::error_code, std::size_t))
281 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
282     ASIO_MOVE_ARG(ReadHandler) handler);
283 
284 /// Start an asynchronous operation to read a certain amount of data from a
285 /// stream.
286 /**
287  * This function is used to asynchronously read a certain number of bytes of
288  * data from a stream. The function call always returns immediately. The
289  * asynchronous operation will continue until one of the following conditions is
290  * true:
291  *
292  * @li The supplied buffers are full. That is, the bytes transferred is equal to
293  * the sum of the buffer sizes.
294  *
295  * @li The completion_condition function object returns 0.
296  *
297  * @param s The stream from which the data is to be read. The type must support
298  * the AsyncReadStream concept.
299  *
300  * @param buffers One or more buffers into which the data will be read. The sum
301  * of the buffer sizes indicates the maximum number of bytes to read from the
302  * stream. Although the buffers object may be copied as necessary, ownership of
303  * the underlying memory blocks is retained by the caller, which must guarantee
304  * that they remain valid until the handler is called.
305  *
306  * @param completion_condition The function object to be called to determine
307  * whether the read operation is complete. The signature of the function object
308  * must be:
309  * @code std::size_t completion_condition(
310  *   // Result of latest async_read_some operation.
311  *   const asio::error_code& error,
312  *
313  *   // Number of bytes transferred so far.
314  *   std::size_t bytes_transferred
315  * ); @endcode
316  * A return value of 0 indicates that the read operation is complete. A non-zero
317  * return value indicates the maximum number of bytes to be read on the next
318  * call to the stream's async_read_some function.
319  *
320  * @param handler The handler to be called when the read operation completes.
321  * Copies will be made of the handler as required. The function signature of the
322  * handler must be:
323  * @code void handler(
324  *   const asio::error_code& error, // Result of operation.
325  *
326  *   std::size_t bytes_transferred           // Number of bytes copied into the
327  *                                           // buffers. If an error occurred,
328  *                                           // this will be the  number of
329  *                                           // bytes successfully transferred
330  *                                           // prior to the error.
331  * ); @endcode
332  * Regardless of whether the asynchronous operation completes immediately or
333  * not, the handler will not be invoked from within this function. Invocation of
334  * the handler will be performed in a manner equivalent to using
335  * asio::io_service::post().
336  *
337  * @par Example
338  * To read into a single data buffer use the @ref buffer function as follows:
339  * @code asio::async_read(s,
340  *     asio::buffer(data, size),
341  *     asio::transfer_at_least(32),
342  *     handler); @endcode
343  * See the @ref buffer documentation for information on reading into multiple
344  * buffers in one go, and how to use it with arrays, boost::array or
345  * std::vector.
346  */
347 template <typename AsyncReadStream, typename MutableBufferSequence,
348     typename CompletionCondition, typename ReadHandler>
349 ASIO_INITFN_RESULT_TYPE(ReadHandler,
350     void (asio::error_code, std::size_t))
351 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
352     CompletionCondition completion_condition,
353     ASIO_MOVE_ARG(ReadHandler) handler);
354 
355 
356 /*@}*/
357 
358 } // namespace asio
359 
360 #include "asio/detail/pop_options.hpp"
361 
362 #include "asio/impl/read.hpp"
363 
364 #endif // ASIO_READ_HPP
365