Beast Logo

PrevUpHomeNext

http::basic_parser_v1

A parser for decoding HTTP/1 wire format messages.

template<
    bool isRequest,
    class Derived>
class basic_parser_v1 :
    public parser_base
Member Functions

Name

Description

basic_parser_v1

Default constructor.

Copy constructor.

complete

Returns true if the parse has completed succesfully.

flags

Returns internal flags associated with the parser.

http_major

Returns the major HTTP version number.

http_minor

Returns the minor HTTP version number.

keep_alive

Returns true if the connection should be kept open.

needs_eof

Returns true if the message end is indicated by eof.

operator=

Copy assignment.

set_option

Set options on the parser.

Set the header maximum size option.

Set the body maximum size option.

status_code

Returns the numeric HTTP Status-Code of a response.

upgrade

Returns true if the message is an upgrade message.

write

Write a sequence of buffers to the parser.

Write a single buffer of data to the parser.

write_eof

Called to indicate the end of file.

Protected Member Functions

Name

Description

reset

Reset the parsing state.

This parser is designed to efficiently parse messages in the HTTP/1 wire format. It allocates no memory and uses minimal state. It will handle chunked encoding and it understands the semantics of the Connection and Content-Length header fields.

The interface uses CRTP (Curiously Recurring Template Pattern). To use this class, derive from basic_parser. When bytes are presented, the implementation will make a series of zero or more calls to derived class members functions (referred to as "callbacks" from here on) matching a specific signature.

Every callback must be provided by the derived class, or else a compilation error will be generated. This exemplar shows the signature and description of the callbacks required in the derived class.

template<bool isRequest>
struct exemplar : basic_parser_v1<isRequest, exemplar>
{
    // Called when the first valid octet of a new message is received
    //
    void on_start(error_code&);

    // Called for each piece of the Request-Method
    //
    void on_method(boost::string_ref const&, error_code&);

    // Called for each piece of the Request-URI
    //
    void on_uri(boost::string_ref const&, error_code&);

    // Called for each piece of the reason-phrase
    //
    void on_reason(boost::string_ref const&, error_code&);

    // Called after the entire Request-Line has been parsed successfully.
    //
    void on_request(error_code&);

    // Called after the entire Response-Line has been parsed successfully.
    //
    void on_response(error_code&);

    // Called for each piece of the current header field.
    //
    void on_field(boost::string_ref const&, error_code&);

    // Called for each piece of the current header value.
    //
    void on_value(boost::string_ref const&, error_code&)

    // Called when the entire header has been parsed successfully.
    //
    void
    on_header(std::uint64_t content_length, error_code&);

    // Called after on_header, before the body is parsed
    //
    body_what
    on_body_what(std::uint64_t content_length, error_code&);

    // Called for each piece of the body.
    //
    // If the header indicates chunk encoding, the chunk
    // encoding is removed from the buffer before being
    // passed to the callback.
    //
    void on_body(boost::string_ref const&, error_code&);

    // Called when the entire message has been parsed successfully.
    // At this point, @ref complete returns `true`, and the parser
    // is ready to parse another message if `keep_alive` would
    // return `true`.
    //
    void on_complete(error_code&) {}
};

The return value of on_body_what is special, it controls whether or not the parser should expect a body. See body_what for choices of the return value.

If a callback sets an error, parsing stops at the current octet and the error is returned to the caller. Callbacks must not throw exceptions.

isRequest

A bool indicating whether the parser will be presented with request or response message.

Derived

The derived class type. This is part of the Curiously Recurring Template Pattern interface.

Requirements

Header: beast/http/basic_parser_v1.hpp

Convenience header: beast/http.hpp


PrevUpHomeNext