• 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 Buffer-Oriented Parsing]
11[block'''<?dbhtml stop-chunking?>''']
12
13A subclass of __basic_parser__ can be invoked directly, without using
14the provided stream operations. This could be useful for implementing
15algorithms on objects whose interface does not conform to __Stream__.
16For example, a
17[@http://zeromq.org/ *ZeroMQ* socket].
18The basic parser interface is interactive; the caller invokes the function
19[link beast.ref.boost__beast__http__basic_parser.put `basic_parser::put`]
20repeatedly with buffers until an error occurs or the parsing is done. The
21function
22[link beast.ref.boost__beast__http__basic_parser.put_eof `basic_parser::put_eof`]
23Is used when the caller knows that there will never be more data (for example,
24if the underlying connection is closed),
25
26[heading Parser Options]
27
28The parser provides a few options which may be set before parsing begins:
29
30[table Parser Options
31[[Name][Default][Description]]
32[[
33    [link beast.ref.boost__beast__http__basic_parser.eager.overload2 `eager`]
34][
35    `false`
36][
37    Normally the parser returns after successfully parsing a structured
38    element (header, chunk header, or chunk body) even if there are octets
39    remaining in the input. This is necessary when attempting to parse the
40    header first, or when the caller wants to inspect information which may
41    be invalidated by subsequent parsing, such as a chunk extension. The
42    `eager` option controls whether the parser keeps going after parsing
43    structured element if there are octets remaining in the buffer and no
44    error occurs. This option is automatically set or cleared during certain
45    stream operations to improve performance with no change in functionality.
46]]
47[[
48    [link beast.ref.boost__beast__http__basic_parser.skip.overload2 `skip`]
49][
50    `false`
51][
52    This option controls whether or not the parser expects to see an HTTP
53    body, regardless of the presence or absence of certain fields such as
54    Content-Length or a chunked Transfer-Encoding. Depending on the request,
55    some responses do not carry a body. For example, a 200 response to a
56    [@https://tools.ietf.org/html/rfc7231#section-4.3.6 CONNECT] request
57    from a tunneling proxy, or a response to a
58    [@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD] request.
59    In these cases, callers may use this function inform the parser that
60    no body is expected. The parser will consider the message complete
61    after the header has been received.
62]]
63[[
64    [link beast.ref.boost__beast__http__basic_parser.body_limit `body_limit`]
65][
66    1MB/8MB
67][
68    This function sets the maximum allowed size of the content body.
69    When a body larger than the specified size is detected, an error
70    is generated and parsing terminates. This setting helps protect
71    servers from resource exhaustion attacks. The default limit when
72    parsing requests is 1MB, and for parsing responses 8MB.
73]]
74[[
75    [link beast.ref.boost__beast__http__basic_parser.header_limit `header_limit`]
76][
77    8KB
78][
79    This function sets the maximum allowed size of the header
80    including all field name, value, and delimiter characters
81    and also including the CRLF sequences in the serialized
82    input.
83]]
84]
85
86
87
88[section:read_from_std_istream Read From std::istream __example__]
89
90The standard library provides the type `std::istream` for performing high
91level read operations on character streams. The variable `std::cin` is based
92on this input stream. This example uses the buffer oriented interface of
93__basic_parser__ to build a stream operation which parses an HTTP message
94from a `std::istream`:
95
96[example_http_read_istream]
97
98[tip
99    Parsing from a `std::istream` could be implemented using an alternate
100    strategy: adapt the `std::istream` interface to a __SyncReadStream__,
101    enabling use with the library's existing stream algorithms. This is
102    left as an exercise for the reader.
103]
104
105[endsect]
106
107
108
109[endsect]
110