2 // Copyright (c) 2013-2017 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)
8 #ifndef BEAST_HTTP_READ_HPP
9 #define BEAST_HTTP_READ_HPP
11 #include <beast/config.hpp>
12 #include <beast/core/async_completion.hpp>
13 #include <beast/core/error.hpp>
14 #include <beast/http/basic_parser.hpp>
15 #include <beast/http/message.hpp>
20 /** Read some HTTP/1 message data from a stream.
22 This function synchronously advances the state of the
23 parser using the provided dynamic buffer and reading
24 from the input stream as needed. The call will block
25 until one of the following conditions is true:
27 @li When expecting a message header, and the complete
30 @li When expecting a chunk header, and the complete
31 chunk header is received.
33 @li When expecting body octets, one or more body octets
36 @li An error occurs in the stream or parser.
38 This function is implemented in terms of one or more calls
39 to the stream's `read_some` function. The implementation may
40 read additional octets that lie past the end of the object
41 being parsed. This additional data is stored in the dynamic
42 buffer, which may be used in subsequent calls.
44 @param stream The stream from which the data is to be read.
45 The type must support the @b SyncReadStream concept.
47 @param dynabuf A @b DynamicBuffer holding additional bytes
48 read by the implementation from the stream. This is both
49 an input and an output parameter; on entry, any data in the
50 dynamic buffer's input sequence will be given to the parser
53 @param parser The parser to use.
55 @return The number of bytes processed from the dynamic
56 buffer. The caller should remove these bytes by calling
57 `consume` on the dynamic buffer.
59 @throws system_error Thrown on failure.
64 bool isRequest, bool isDirect, class Derived>
67 SyncReadStream& stream,
68 DynamicBuffer& dynabuf,
69 basic_parser<isRequest, isDirect, Derived>& parser);
71 /** Read some HTTP/1 message data from a stream.
73 This function synchronously advances the state of the
74 parser using the provided dynamic buffer and reading
75 from the input stream as needed. The call will block
76 until one of the following conditions is true:
78 @li When expecting a message header, and the complete
81 @li When expecting a chunk header, and the complete
82 chunk header is received.
84 @li When expecting body octets, one or more body octets
87 @li An error occurs in the stream or parser.
89 This function is implemented in terms of one or more calls
90 to the stream's `read_some` function. The implementation may
91 read additional octets that lie past the end of the object
92 being parsed. This additional data is stored in the dynamic
93 buffer, which may be used in subsequent calls.
95 @param stream The stream from which the data is to be read.
96 The type must support the @b SyncReadStream concept.
98 @param dynabuf A @b DynamicBuffer holding additional bytes
99 read by the implementation from the stream. This is both
100 an input and an output parameter; on entry, any data in the
101 dynamic buffer's input sequence will be given to the parser
104 @param parser The parser to use.
106 @param ec Set to the error, if any occurred.
108 @return The number of bytes processed from the dynamic
109 buffer. The caller should remove these bytes by calling
110 `consume` on the dynamic buffer.
113 class SyncReadStream,
115 bool isRequest, bool isDirect, class Derived>
118 SyncReadStream& stream,
119 DynamicBuffer& dynabuf,
120 basic_parser<isRequest, isDirect, Derived>& parser,
123 /** Start an asynchronous operation to read some HTTP/1 message data from a stream.
125 This function asynchronously advances the state of the
126 parser using the provided dynamic buffer and reading from
127 the input stream as needed. The function call always
128 returns immediately. The asynchronous operation will
129 continue until one of the following conditions is true:
131 @li When expecting a message header, and the complete
134 @li When expecting a chunk header, and the complete
135 chunk header is received.
137 @li When expecting body octets, one or more body octets
140 @li An error occurs in the stream or parser.
142 This operation is implemented in terms of zero or more calls to
143 the next layer's `async_read_some` function, and is known as a
144 <em>composed operation</em>. The program must ensure that the
145 stream performs no other operations until this operation completes.
146 The implementation may read additional octets that lie past the
147 end of the object being parsed. This additional data is stored
148 in the stream buffer, which may be used in subsequent calls.
150 The completion handler will be called with the number of bytes
151 processed from the dynamic buffer. The caller should remove
152 these bytes by calling `consume` on the dynamic buffer.
154 @param stream The stream from which the data is to be read.
155 The type must support the @b AsyncReadStream concept.
157 @param dynabuf A @b DynamicBuffer holding additional bytes
158 read by the implementation from the stream. This is both
159 an input and an output parameter; on entry, any data in the
160 dynamic buffer's input sequence will be given to the parser
163 @param parser The parser to use.
165 @param handler The handler to be called when the request
166 completes. Copies will be made of the handler as required.
167 The equivalent function signature of the handler must be:
169 error_code const& error, // result of operation
170 std::size_t bytes_used // the number of bytes to consume
172 Regardless of whether the asynchronous operation completes
173 immediately or not, the handler will not be invoked from within
174 this function. Invocation of the handler will be performed in a
175 manner equivalent to using `boost::asio::io_service::post`.
178 class AsyncReadStream,
180 bool isRequest, bool isDirect, class Derived,
185 typename async_completion<
186 ReadHandler, void(error_code, std::size_t)>::result_type
189 AsyncReadStream& stream,
190 DynamicBuffer& dynabuf,
191 basic_parser<isRequest, isDirect, Derived>& parser,
192 ReadHandler&& handler);
194 //------------------------------------------------------------------------------
196 /** Read an HTTP/1 message from a stream.
198 This function synchronously reads from a stream and passes
199 data to the specified parser. The call will block until one
200 of the following conditions is true:
202 @li The parser indicates no more additional data is needed.
204 @li An error occurs in the stream or parser.
206 This function is implemented in terms of one or more calls
207 to the stream's `read_some` function. The implementation may
208 read additional octets that lie past the end of the object
209 being parsed. This additional data is stored in the dynamic
210 buffer, which may be used in subsequent calls.
212 @param stream The stream from which the data is to be read.
213 The type must support the @b SyncReadStream concept.
215 @param dynabuf A @b DynamicBuffer holding additional bytes
216 read by the implementation from the stream. This is both
217 an input and an output parameter; on entry, any data in the
218 dynamic buffer's input sequence will be given to the parser
221 @param parser The parser to use.
223 @throws system_error Thrown on failure.
226 class SyncReadStream,
228 bool isRequest, bool isDirect, class Derived>
231 SyncReadStream& stream,
232 DynamicBuffer& dynabuf,
233 basic_parser<isRequest, isDirect, Derived>& parser);
235 /** Read an HTTP/1 message from a stream.
237 This function synchronously reads from a stream and passes
238 data to the specified parser. The call will block until one
239 of the following conditions is true:
241 @li The parser indicates that no more data is needed.
243 @li An error occurs in the stream or parser.
245 This function is implemented in terms of one or more calls
246 to the stream's `read_some` function. The implementation may
247 read additional octets that lie past the end of the object
248 being parsed. This additional data is stored in the dynamic
249 buffer, which may be used in subsequent calls.
251 @param stream The stream from which the data is to be read.
252 The type must support the @b SyncReadStream concept.
254 @param dynabuf A @b DynamicBuffer holding additional bytes
255 read by the implementation from the stream. This is both
256 an input and an output parameter; on entry, any data in the
257 dynamic buffer's input sequence will be given to the parser
260 @param parser The parser to use.
262 @param ec Set to the error, if any occurred.
265 class SyncReadStream,
267 bool isRequest, bool isDirect, class Derived>
270 SyncReadStream& stream,
271 DynamicBuffer& dynabuf,
272 basic_parser<isRequest, isDirect, Derived>& parser,
275 /** Start an asynchronous operation to read an HTTP/1 message from a stream.
277 This function is used to asynchronously read from a stream and
278 pass the data to the specified parser. The function call always
279 returns immediately. The asynchronous operation will continue
280 until one of the following conditions is true:
282 @li The parser indicates that no more data is needed.
284 @li An error occurs in the stream or parser.
286 This operation is implemented in terms of one or more calls to
287 the next layer's `async_read_some` function, and is known as a
288 <em>composed operation</em>. The program must ensure that the
289 stream performs no other operations until this operation completes.
290 The implementation may read additional octets that lie past the
291 end of the object being parsed. This additional data is stored
292 in the stream buffer, which may be used in subsequent calls.
294 @param stream The stream from which the data is to be read.
295 The type must support the @b AsyncReadStream concept.
297 @param dynabuf A @b DynamicBuffer holding additional bytes
298 read by the implementation from the stream. This is both
299 an input and an output parameter; on entry, any data in the
300 dynamic buffer's input sequence will be given to the parser
303 @param parser The parser to use.
305 @param handler The handler to be called when the request
306 completes. Copies will be made of the handler as required.
307 The equivalent function signature of the handler must be:
309 error_code const& error // result of operation
311 Regardless of whether the asynchronous operation completes
312 immediately or not, the handler will not be invoked from within
313 this function. Invocation of the handler will be performed in a
314 manner equivalent to using `boost::asio::io_service::post`.
317 class AsyncReadStream,
319 bool isRequest, bool isDirect, class Derived,
324 typename async_completion<
325 ReadHandler, void(error_code)>::result_type
328 AsyncReadStream& stream,
329 DynamicBuffer& dynabuf,
330 basic_parser<isRequest, isDirect, Derived>& parser,
331 ReadHandler&& handler);
333 /** Read an HTTP/1 message from a stream.
335 This function is used to synchronously read a message from
336 a stream. The call blocks until one of the following conditions
339 @li A complete message is read in.
341 @li An error occurs in the stream or parser.
343 This function is implemented in terms of one or more calls
344 to the stream's `read_some` function. The implementation may
345 read additional octets that lie past the end of the message
346 being parsed. This additional data is stored in the dynamic
347 buffer, which may be used in subsequent calls.
349 @param stream The stream from which the data is to be read.
350 The type must support the @b `SyncReadStream` concept.
352 @param dynabuf A @b `DynamicBuffer` holding additional bytes
353 read by the implementation from the stream. This is both
354 an input and an output parameter; on entry, any data in the
355 dynamic buffer's input sequence will be given to the parser
358 @param msg An object used to store the message. Any
359 contents will be overwritten. The type must support
360 copy assignment or move assignment.
362 @throws system_error Thrown on failure.
365 class SyncReadStream,
367 bool isRequest, class Body, class Fields>
370 SyncReadStream& stream,
371 DynamicBuffer& dynabuf,
372 message<isRequest, Body, Fields>& msg);
374 /** Read a HTTP/1 message from a stream.
376 This function is used to synchronously read a message from
377 a stream. The call blocks until one of the following conditions
380 @li A complete message is read in.
382 @li An error occurs in the stream or parser.
384 This function is implemented in terms of one or more calls
385 to the stream's `read_some` function. The implementation may
386 read additional octets that lie past the end of the message
387 being parsed. This additional data is stored in the dynamic
388 buffer, which may be used in subsequent calls.
390 @param stream The stream from which the data is to be read.
391 The type must support the @b `SyncReadStream` concept.
393 @param dynabuf A @b `DynamicBuffer` holding additional bytes
394 read by the implementation from the stream. This is both
395 an input and an output parameter; on entry, any data in the
396 dynamic buffer's input sequence will be given to the parser
399 @param msg An object used to store the message. Any
400 contents will be overwritten. The type must support
401 copy assignment or move assignment.
403 @param ec Set to the error, if any occurred.
406 class SyncReadStream,
408 bool isRequest, class Body, class Fields>
411 SyncReadStream& stream,
412 DynamicBuffer& dynabuf,
413 message<isRequest, Body, Fields>& msg,
416 /** Read a HTTP/1 message asynchronously from a stream.
418 This function is used to asynchronously read a message from
419 a stream. The function call always returns immediately. The
420 asynchronous operation will continue until one of the following
423 @li A complete message is read in.
425 @li An error occurs in the stream or parser.
427 This operation is implemented in terms of one or more calls to
428 the stream's `async_read_some` function, and is known as a
429 <em>composed operation</em>. The program must ensure that the
430 stream performs no other operations until this operation completes.
431 The implementation may read additional octets that lie past the
432 end of the message being parsed. This additional data is stored
433 in the dynamic buffer, which may be used in subsequent calls.
435 @param stream The stream to read the message from.
436 The type must support the @b `AsyncReadStream` concept.
438 @param dynabuf A @b `DynamicBuffer` holding additional bytes
439 read by the implementation from the stream. This is both
440 an input and an output parameter; on entry, any data in the
441 dynamic buffer's input sequence will be given to the parser
444 @param msg An object used to store the header. Any contents
445 will be overwritten. The type must support copy assignment or
446 move assignment. The object must remain valid at least until
447 the completion handler is called; ownership is not transferred.
449 @param handler The handler to be called when the operation
450 completes. Copies will be made of the handler as required.
451 The equivalent function signature of the handler must be:
453 error_code const& error // result of operation
455 Regardless of whether the asynchronous operation completes
456 immediately or not, the handler will not be invoked from within
457 this function. Invocation of the handler will be performed in a
458 manner equivalent to using `boost::asio::io_service::post`.
461 class AsyncReadStream,
463 bool isRequest, class Body, class Fields,
468 typename async_completion<
469 ReadHandler, void(error_code)>::result_type
472 AsyncReadStream& stream,
473 DynamicBuffer& dynabuf,
474 message<isRequest, Body, Fields>& msg,
475 ReadHandler&& handler);
480 #include <beast/http/impl/async_read.ipp>
481 #include <beast/http/impl/read.ipp>