2 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
4 // Distributed under the Boost Software License, Version 1.0. (See accompanying
5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 // Official repository: https://github.com/boostorg/beast
10 #ifndef BOOST_BEAST_DETAIL_READ_HPP
11 #define BOOST_BEAST_DETAIL_READ_HPP
13 #include <boost/beast/core/detail/config.hpp>
14 #include <boost/beast/core/error.hpp>
15 #include <boost/beast/core/stream_traits.hpp>
16 #include <boost/beast/core/detail/is_invocable.hpp>
17 #include <boost/asio/async_result.hpp>
24 //------------------------------------------------------------------------------
26 /** Read data into a dynamic buffer from a stream until a condition is met.
28 This function is used to read from a stream into a dynamic buffer until
29 a condition is met. The call will block until one of the following is true:
31 @li The specified dynamic buffer sequence is full (that is, it has
32 reached its currently configured maximum size).
34 @li The `completion_condition` function object returns 0.
36 This operation is implemented in terms of zero or more calls to the
37 stream's `read_some` function.
39 @param stream The stream from which the data is to be read. The type
40 must support the <em>SyncReadStream</em> requirements.
42 @param buffer The dynamic buffer sequence into which the data will be read.
44 @param completion_condition The function object to be called to determine
45 whether the read operation is complete. The function object must be invocable
50 // Modifiable result of latest read_some operation.
53 // Number of bytes transferred so far.
54 std::size_t bytes_transferred
56 // The dynamic buffer used to store the bytes read
60 A non-zero return value indicates the maximum number of bytes to be read on
61 the next call to the stream's `read_some` function. A return value of 0
62 from the completion condition indicates that the read operation is complete;
63 in this case the optionally modifiable error passed to the completion
64 condition will be delivered to the caller as an exception.
66 @returns The number of bytes transferred from the stream.
68 @throws net::system_error Thrown on failure.
73 class CompletionCondition
74 #if ! BOOST_BEAST_DOXYGEN
75 , class = typename std::enable_if<
76 is_sync_read_stream<SyncReadStream>::value &&
77 net::is_dynamic_buffer<DynamicBuffer>::value &&
78 detail::is_invocable<CompletionCondition,
79 void(error_code&, std::size_t, DynamicBuffer&)>::value
85 SyncReadStream& stream,
86 DynamicBuffer& buffer,
87 CompletionCondition completion_condition);
89 /** Read data into a dynamic buffer from a stream until a condition is met.
91 This function is used to read from a stream into a dynamic buffer until
92 a condition is met. The call will block until one of the following is true:
94 @li The specified dynamic buffer sequence is full (that is, it has
95 reached its currently configured maximum size).
97 @li The `completion_condition` function object returns 0.
99 This operation is implemented in terms of zero or more calls to the
100 stream's `read_some` function.
102 @param stream The stream from which the data is to be read. The type
103 must support the <em>SyncReadStream</em> requirements.
105 @param buffer The dynamic buffer sequence into which the data will be read.
107 @param completion_condition The function object to be called to determine
108 whether the read operation is complete. The function object must be invocable
112 completion_condition(
113 // Modifiable result of latest read_some operation.
116 // Number of bytes transferred so far.
117 std::size_t bytes_transferred
119 // The dynamic buffer used to store the bytes read
120 DynamicBuffer& buffer
123 A non-zero return value indicates the maximum number of bytes to be read on
124 the next call to the stream's `read_some` function. A return value of 0
125 from the completion condition indicates that the read operation is complete;
126 in this case the optionally modifiable error passed to the completion
127 condition will be delivered to the caller.
129 @returns The number of bytes transferred from the stream.
132 class SyncReadStream,
134 class CompletionCondition
135 #if ! BOOST_BEAST_DOXYGEN
136 , class = typename std::enable_if<
137 is_sync_read_stream<SyncReadStream>::value &&
138 net::is_dynamic_buffer<DynamicBuffer>::value &&
139 detail::is_invocable<CompletionCondition,
140 void(error_code&, std::size_t, DynamicBuffer&)>::value
146 SyncReadStream& stream,
147 DynamicBuffer& buffer,
148 CompletionCondition completion_condition,
151 /** Asynchronously read data into a dynamic buffer from a stream until a condition is met.
153 This function is used to asynchronously read from a stream into a dynamic
154 buffer until a condition is met. The function call always returns immediately.
155 The asynchronous operation will continue until one of the following is true:
157 @li The specified dynamic buffer sequence is full (that is, it has
158 reached its currently configured maximum size).
160 @li The `completion_condition` function object returns 0.
162 This operation is implemented in terms of zero or more calls to the stream's
163 `async_read_some` function, and is known as a <em>composed operation</em>. The
164 program must ensure that the stream performs no other read operations (such
165 as `async_read`, the stream's `async_read_some` function, or any other composed
166 operations that perform reads) until this operation completes.
168 @param stream The stream from which the data is to be read. The type must
169 support the <em>AsyncReadStream</em> requirements.
171 @param buffer The dynamic buffer sequence into which the data will be read.
172 Ownership of the object is retained by the caller, which must guarantee
173 that it remains valid until the handler is called.
175 @param completion_condition The function object to be called to determine
176 whether the read operation is complete. The function object must be invocable
180 completion_condition(
181 // Modifiable result of latest async_read_some operation.
184 // Number of bytes transferred so far.
185 std::size_t bytes_transferred,
187 // The dynamic buffer used to store the bytes read
188 DynamicBuffer& buffer
191 A non-zero return value indicates the maximum number of bytes to be read on
192 the next call to the stream's `async_read_some` function. A return value of 0
193 from the completion condition indicates that the read operation is complete;
194 in this case the optionally modifiable error passed to the completion
195 condition will be delivered to the completion handler.
197 @param handler The completion handler to invoke when the operation
198 completes. The implementation takes ownership of the handler by
199 performing a decay-copy. The equivalent function signature of
204 error_code const& ec, // Result of operation.
206 std::size_t bytes_transferred // Number of bytes copied into
207 // the dynamic buffer. If an error
208 // occurred, this will be the number
209 // of bytes successfully transferred
210 // prior to the error.
213 Regardless of whether the asynchronous operation completes
214 immediately or not, the handler will not be invoked from within
215 this function. Invocation of the handler will be performed in a
216 manner equivalent to using `net::post`.
219 class AsyncReadStream,
221 class CompletionCondition,
223 #if ! BOOST_BEAST_DOXYGEN
224 , class = typename std::enable_if<
225 is_async_read_stream<AsyncReadStream>::value &&
226 net::is_dynamic_buffer<DynamicBuffer>::value &&
227 detail::is_invocable<CompletionCondition,
228 void(error_code&, std::size_t, DynamicBuffer&)>::value
232 BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
234 AsyncReadStream& stream,
235 DynamicBuffer& buffer,
236 CompletionCondition&& completion_condition,
237 ReadHandler&& handler);
243 #include <boost/beast/core/detail/impl/read.hpp>