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
23namespace 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 */
69template <typename SyncReadStream, typename MutableBufferSequence>
70std::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 */
108template <typename SyncReadStream, typename MutableBufferSequence>
109std::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 */
158template <typename SyncReadStream, typename MutableBufferSequence,
159  typename CompletionCondition>
160std::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 */
202template <typename SyncReadStream, typename MutableBufferSequence,
203    typename CompletionCondition>
204std::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 */
277template <typename AsyncReadStream, typename MutableBufferSequence,
278    typename ReadHandler>
279ASIO_INITFN_RESULT_TYPE(ReadHandler,
280    void (asio::error_code, std::size_t))
281async_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 */
347template <typename AsyncReadStream, typename MutableBufferSequence,
348    typename CompletionCondition, typename ReadHandler>
349ASIO_INITFN_RESULT_TYPE(ReadHandler,
350    void (asio::error_code, std::size_t))
351async_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