]>
Commit | Line | Data |
---|---|---|
92f5a8d4 TL |
1 | // |
2 | // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) | |
3 | // | |
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) | |
6 | // | |
7 | // Official repository: https://github.com/boostorg/beast | |
8 | // | |
9 | ||
10 | #ifndef BOOST_BEAST_DETAIL_READ_HPP | |
11 | #define BOOST_BEAST_DETAIL_READ_HPP | |
12 | ||
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> | |
18 | #include <cstdlib> | |
19 | ||
20 | namespace boost { | |
21 | namespace beast { | |
22 | namespace detail { | |
23 | ||
24 | //------------------------------------------------------------------------------ | |
25 | ||
26 | /** Read data into a dynamic buffer from a stream until a condition is met. | |
27 | ||
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: | |
30 | ||
31 | @li The specified dynamic buffer sequence is full (that is, it has | |
32 | reached its currently configured maximum size). | |
33 | ||
34 | @li The `completion_condition` function object returns 0. | |
35 | ||
36 | This operation is implemented in terms of zero or more calls to the | |
37 | stream's `read_some` function. | |
38 | ||
39 | @param stream The stream from which the data is to be read. The type | |
40 | must support the <em>SyncReadStream</em> requirements. | |
41 | ||
42 | @param buffer The dynamic buffer sequence into which the data will be read. | |
43 | ||
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 | |
46 | with this signature: | |
47 | @code | |
48 | std::size_t | |
49 | completion_condition( | |
50 | // Modifiable result of latest read_some operation. | |
51 | error_code& ec, | |
52 | ||
53 | // Number of bytes transferred so far. | |
54 | std::size_t bytes_transferred | |
55 | ||
56 | // The dynamic buffer used to store the bytes read | |
57 | DynamicBuffer& buffer | |
58 | ); | |
59 | @endcode | |
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. | |
65 | ||
66 | @returns The number of bytes transferred from the stream. | |
67 | ||
68 | @throws net::system_error Thrown on failure. | |
69 | */ | |
70 | template< | |
71 | class SyncReadStream, | |
72 | class DynamicBuffer, | |
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 | |
80 | >::type | |
81 | #endif | |
82 | > | |
83 | std::size_t | |
84 | read( | |
85 | SyncReadStream& stream, | |
86 | DynamicBuffer& buffer, | |
87 | CompletionCondition completion_condition); | |
88 | ||
89 | /** Read data into a dynamic buffer from a stream until a condition is met. | |
90 | ||
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: | |
93 | ||
94 | @li The specified dynamic buffer sequence is full (that is, it has | |
95 | reached its currently configured maximum size). | |
96 | ||
97 | @li The `completion_condition` function object returns 0. | |
98 | ||
99 | This operation is implemented in terms of zero or more calls to the | |
100 | stream's `read_some` function. | |
101 | ||
102 | @param stream The stream from which the data is to be read. The type | |
103 | must support the <em>SyncReadStream</em> requirements. | |
104 | ||
105 | @param buffer The dynamic buffer sequence into which the data will be read. | |
106 | ||
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 | |
109 | with this signature: | |
110 | @code | |
111 | std::size_t | |
112 | completion_condition( | |
113 | // Modifiable result of latest read_some operation. | |
114 | error_code& ec, | |
115 | ||
116 | // Number of bytes transferred so far. | |
117 | std::size_t bytes_transferred | |
118 | ||
119 | // The dynamic buffer used to store the bytes read | |
120 | DynamicBuffer& buffer | |
121 | ); | |
122 | @endcode | |
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. | |
128 | ||
129 | @returns The number of bytes transferred from the stream. | |
130 | */ | |
131 | template< | |
132 | class SyncReadStream, | |
133 | class DynamicBuffer, | |
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 | |
141 | >::type | |
142 | #endif | |
143 | > | |
144 | std::size_t | |
145 | read( | |
146 | SyncReadStream& stream, | |
147 | DynamicBuffer& buffer, | |
148 | CompletionCondition completion_condition, | |
149 | error_code& ec); | |
150 | ||
151 | /** Asynchronously read data into a dynamic buffer from a stream until a condition is met. | |
152 | ||
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: | |
156 | ||
157 | @li The specified dynamic buffer sequence is full (that is, it has | |
158 | reached its currently configured maximum size). | |
159 | ||
160 | @li The `completion_condition` function object returns 0. | |
161 | ||
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. | |
167 | ||
168 | @param stream The stream from which the data is to be read. The type must | |
169 | support the <em>AsyncReadStream</em> requirements. | |
170 | ||
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. | |
174 | ||
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 | |
177 | with this signature: | |
178 | @code | |
179 | std::size_t | |
180 | completion_condition( | |
181 | // Modifiable result of latest async_read_some operation. | |
182 | error_code& ec, | |
183 | ||
184 | // Number of bytes transferred so far. | |
185 | std::size_t bytes_transferred, | |
186 | ||
187 | // The dynamic buffer used to store the bytes read | |
188 | DynamicBuffer& buffer | |
189 | ); | |
190 | @endcode | |
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. | |
196 | ||
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 | |
200 | the handler must be: | |
201 | @code | |
202 | void | |
203 | handler( | |
204 | error_code const& ec, // Result of operation. | |
205 | ||
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. | |
211 | ); | |
212 | @endcode | |
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`. | |
217 | */ | |
218 | template< | |
219 | class AsyncReadStream, | |
220 | class DynamicBuffer, | |
221 | class CompletionCondition, | |
20effc67 | 222 | BOOST_BEAST_ASYNC_TPARAM2 ReadHandler |
92f5a8d4 TL |
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 | |
229 | >::type | |
230 | #endif | |
231 | > | |
232 | BOOST_BEAST_ASYNC_RESULT2(ReadHandler) | |
233 | async_read( | |
234 | AsyncReadStream& stream, | |
235 | DynamicBuffer& buffer, | |
236 | CompletionCondition&& completion_condition, | |
237 | ReadHandler&& handler); | |
238 | ||
239 | } // detail | |
240 | } // beast | |
241 | } // boost | |
242 | ||
243 | #include <boost/beast/core/detail/impl/read.hpp> | |
244 | ||
245 | #endif |