• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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[section Parser Stream Operations]
11
12Non-trivial algorithms need to do more than receive entire messages
13at once, such as:
14
15
16* Receive the header first and body later.
17
18* Receive a large body using a fixed-size buffer.
19
20* Receive a message incrementally: bounded work in each I/O cycle.
21
22* Defer the commitment to a __Body__ type until after reading the header.
23
24These types of operations require callers to manage the lifetime of
25associated state, by constructing a class derived from __basic_parser__.
26Beast comes with the derived instance __parser__ which creates complete
27__message__ objects using the __basic_fields__ Fields container.
28
29[table Parser
30[[Name][Description]]
31[[
32    __parser__
33][
34    ```
35    /// An HTTP/1 parser for producing a message.
36    template<
37        bool isRequest,                         // `true` to parse an HTTP request
38        class Body,                             // The Body type for the resulting message
39        class Allocator = std::allocator<char>> // The type of allocator for the header
40    class parser
41        : public basic_parser<...>;
42    ```
43]]
44[[
45    [link beast.ref.boost__beast__http__request_parser `request_parser`]
46][
47    ```
48    /// An HTTP/1 parser for producing a request message.
49    template<class Body, class Allocator = std::allocator<char>>
50    using request_parser = parser<true, Body, Allocator>;
51    ```
52]]
53[[
54    [link beast.ref.boost__beast__http__response_parser `response_parser`]
55][
56    ```
57    /// An HTTP/1 parser for producing a response message.
58    template<class Body, class Allocator = std::allocator<char>>
59    using response_parser = parser<false, Body, Allocator>;
60    ```
61]]
62]
63
64[note
65    The __basic_parser__ and classes derived from it handle octet streams
66    serialized in the HTTP/1 format described in __rfc7230__.
67]
68
69The stream operations which work on parsers are:
70
71[table Parser Stream Operations
72[[Name][Description]]
73[[
74    [link beast.ref.boost__beast__http__read.overload1 [*read]]
75][
76    Read everything into a parser from a __SyncWriteStream__.
77]]
78[[
79    [link beast.ref.boost__beast__http__async_read.overload1 [*async_read]]
80][
81    Read everything into a parser asynchronously from an __AsyncWriteStream__.
82]]
83[[
84    [link beast.ref.boost__beast__http__read_header.overload1 [*read_header]]
85][
86    Read only the header octets into a parser from a __SyncWriteStream__.
87]]
88[[
89    [link beast.ref.boost__beast__http__async_read_header [*async_read_header]]
90][
91    Read only the header octets into a parser asynchronously from an __AsyncWriteStream__.
92]]
93[[
94    [link beast.ref.boost__beast__http__read_some.overload1 [*read_some]]
95][
96    Read some octets into a parser from a __SyncReadStream__.
97]]
98[[
99    [link beast.ref.boost__beast__http__async_read_some [*async_read_some]]
100][
101    Read some octets into a parser asynchronously from an __AsyncWriteStream__.
102]]
103]
104
105As with message stream operations, parser stream operations require a
106persisted __DynamicBuffer__  for holding unused octets from the stream.
107The basic parser implementation is optimized for the case where this dynamic
108buffer stores its input sequence in a single contiguous memory buffer. It is
109advised to use an instance of __flat_buffer__, __flat_static_buffer__, or
110__flat_static_buffer_base__ for this purpose, although a user defined instance
111of __DynamicBuffer__ which produces input sequences of length one is also
112suitable.
113
114The parser contains a message constructed internally. Arguments passed
115to the parser's constructor are forwarded into the message container.
116The caller can access the message inside the parser by calling
117[link beast.ref.boost__beast__http__parser.get `parser::get`].
118If the `Fields` and `Body` types are [*MoveConstructible], the caller
119can take ownership of the message by calling
120[link beast.ref.boost__beast__http__parser.release `parser::release`]. In this example
121we read an HTTP response with a string body using a parser, then print
122the response:
123
124[http_snippet_13]
125
126
127
128[section:incremental_read Incremental Read __example__]
129
130This function uses
131[link beast.ref.boost__beast__http__buffer_body `buffer_body`]
132and parser stream operations to read a message body progressively
133using a small, fixed-size buffer:
134
135[example_incremental_read]
136
137[endsect]
138
139
140
141[endsect]
142