| Home | Libraries | People | FAQ | More

#### http::basic_parser

A parser for decoding HTTP/1 wire format messages.

##### Synopsis

Defined in header `<boost/beast/http/basic_parser.hpp>`

    template<
        bool isRequest>
    class basic_parser

##### Types

Name | Description
--- | ---
is_request | `true` if this parser parses requests, `false` for responses.

##### Member Functions

Name | Description
--- | ---
basic_parser [constructor] | Copy constructor.
body_limit | Set the limit on the payload body.
chunked | Returns `true` if the last value for Transfer-Encoding is "chunked".
content_length | Returns the optional value of Content-Length if known.
content_length_remaining | Returns the remaining content length if known.
eager | Returns `true` if the eager parse option is set. — Set the eager parse option.
got_some | Returns `true` if the parser has received at least one byte of input.
header_limit | Set a limit on the total size of the header.
is_done | Returns `true` if the message is complete.
is_header_done | Returns `true` if a the parser has produced the full header.
keep_alive | Returns `true` if the message has keep-alive connection semantics.
need_eof | Returns `true` if the message semantics require an end of file.
operator= | Copy assignment.
put | Write a buffer sequence to the parser.
put_eof | Inform the parser that the end of stream was reached.
skip | Returns `true` if the skip parse option is set. — Set the skip parse option.
upgrade | Returns `true` if the message is an upgrade message.
~basic_parser [destructor] | Destructor.

##### Protected Member Functions

Name | Description
--- | ---
basic_parser [constructor] | Default constructor. — Move constructor.
on_body_impl | Called each time additional data is received representing the content body.
on_body_init_impl | Called once before the body is processed.
on_chunk_body_impl | Called each time additional data is received representing part of a body chunk.
on_chunk_header_impl | Called each time a new chunk header of a chunk encoded body is received.
on_field_impl | Called once for each complete field in the HTTP header.
on_finish_impl | Called once when the complete message is received.
on_header_impl | Called once after the complete HTTP header is received.
on_request_impl | Called after receiving the request-line.
on_response_impl | Called after receiving the status-line.
on_trailer_field_impl | Called once for each complete field in the HTTP trailer header.
operator= | Move assignment.

##### Description

This parser is designed to efficiently parse messages in the HTTP/1 wire format. It allocates no memory when input is presented as a single contiguous buffer, and uses minimal state. It will handle chunked encoding and it understands the semantics of the Connection, Content-Length, and Upgrade fields. The parser is optimized for the case where the input buffer sequence consists of a single contiguous buffer. The `beast::basic_flat_buffer` class is provided, which guarantees that the input sequence of the stream buffer will be represented by exactly one contiguous buffer. To ensure the optimum performance of the parser, use `beast::basic_flat_buffer` with HTTP algorithms such as `read`, `read_some`, `async_read`, and `async_read_some`. Alternatively, the caller may use custom techniques to ensure that the structured portion of the HTTP message (header or chunk header) is contained in a linear buffer.

The interface to the parser uses virtual member functions. To use this class, derive your type from `basic_parser`. When bytes are presented, the implementation will make a series of zero or more calls to virtual functions, which the derived class must implement.

Every virtual function must be provided by the derived class, or else a compilation error will be generated. The implementation will make sure that `ec` is clear before each virtual function is invoked. If a virtual function sets an error, it is propagated out of the parser to the caller.

##### Template Parameters

Type | Description
--- | ---
`isRequest` | A `bool` indicating whether the parser will be presented with request or response message.

##### Remarks

If the parser encounters a field value with obs-fold longer than 4 kilobytes in length, an error is generated.