forked from boostorg/beast
Documentation work
This commit is contained in:
1 parent
d4ec693a61
commit
9d5d4d56a4
46 files changed
+1264
-153
No files matched your search
@@ -0,0 +1,119 @@
|
||||
[/
|
||||
Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
[section:parser_streams Parser Stream Operations]
|
||||
|
||||
Message oriented stream operations provide for limited control.
|
||||
Sophisticated algorithms may need to do more, such as:
|
||||
|
||||
* Receive the header first, then the body later.
|
||||
|
||||
* Receive a large body using a fixed-size buffer.
|
||||
|
||||
* Receive a message incrementally: bounded work in each I/O cycle.
|
||||
|
||||
* Defer the commitment to a __Body__ type until after reading the header.
|
||||
|
||||
All of these operations require callers to manage the lifetime of state
|
||||
information associated with the operation, by constructing a class derived
|
||||
from __basic_parser__. Beast comes with two instances of parsers, and user
|
||||
defined types deriving from the basic parser are possible:
|
||||
|
||||
[table Parser Implementations
|
||||
[[Name][Description]]
|
||||
[[
|
||||
__parser__
|
||||
][
|
||||
```
|
||||
/// An HTTP/1 parser for producing a message.
|
||||
template<
|
||||
bool isRequest, // `true` to parse an HTTP request
|
||||
class Body, // The Body type for the resulting message
|
||||
class Fields> // The type of container representing the fields
|
||||
class parser
|
||||
: public basic_parser<...>;
|
||||
```
|
||||
]]
|
||||
[[
|
||||
[link beast.ref.http__request_parser `request_parser`]
|
||||
][
|
||||
```
|
||||
/// An HTTP/1 parser for producing a request message.
|
||||
template<class Body, class Fields = fields>
|
||||
using request_parser = parser<true, Body, Fields>;
|
||||
```
|
||||
]]
|
||||
[[
|
||||
[link beast.ref.http__response_parser `response_parser`]
|
||||
][
|
||||
```
|
||||
/// An HTTP/1 parser for producing a response message.
|
||||
template<class Body, class Fields = fields>
|
||||
using response_parser = parser<false, Body, Fields>;
|
||||
```
|
||||
]]
|
||||
]
|
||||
|
||||
[note
|
||||
The __basic_parser__ and classes derived from it handle octet streams
|
||||
serialized in the HTTP/1 format described in __rfc7230__.
|
||||
]
|
||||
|
||||
The stream operations which work on parsers are:
|
||||
|
||||
[table Parser Stream Operations
|
||||
[[Name][Description]]
|
||||
[[
|
||||
[link beast.ref.http__read.overload1 [*read]]
|
||||
][
|
||||
Read everything into a parser from a __SyncWriteStream__.
|
||||
]]
|
||||
[[
|
||||
[link beast.ref.http__async_read.overload1 [*async_read]]
|
||||
][
|
||||
Read everything into a parser asynchronously from an __AsyncWriteStream__.
|
||||
]]
|
||||
[[
|
||||
[link beast.ref.http__read_header.overload1 [*read_header]]
|
||||
][
|
||||
Read only the header octets into a parser from a __SyncWriteStream__.
|
||||
]]
|
||||
[[
|
||||
[link beast.ref.http__async_read_header [*async_read_header]]
|
||||
][
|
||||
Read only the header octets into a parser asynchronously from an __AsyncWriteStream__.
|
||||
]]
|
||||
[[
|
||||
[link beast.ref.http__read_some.overload1 [*read_some]]
|
||||
][
|
||||
Read some octets into a parser from a __SyncReadStream__.
|
||||
]]
|
||||
[[
|
||||
[link beast.ref.http__async_read_some [*async_read_some]]
|
||||
][
|
||||
Read some octets into a parser asynchronously from an __AsyncWriteStream__.
|
||||
]]
|
||||
]
|
||||
|
||||
As with message stream operations, parser stream operations require a
|
||||
persisted __DynamicBuffer__ for holding unused octets from the stream.
|
||||
The basic parser implementation is optimized for the case where this dynamic
|
||||
buffer stores its input sequence in a single contiguous memory buffer. It is
|
||||
advised to use an instance of __flat_buffer__, __static_buffer__, or
|
||||
__static_buffer_n__ for this purpose, although a user defined instance of
|
||||
__DynamicBuffer__ which produces input sequences of length one is also suitable.
|
||||
|
||||
The provided parsers use a "captive object" model, acting as container for
|
||||
the __message__ produced as a result of parsing. The caller accesses the
|
||||
contained object, and depending on the types used to instantiate the parser,
|
||||
it may be possible to acquire ownership of the header or message captive
|
||||
object and destroy the parser. In this example we read an HTTP response
|
||||
with a string body using a parser, then print the response:
|
||||
|
||||
[http_snippet_13]
|
||||
|
||||
[endsect]
|
||||
Reference in new issue
Block a user