# pion::http::parser Class Reference

`#include <parser.hpp>`

Inherited by pion::http::reader.

List of all members.

## Classes

class | error_category_t
| class-specific error category More...

## Public Types

enum

error_value_t {
ERROR_METHOD_CHAR = 1, ERROR_METHOD_SIZE, ERROR_URI_CHAR, ERROR_URI_SIZE,
ERROR_QUERY_CHAR, ERROR_QUERY_SIZE, ERROR_VERSION_EMPTY, ERROR_VERSION_CHAR,
ERROR_STATUS_EMPTY, ERROR_STATUS_CHAR, ERROR_HEADER_CHAR, ERROR_HEADER_NAME_SIZE,
ERROR_HEADER_VALUE_SIZE, ERROR_INVALID_CONTENT_LENGTH, ERROR_CHUNK_CHAR, ERROR_MISSING_CHUNK_DATA,
ERROR_MISSING_HEADER_DATA, ERROR_MISSING_TOO_MUCH_CONTENT
}

| class-specific error code values
typedef boost::function2< void, const char *, std::size_t > | payload_handler_t
| callback type used to consume payload content

## Public Member Functions

| parser (const bool is_request, std::size_t max_content_length=DEFAULT_CONTENT_MAX)
virtual | ~parser ()
| default destructor
boost::tribool | parse (http::message &http_msg, boost::system::error_code &ec)
boost::tribool | parse_missing_data (http::message &http_msg, std::size_t len, boost::system::error_code &ec)
void | finish (http::message &http_msg) const
void | set_read_buffer (const char *ptr, size_t len)
void | load_read_pos (const char *&read_ptr, const char *&read_end_ptr) const
bool | check_premature_eof (http::message &http_msg)
void | parse_headers_only (bool b=true)
void | skip_header_parsing (http::message &http_msg)
void | reset (void)
| resets the parser to its initial state
bool | eof (void) const
| returns true if there are no more bytes available in the read buffer
std::size_t | bytes_available (void) const
| returns the number of bytes available in the read buffer
std::size_t | gcount (void) const
| returns the number of bytes read during the last parse operation
std::size_t | get_total_bytes_read (void) const
| returns the total number of bytes read while parsing the HTTP message
std::size_t | get_content_bytes_read (void) const
| returns the total number of bytes read while parsing the payload content
std::size_t | get_max_content_length (void) const
| returns the maximum length for HTTP payload content
const std::string & | get_raw_headers (void) const
| returns the raw HTTP headers saved by the parser
bool | get_save_raw_headers (void) const
| returns true if the parser is saving raw HTTP header contents
bool | get_parse_headers_only (void)
| returns true if parsing headers only
bool | is_parsing_request (void) const
| returns true if the parser is being used to parse an HTTP request
bool | is_parsing_response (void) const
| returns true if the parser is being used to parse an HTTP response
void | set_payload_handler (payload_handler_t &h)
| defines a callback function to be used for consuming payload content
void | set_max_content_length (std::size_t n)
| sets the maximum length for HTTP payload content
void | reset_max_content_length (void)
| resets the maximum length for HTTP payload content to the default value
void | set_save_raw_headers (bool b)
| sets parameter for saving raw HTTP header content
void | set_logger (logger log_ptr)
| sets the logger to be used
logger | get_logger (void)
| returns the logger currently in use
boost::tribool | finish_header_parsing (http::message &http_msg, boost::system::error_code &ec)

## Static Public Member Functions

static bool | parse_uri (const std::string &uri, std::string &proto, std::string &host, boost::uint16_t &port, std::string &path, std::string &query)
static bool | parse_url_encoded (ihash_multimap &dict, const char *ptr, const std::size_t len)
static bool | parse_multipart_form_data (ihash_multimap &dict, const std::string &content_type, const char *ptr, const std::size_t len)
static bool | parse_cookie_header (ihash_multimap &dict, const char *ptr, const std::size_t len, bool set_cookie_header)
static bool | parse_cookie_header (ihash_multimap &dict, const std::string &cookie_header, bool set_cookie_header)
static bool | parse_url_encoded (ihash_multimap &dict, const std::string &query)
static bool | parse_multipart_form_data (ihash_multimap &dict, const std::string &content_type, const std::string &form_data)
static bool | parse_forwarded_for (const std::string &header, std::string &public_ip)
static error_category_t & | get_error_category (void)
| returns an instance of parser::error_category_t

## Static Public Attributes

static const std::size_t | DEFAULT_CONTENT_MAX = 1024 * 1024
| maximum length for HTTP payload content

## Protected Member Functions

virtual void | finished_parsing_headers (const boost::system::error_code &ec)
| Called after we have finished parsing the HTTP message headers.
boost::tribool | parse_headers (http::message &http_msg, boost::system::error_code &ec)
void | update_message_with_header_data (http::message &http_msg) const
boost::tribool | parse_chunks (http::message::chunk_cache_t &chunk_buffers, boost::system::error_code &ec)
boost::tribool | consume_content (http::message &http_msg, boost::system::error_code &ec)
std::size_t | consume_content_as_next_chunk (http::message::chunk_cache_t &chunk_buffers)

## Static Protected Member Functions

static void | compute_msg_status (http::message &http_msg, bool msg_parsed_ok)
static void | set_error (boost::system::error_code &ec, error_value_t ev)
static void | create_error_category (void)
| creates the unique parser error_category_t
static bool | is_char (int c)
static bool | is_control (int c)
static bool | is_special (int c)
static bool | is_digit (int c)
static bool | is_hex_digit (int c)
static bool | is_cookie_attribute (const std::string &name, bool set_cookie_header)

## Protected Attributes

logger | m_logger
| primary logging interface used by this class
const bool | m_is_request
| true if the message is an HTTP request; false if it is an HTTP response
const char * | m_read_ptr
| points to the next character to be consumed in the read_buffer
const char * | m_read_end_ptr
| points to the end of the read_buffer (last byte + 1)

## Static Protected Attributes

static const boost::uint32_t | STATUS_MESSAGE_MAX = 1024
| maximum length for response status message
static const boost::uint32_t | METHOD_MAX = 1024
| maximum length for the request method
static const boost::uint32_t | RESOURCE_MAX = 256 * 1024
| maximum length for the resource requested
static const boost::uint32_t | QUERY_STRING_MAX = 1024 * 1024
| maximum length for the query string
static const boost::uint32_t | HEADER_NAME_MAX = 1024
| maximum length for an HTTP header name
static const boost::uint32_t | HEADER_VALUE_MAX = 1024 * 1024
| maximum length for an HTTP header value
static const boost::uint32_t | QUERY_NAME_MAX = 1024
| maximum length for the name of a query string variable
static const boost::uint32_t | QUERY_VALUE_MAX = 1024 * 1024
| maximum length for the value of a query string variable
static const boost::uint32_t | COOKIE_NAME_MAX = 1024
| maximum length for the name of a cookie name
static const boost::uint32_t | COOKIE_VALUE_MAX = 1024 * 1024
| maximum length for the value of a cookie; also used for path and domain

## Detailed Description

parser: parses HTTP messages

Definition at line 39 of file parser.hpp.

## Constructor & Destructor Documentation

pion::http::parser::parser | ( | const bool | is_request,
|  | std::size_t | max_content_length = `DEFAULT_CONTENT_MAX` |
| ) |  |  | `[inline]`

creates new parser objects

Parameters:

  | is_request | if true, the message is parsed as an HTTP request; if false, the message is parsed as an HTTP response
  | max_content_length | maximum length for HTTP payload content

Definition at line 129 of file parser.hpp.

## Member Function Documentation

bool pion::http::parser::check_premature_eof | ( | http::message & | http_msg | ) | `[inline]`

checks to see if a premature EOF was encountered while parsing. This should be called if there is no more data to parse, and if the last call to the parse() function returned boost::indeterminate

Parameters:

  | http_msg | the HTTP message object being parsed

Returns:
  true if premature EOF, false if message is OK & finished parsing

Definition at line 208 of file parser.hpp.

References pion::http::message::concatenate_chunks().

Referenced by pion::http::message::read(), and pion::http::message::receive().

void pion::http::parser::compute_msg_status | ( | http::message & | http_msg,
|  | bool | msg_parsed_ok |
| ) |  |  | `[static, protected]`

compute and sets a HTTP Message data integrity status

Parameters:

  | http_msg | target HTTP message
  | msg_parsed_ok | message parsing result

Definition at line 1550 of file http_parser.cpp.

References pion::http::message::has_data_after_missing_packets(), and pion::http::message::has_missing_packets().

Referenced by finish(), parse(), and parse_missing_data().

boost::tribool pion::http::parser::consume_content | ( | http::message & | http_msg,
|  | boost::system::error_code & | ec |
| ) |  |  | `[protected]`

consumes payload content in the parser's read buffer

Parameters:

  | http_msg | the HTTP message object to consume content for
  | ec | error_code contains additional information for parsing errors

Returns:
  boost::tribool result of parsing: false = message has an error, true = finished parsing message, indeterminate = message is not yet finished

Definition at line 1420 of file http_parser.cpp.

References bytes_available(), pion::http::message::get_content(), and m_read_ptr.

Referenced by parse().

std::size_t pion::http::parser::consume_content_as_next_chunk | ( | http::message::chunk_cache_t & | chunk_buffers | ) | `[protected]`

consume the bytes available in the read buffer, converting them into the next chunk for the HTTP message

Parameters:

  | chunk_buffers | buffers to be populated from parsing chunked content

Returns:
  std::size_t number of content bytes consumed, if any

Definition at line 1465 of file http_parser.cpp.

References bytes_available(), m_read_end_ptr, and m_read_ptr.

Referenced by parse().

void pion::http::parser::finish | ( | http::message & | http_msg | ) | const

finishes parsing an HTTP response message

Parameters:

  | http_msg | the HTTP message object to finish

Definition at line 1488 of file http_parser.cpp.

References compute_msg_status(), pion::http::message::concatenate_chunks(), pion::http::message::create_content_buffer(), pion::http::message::get_content(), get_content_bytes_read(), pion::http::message::get_content_length(), pion::http::message::get_header(), pion::http::request::get_queries(), is_parsing_request(), pion::http::message::is_valid(), m_logger, parse_multipart_form_data(), parse_url_encoded(), pion::http::message::set_content_length(), pion::http::message::set_is_valid(), and update_message_with_header_data().

Referenced by parse(), and parse_missing_data().

boost::tribool pion::http::parser::finish_header_parsing | ( | http::message & | http_msg,
|  | boost::system::error_code & | ec |
| ) |  |  |

should be called after parsing HTTP headers, to prepare for payload content parsing available in the read buffer

Parameters:

  | http_msg | the HTTP message object to populate from parsing
  | ec | error_code contains additional information for parsing errors

Returns:
  boost::tribool result of parsing: false = message has an error, true = finished parsing HTTP message (no content), indeterminate = payload content is available to be parsed

Definition at line 743 of file http_parser.cpp.

References pion::http::message::create_content_buffer(), finished_parsing_headers(), pion::http::message::get_chunk_cache(), pion::http::message::get_content_length(), pion::http::message::has_header(), pion::http::message::is_chunked(), pion::http::message::is_content_length_implied(), m_is_request, m_logger, pion::http::message::set_content_length(), set_error(), pion::http::message::update_content_length_using_header(), update_message_with_header_data(), and pion::http::message::update_transfer_encoding_using_header().

Referenced by parse().

void pion::http::parser::load_read_pos | ( | const char *& | read_ptr,
|  | const char *& | read_end_ptr |
| ) |  |  | const`[inline]`

loads a read position bookmark

Parameters:

  | read_ptr | points to the next character to be consumed in the read_buffer
  | read_end_ptr | points to the end of the read_buffer (last byte + 1)

Definition at line 195 of file parser.hpp.

Referenced by pion::http::message::receive().

boost::tribool pion::http::parser::parse | ( | http::message & | http_msg,
|  | boost::system::error_code & | ec |
| ) |  |  |

parses an HTTP message including all payload content it might contain

Parameters:

  | http_msg | the HTTP message object to populate from parsing
  | ec | error_code contains additional information for parsing errors

Returns:
  boost::tribool result of parsing: false = message has an error, true = finished parsing HTTP message, indeterminate = not yet finished parsing HTTP message

Definition at line 46 of file http_parser.cpp.

References compute_msg_status(), pion::http::message::concatenate_chunks(), consume_content(), consume_content_as_next_chunk(), eof(), finish(), finish_header_parsing(), pion::http::message::get_chunk_cache(), pion::http::message::has_missing_packets(), parse_chunks(), and parse_headers().

Referenced by pion::http::reader::consume_bytes(), pion::http::message::read(), and pion::http::message::receive().

boost::tribool pion::http::parser::parse_chunks | ( | http::message::chunk_cache_t & | chunk_buffers,
|  | boost::system::error_code & | ec |
| ) |  |  | `[protected]`

parses a chunked HTTP message-body using bytes available in the read buffer

Parameters:

  | chunk_buffers | buffers to be populated from parsing chunked content
  | ec | error_code contains additional information for parsing errors

Returns:
  boost::tribool result of parsing: false = message has an error, true = finished parsing message, indeterminate = message is not yet finished

Definition at line 1254 of file http_parser.cpp.

References bytes_available(), m_logger, m_read_end_ptr, m_read_ptr, and set_error().

Referenced by parse().

static bool pion::http::parser::parse_cookie_header | ( | ihash_multimap & | dict,
|  | const std::string & | cookie_header,
|  | bool | set_cookie_header |
| ) |  |  | `[inline, static]`

parse key-value pairs out of a "Cookie" request header (i.e. this=that; a=value)

Parameters:

  | dict | dictionary for key-values pairs
  | cookie_header | header string to be parsed
  | set_cookie_header | set true if parsing Set-Cookie response header

Returns:
  bool true if successful

Definition at line 369 of file parser.hpp.

static bool pion::http::parser::parse_cookie_header | ( | ihash_multimap & | dict,
|  | const char * | ptr,
|  | const std::size_t | len,
|  | bool | set_cookie_header |
| ) |  |  | `[static]`

parse key-value pairs out of a "Cookie" request header (i.e. this=that; a=value)

Parameters:

  | dict | dictionary for key-values pairs
  | ptr | points to the start of the header string to be parsed
  | len | length of the encoded string, in bytes
  | set_cookie_header | set true if parsing Set-Cookie response header

Returns:
  bool true if successful

Referenced by update_message_with_header_data().

bool pion::http::parser::parse_forwarded_for | ( | const std::string & | header,
|  | std::string & | public_ip |
| ) |  |  | `[static]`

parses an X-Forwarded-For HTTP header, and extracts from it an IP address that best matches the client's public IP address (if any are found)

Parameters:

  | header | the X-Forwarded-For HTTP header to parse
  | public_ip | the extract IP address, if found

Returns:
  bool true if a public IP address was found and extracted

static regex used to check for private/local networks: 10.* 127.* 192.168.* 172.16-31.*

Definition at line 1570 of file http_parser.cpp.

boost::tribool pion::http::parser::parse_headers | ( | http::message & | http_msg,
|  | boost::system::error_code & | ec |
| ) |  |  | `[protected]`

parses an HTTP message up to the end of the headers using bytes available in the read buffer

Parameters:

  | http_msg | the HTTP message object to populate from parsing
  | ec | error_code contains additional information for parsing errors

Returns:
  boost::tribool result of parsing: false = message has an error, true = finished parsing HTTP headers, indeterminate = not yet finished parsing HTTP headers

Definition at line 239 of file http_parser.cpp.

References pion::http::message::add_header(), pion::http::message::get_version_major(), pion::http::message::get_version_minor(), HEADER_NAME_MAX, HEADER_VALUE_MAX, m_is_request, m_logger, m_read_end_ptr, m_read_ptr, METHOD_MAX, QUERY_STRING_MAX, RESOURCE_MAX, set_error(), pion::http::message::set_version_major(), pion::http::message::set_version_minor(), and STATUS_MESSAGE_MAX.

Referenced by parse().

void pion::http::parser::parse_headers_only | ( | bool | b = `true` | ) | `[inline]`

controls headers-only parsing (default is disabled; content parsed also)

Parameters:

  | b | if true, then the parse() function returns true after headers

Definition at line 222 of file parser.hpp.

Referenced by pion::http::message::read(), and pion::http::message::receive().

boost::tribool pion::http::parser::parse_missing_data | ( | http::message & | http_msg,
|  | std::size_t | len,
|  | boost::system::error_code & | ec |
| ) |  |  |

attempts to continue parsing despite having missed data (length is known but content is not)

Parameters:

  | http_msg | the HTTP message object to populate from parsing
  | len | the length in bytes of the missing data
  | ec | error_code contains additional information for parsing errors

Returns:
  boost::tribool result of parsing: false = message has an error, true = finished parsing HTTP message, indeterminate = not yet finished parsing HTTP message

Definition at line 125 of file http_parser.cpp.

References compute_msg_status(), finish(), pion::http::message::get_chunk_cache(), pion::http::message::get_content(), set_error(), and pion::http::message::set_missing_packets().

static bool pion::http::parser::parse_multipart_form_data | ( | ihash_multimap & | dict,
|  | const std::string & | content_type,
|  | const std::string & | form_data |
| ) |  |  | `[inline, static]`

parse key-value pairs out of a multipart/form-data payload content (http://www.ietf.org/rfc/rfc2388.txt)

Parameters:

  | dict | dictionary for key-values pairs
  | content_type | value of the content-type HTTP header
  | form_data | the encoded form data

Returns:
  bool true if successful

Definition at line 400 of file parser.hpp.

static bool pion::http::parser::parse_multipart_form_data | ( | ihash_multimap & | dict,
|  | const std::string & | content_type,
|  | const char * | ptr,
|  | const std::size_t | len |
| ) |  |  | `[static]`

parse key-value pairs out of a multipart/form-data payload content (http://www.ietf.org/rfc/rfc2388.txt)

Parameters:

  | dict | dictionary for key-values pairs
  | content_type | value of the content-type HTTP header
  | ptr | points to the start of the encoded data
  | len | length of the encoded data, in bytes

Returns:
  bool true if successful

Referenced by finish().

bool pion::http::parser::parse_uri | ( | const std::string & | uri,
|  | std::string & | proto,
|  | std::string & | host,
|  | boost::uint16_t & | port,
|  | std::string & | path,
|  | std::string & | query |
| ) |  |  | `[static]`

parses a URI string

Parameters:

  | uri | the string to parse
  | proto | will be set to the protocol (i.e. "http")
  | host | will be set to the hostname (i.e. "www.cloudmeter.com")
  | port | host port number to use for connection (i.e. 80)
  | path | uri stem or file path
  | query | uri query string

Returns:
  true if the URI was successfully parsed, false if there was an error

Definition at line 830 of file http_parser.cpp.

static bool pion::http::parser::parse_url_encoded | ( | ihash_multimap & | dict,
|  | const std::string & | query |
| ) |  |  | `[inline, static]`

parse key-value pairs out of a url-encoded string (i.e. this=that&a=value)

Parameters:

  | dict | dictionary for key-values pairs
  | query | the encoded query string to be parsed

Returns:
  bool true if successful

Definition at line 384 of file parser.hpp.

static bool pion::http::parser::parse_url_encoded | ( | ihash_multimap & | dict,
|  | const char * | ptr,
|  | const std::size_t | len |
| ) |  |  | `[static]`

parse key-value pairs out of a url-encoded string (i.e. this=that&a=value)

Parameters:

  | dict | dictionary for key-values pairs
  | ptr | points to the start of the encoded string
  | len | length of the encoded string, in bytes

Returns:
  bool true if successful

Referenced by finish(), and update_message_with_header_data().

static void pion::http::parser::set_error | ( | boost::system::error_code & | ec,
|  | error_value_t | ev |
| ) |  |  | `[inline, static, protected]`

sets an error code

Parameters:

  | ec | error code variable to define
  | ev | error value to raise

Definition at line 516 of file parser.hpp.

Referenced by finish_header_parsing(), parse_chunks(), parse_headers(), and parse_missing_data().

void pion::http::parser::set_read_buffer | ( | const char * | ptr,
|  | size_t | len |
| ) |  |  | `[inline]`

resets the location and size of the read buffer

Parameters:

  | ptr | pointer to the first bytes available to be read
  | len | number of bytes available to be read

Definition at line 184 of file parser.hpp.

Referenced by pion::http::reader::consume_bytes(), pion::http::message::read(), and pion::http::message::receive().

void pion::http::parser::skip_header_parsing | ( | http::message & | http_msg | ) | `[inline]`

skip parsing all headers and parse payload content only

Parameters:

  | http_msg | the HTTP message object being parsed

Definition at line 229 of file parser.hpp.

void pion::http::parser::update_message_with_header_data | ( | http::message & | http_msg | ) | const`[protected]`

updates an http::message object with data obtained from parsing headers

Parameters:

  | http_msg | the HTTP message object to populate from parsing

Definition at line 689 of file http_parser.cpp.

References pion::http::message::get_cookies(), pion::http::message::get_headers(), pion::http::request::get_queries(), is_parsing_request(), m_logger, parse_cookie_header(), parse_url_encoded(), pion::http::request::set_method(), pion::http::request::set_query_string(), pion::http::request::set_resource(), pion::http::response::set_status_code(), and pion::http::response::set_status_message().

Referenced by finish(), and finish_header_parsing().

The documentation for this class was generated from the following files:

- include/pion/http/parser.hpp
- src/http_parser.cpp