boost::burl::parser

A parser for HTTP/1 messages.

Synopsis

Declared in <boost/burl/parser.hpp>

class parser;

Description

The parser performs no I/O. Received bytes are handed to it through prepare and commit, and each parsing operation reports http::error::need_data when it requires more. Driving the parser over a stream is the job of message_reader.

The parser uses a single block of memory allocated during construction and never exceeds it. The space is reused across messages, one at a time, and holds:

raw octets received from the stream,
the message header, with O(1) access to the start line,
all or part of the message body, and
decoded output when a decoder is installed.

Operations

The body can be retrieved three ways, which differ in where the octets end up:

flatten_body returns the whole body in place, without copying,
read_some copies into caller‐supplied memory, or lets an installed decoder write into it directly, and
pull borrows the parser's own buffers, which consume then releases.

Each parses the header first when it has not been parsed already, so a caller with no interest in the header never has to call parse_header. Installing a decoder does require it, because set_decoder must run after the header and before any body octet.

Errors

Every parsing operation reports through an error_code out parameter:

http::error::need_data — fill prepare, call commit, and try again. Reported only while prepare has room.
http::error::in_place_overflow — more input is required but no writable space remains.
http::error::incomplete — more input is required but commit_eof was called.
http::error::end_of_stream — the stream closed cleanly before the message began.