pion::http::message Class Referenceabstract

`#include <message.hpp>`

Inherits pion::http::types.

Inherited by pion::http::request, and pion::http::response.

## Classes

class | content_buffer_t
| a simple helper class used to manage a fixed-size payload content buffer More...
struct | receive_error_t
| data type for library errors returned during receive() operations More...

## Public Types

enum | data_status_t { STATUS_NONE, STATUS_TRUNCATED, STATUS_PARTIAL, STATUS_OK }
| defines message data integrity status codes
typedef std::vector< boost::asio::const_buffer > | write_buffers_t
| data type for I/O write buffers (these wrap existing data to be sent)
typedef std::vector< char > | chunk_cache_t
| used to cache chunked data

## Public Member Functions

| message (void)
| constructs a new HTTP message object
| message (const message &http_msg)
| copy constructor
message & | operator= (const message &http_msg)
| assignment operator
virtual | ~message ()
| virtual destructor
virtual void | clear (void)
| clears all message data
virtual bool | is_content_length_implied (void) const =0
| should return true if the content length can be implied without headers
bool | is_valid (void) const
| returns true if the message is valid
bool | get_chunks_supported (void) const
| returns true if chunked transfer encodings are supported
boost::asio::ip::address & | get_remote_ip (void)
| returns IP address of the remote endpoint
boost::uint16_t | get_version_major (void) const
| returns the major HTTP version number
boost::uint16_t | get_version_minor (void) const
| returns the minor HTTP version number
std::string | get_version_string (void) const
| returns a string representation of the HTTP version (i.e. "HTTP/1.1")
size_t | get_content_length (void) const
| returns the length of the payload content (in bytes)
bool | is_chunked (void) const
| returns true if the message content is chunked
bool | is_content_buffer_allocated () const
| returns true if buffer for content is allocated
std::size_t | get_content_buffer_size () const
| returns size of allocated buffer
char * | get_content (void)
| returns a pointer to the payload content, or empty string if there is none
const char * | get_content (void) const
| returns a const pointer to the payload content, or empty string if there is none
chunk_cache_t & | get_chunk_cache (void)
| returns a reference to the chunk cache
const std::string & | get_header (const std::string &key) const
| returns a value for the header if any are defined; otherwise, an empty string
ihash_multimap & | get_headers (void)
| returns a reference to the HTTP headers
bool | has_header (const std::string &key) const
| returns true if at least one value for the header is defined
const std::string & | get_cookie (const std::string &key) const
ihash_multimap & | get_cookies (void)
| returns the cookie parameters
bool | has_cookie (const std::string &key) const
void | add_cookie (const std::string &key, const std::string &value)
void | change_cookie (const std::string &key, const std::string &value)
void | delete_cookie (const std::string &key)
const std::string & | get_first_line (void) const
| returns a string containing the first line for the HTTP message
bool | has_missing_packets () const
| true if there were missing packets
void | set_missing_packets (bool newVal)
| set to true when missing packets detected
bool | has_data_after_missing_packets () const
| true if more data seen after the missing packets
void | set_data_after_missing_packet (bool newVal)
void | set_is_valid (bool b=true)
| sets whether or not the message is valid
void | set_chunks_supported (bool b)
| set to true if chunked transfer encodings are supported
void | set_remote_ip (const boost::asio::ip::address &ip)
| sets IP address of the remote endpoint
void | set_version_major (const boost::uint16_t n)
| sets the major HTTP version number
void | set_version_minor (const boost::uint16_t n)
| sets the minor HTTP version number
void | set_content_length (size_t n)
| sets the length of the payload content (in bytes)
void | set_do_not_send_content_length (void)
| if called, the content-length will not be sent in the HTTP headers
data_status_t | get_status () const
| return the data receival status
void | set_status (data_status_t newVal)
void | update_content_length_using_header (void)
| sets the length of the payload content using the Content-Length header
void | update_transfer_encoding_using_header (void)
| sets the transfer coding using the Transfer-Encoding header
char * | create_content_buffer (void)
void | set_content (const std::string &content)
| resets payload content to match the value of a string
void | clear_content (void)
| clears payload content buffer
void | set_content_type (const std::string &type)
| sets the content type for the message payload
void | add_header (const std::string &key, const std::string &value)
| adds a value for the HTTP header named key
void | change_header (const std::string &key, const std::string &value)
| changes the value for the HTTP header named key
void | delete_header (const std::string &key)
| removes all values for the HTTP header named key
bool | check_keep_alive (void) const
| returns true if the HTTP connection may be kept alive
void | prepare_buffers_for_send (write_buffers_t &write_buffers, const bool keep_alive, const bool using_chunks)
std::size_t | send (tcp::connection &tcp_conn, boost::system::error_code &ec, bool headers_only=false)
std::size_t | receive (tcp::connection &tcp_conn, boost::system::error_code &ec, parser &http_parser)
std::size_t | receive (tcp::connection &tcp_conn, boost::system::error_code &ec, bool headers_only=false, std::size_t max_content_length=static_cast< size_t >(-1))
std::size_t | write (std::ostream &out, boost::system::error_code &ec, bool headers_only=false)
std::size_t | read (std::istream &in, boost::system::error_code &ec, parser &http_parser)
std::size_t | read (std::istream &in, boost::system::error_code &ec, bool headers_only=false, std::size_t max_content_length=static_cast< size_t >(-1))
void | concatenate_chunks (void)
Public Member Functions inherited from pion::http::types
virtual | ~types ()
| virtual destructor

## Protected Member Functions

void | prepare_headers_for_send (const bool keep_alive, const bool using_chunks)
void | append_headers (write_buffers_t &write_buffers)
virtual void | append_cookie_headers (void)
| appends HTTP headers for any cookies defined by the http::message
void | clear_first_line (void) const
virtual void | update_first_line (void) const =0
| updates the string containing the first line for the HTTP message

## Static Protected Member Functions

template<typename DictionaryType >
static const std::string & | get_value (const DictionaryType &dict, const std::string &key)
template<typename DictionaryType >
static void | change_value (DictionaryType &dict, const std::string &key, const std::string &value)
template<typename DictionaryType >
static void | delete_value (DictionaryType &dict, const std::string &key)

## Protected Attributes

std::string | m_first_line

## Additional Inherited Members

Static Public Member Functions inherited from pion::http::types
static std::string | get_date_string (const time_t t)
| converts time_t format into an HTTP-date string
static std::string | make_query_string (const ihash_multimap &query_params)
| builds an HTTP query string from a collection of query parameters
static std::string | make_set_cookie_header (const std::string &name, const std::string &value, const std::string &path, const bool has_max_age=false, const unsigned long max_age=0)
Static Public Attributes inherited from pion::http::types
static const std::string | STRING_EMPTY
static const std::string | STRING_CRLF
static const std::string | STRING_HTTP_VERSION
static const std::string | HEADER_NAME_VALUE_DELIMITER
static const std::string | COOKIE_NAME_VALUE_DELIMITER
static const std::string | HEADER_HOST
static const std::string | HEADER_COOKIE
static const std::string | HEADER_SET_COOKIE
static const std::string | HEADER_CONNECTION
static const std::string | HEADER_CONTENT_TYPE
static const std::string | HEADER_CONTENT_LENGTH
static const std::string | HEADER_CONTENT_LOCATION
static const std::string | HEADER_CONTENT_ENCODING
static const std::string | HEADER_CONTENT_DISPOSITION
static const std::string | HEADER_LAST_MODIFIED
static const std::string | HEADER_IF_MODIFIED_SINCE
static const std::string | HEADER_TRANSFER_ENCODING
static const std::string | HEADER_LOCATION
static const std::string | HEADER_AUTHORIZATION
static const std::string | HEADER_REFERER
static const std::string | HEADER_USER_AGENT
static const std::string | HEADER_X_FORWARDED_FOR
static const std::string | HEADER_CLIENT_IP
static const std::string | CONTENT_TYPE_HTML
static const std::string | CONTENT_TYPE_TEXT
static const std::string | CONTENT_TYPE_XML
static const std::string | CONTENT_TYPE_URLENCODED
static const std::string | CONTENT_TYPE_MULTIPART_FORM_DATA
static const std::string | REQUEST_METHOD_HEAD
static const std::string | REQUEST_METHOD_GET
static const std::string | REQUEST_METHOD_PUT
static const std::string | REQUEST_METHOD_POST
static const std::string | REQUEST_METHOD_DELETE
static const std::string | RESPONSE_MESSAGE_OK
static const std::string | RESPONSE_MESSAGE_CREATED
static const std::string | RESPONSE_MESSAGE_ACCEPTED
static const std::string | RESPONSE_MESSAGE_NO_CONTENT
static const std::string | RESPONSE_MESSAGE_FOUND
static const std::string | RESPONSE_MESSAGE_UNAUTHORIZED
static const std::string | RESPONSE_MESSAGE_FORBIDDEN
static const std::string | RESPONSE_MESSAGE_NOT_FOUND
static const std::string | RESPONSE_MESSAGE_METHOD_NOT_ALLOWED
static const std::string | RESPONSE_MESSAGE_NOT_MODIFIED
static const std::string | RESPONSE_MESSAGE_BAD_REQUEST
static const std::string | RESPONSE_MESSAGE_SERVER_ERROR
static const std::string | RESPONSE_MESSAGE_NOT_IMPLEMENTED
static const std::string | RESPONSE_MESSAGE_CONTINUE
static const unsigned int | RESPONSE_CODE_OK = 200
static const unsigned int | RESPONSE_CODE_CREATED = 201
static const unsigned int | RESPONSE_CODE_ACCEPTED = 202
static const unsigned int | RESPONSE_CODE_NO_CONTENT = 204
static const unsigned int | RESPONSE_CODE_FOUND = 302
static const unsigned int | RESPONSE_CODE_UNAUTHORIZED = 401
static const unsigned int | RESPONSE_CODE_FORBIDDEN = 403
static const unsigned int | RESPONSE_CODE_NOT_FOUND = 404
static const unsigned int | RESPONSE_CODE_METHOD_NOT_ALLOWED = 405
static const unsigned int | RESPONSE_CODE_NOT_MODIFIED = 304
static const unsigned int | RESPONSE_CODE_BAD_REQUEST = 400
static const unsigned int | RESPONSE_CODE_SERVER_ERROR = 500
static const unsigned int | RESPONSE_CODE_NOT_IMPLEMENTED = 501
static const unsigned int | RESPONSE_CODE_CONTINUE = 100

## Detailed Description

message: base container for HTTP messages

Definition at line 55 of file message.hpp.

## Member Function Documentation

## add_cookie()

void pion::http::message::add_cookie | ( | const std::string & | key,
|  | const std::string & | value
| ) |  |

inline

adds a value for the cookie since cookie names are insensitive, key should use lowercase alpha chars

Definition at line 246 of file message.hpp.

## append_headers()

void pion::http::message::append_headers | ( | write_buffers_t & | write_buffers | ) |

inline protected

appends the message's HTTP headers to a vector of write buffers

Parameters

  write_buffers | the buffers to append HTTP headers into

Definition at line 585 of file message.hpp.

## change_cookie()

void pion::http::message::change_cookie | ( | const std::string & | key,
|  | const std::string & | value
| ) |  |

inline

changes the value of a cookie since cookie names are insensitive, key should use lowercase alpha chars

Definition at line 252 of file message.hpp.

## change_value()

template<typename DictionaryType >

static void pion::http::message::change_value | ( | DictionaryType & | dict,
|  | const std::string & | key,
|  | const std::string & | value
| ) |  |

inline static protected

Changes the value for a dictionary key. Adds the key if it does not already exist. If multiple values exist for the key, they will be removed and only the new value will remain.

Parameters

  dict | the dictionary object to update
  key | the key to change the value for
  value | the value to assign to the key

Definition at line 626 of file message.hpp.

Referenced by pion::http::request::change_query().

## clear_first_line()

void pion::http::message::clear_first_line | ( | void |  | ) | const

inline protected

erases the string containing the first line for the HTTP message (it will be updated the next time get_first_line() is called)

Definition at line 668 of file message.hpp.

Referenced by 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().

## concatenate_chunks()

void pion::http::message::concatenate_chunks | ( | void |  | ) |

pieces together all the received chunks

Definition at line 230 of file http_message.cpp.

References create_content_buffer(), and set_content_length().

Referenced by pion::http::parser::check_premature_eof(), pion::http::parser::finish(), and pion::http::parser::parse().

## create_content_buffer()

char* pion::http::message::create_content_buffer | ( | void |  | ) |

inline

creates a payload content buffer of size m_content_length and returns a pointer to the new buffer (memory is managed by message class)

Definition at line 338 of file message.hpp.

Referenced by concatenate_chunks(), pion::http::parser::finish(), pion::http::parser::finish_header_parsing(), pion::http::request::set_content(), and pion::http::request::use_query_params_for_post_content().

## delete_cookie()

void pion::http::message::delete_cookie | ( | const std::string & | key | ) |

inline

removes all values for a cookie since cookie names are insensitive, key should use lowercase alpha chars

Definition at line 258 of file message.hpp.

## delete_value()

template<typename DictionaryType >

static void pion::http::message::delete_value | ( | DictionaryType & | dict,
|  | const std::string & | key
| ) |  |

inline static protected

Deletes all values for a key

Parameters

  dict | the dictionary object to update
  key | the key to delete

Definition at line 657 of file message.hpp.

Referenced by pion::http::request::delete_query().

## get_cookie()

const std::string& pion::http::message::get_cookie | ( | const std::string & | key | ) | const

inline

returns a value for the cookie if any are defined; otherwise, an empty string since cookie names are insensitive, key should use lowercase alpha chars

Definition at line 229 of file message.hpp.

## get_value()

template<typename DictionaryType >

static const std::string& pion::http::message::get_value | ( | const DictionaryType & | dict,
|  | const std::string & | key
| ) |  |

inline static protected

Returns the first value in a dictionary if key is found; or an empty string if no values are found

Parameters

  dict | the dictionary to search for key
  key | the key to search for

Returns
  value if found; empty string if not

Definition at line 609 of file message.hpp.

Referenced by pion::http::request::get_query().

## has_cookie()

bool pion::http::message::has_cookie | ( | const std::string & | key | ) | const

inline

returns true if at least one value for the cookie is defined since cookie names are insensitive, key should use lowercase alpha chars

Definition at line 240 of file message.hpp.

## prepare_buffers_for_send()

void pion::http::message::prepare_buffers_for_send | ( | write_buffers_t & | write_buffers,
|  | const bool | keep_alive,
|  | const bool | using_chunks
| ) |  |

inline

initializes a vector of write buffers with the HTTP message information

Parameters

  write_buffers | vector of write buffers to initialize
  keep_alive | true if the connection should be kept alive
  using_chunks | true if the payload content will be sent in chunks

Definition at line 391 of file message.hpp.

Referenced by send(), and write().

## prepare_headers_for_send()

void pion::http::message::prepare_headers_for_send | ( | const bool | keep_alive,
|  | const bool | using_chunks
| ) |  |

inline protected

prepares HTTP headers for a send operation

Parameters

  keep_alive | true if the connection should be kept alive
  using_chunks | true if the payload content will be sent in chunks

Definition at line 568 of file message.hpp.

## read() [1/2]

std::size_t pion::http::message::read | ( | std::istream & | in,
|  | boost::system::error_code & | ec,
|  | parser & | http_parser
| ) |  |

reads a new message from a std::istream (blocks until finished)

Parameters

  in | std::istream to use
  ec | contains error code if the read fails
  http_parser | http parser object to use

Returns
  std::size_t number of bytes read from the connection

Definition at line 180 of file http_message.cpp.

References pion::http::parser::check_premature_eof(), clear(), pion::http::parser::get_total_bytes_read(), pion::http::parser::parse(), and pion::http::parser::set_read_buffer().

Referenced by read().

## read() [2/2]

std::size_t pion::http::message::read | ( | std::istream & | in,
|  | boost::system::error_code & | ec,
|  | bool | headers_only = `false`,
|  | std::size_t | max_content_length = `static_cast<size_t>(-1)`
| ) |  |

reads a new message from a std::istream (blocks until finished)

Parameters

  in | std::istream to use
  ec | contains error code if the read fails
  headers_only | if true then only HTTP headers are read
  max_content_length | maximum number of content bytes received

Returns
  std::size_t number of bytes read from the connection

Definition at line 219 of file http_message.cpp.

References pion::http::parser::parse_headers_only(), read(), and pion::http::parser::set_max_content_length().

## receive() [1/2]

std::size_t pion::http::message::receive | ( | tcp::connection & | tcp_conn,
|  | boost::system::error_code & | ec,
|  | parser & | http_parser
| ) |  |

receives a new message from a TCP connection (blocks until finished)

Parameters

  tcp_conn | TCP connection to use
  ec | contains error code if the receive fails
  http_parser | http parser object to use

Returns
  std::size_t number of bytes read from the connection

Definition at line 48 of file http_message.cpp.

References check_keep_alive(), pion::http::parser::check_premature_eof(), clear(), pion::http::parser::eof(), pion::http::parser::get_parse_headers_only(), pion::tcp::connection::get_pipelined(), pion::tcp::connection::get_read_buffer(), pion::http::parser::get_total_bytes_read(), pion::http::parser::load_read_pos(), pion::tcp::connection::load_read_pos(), pion::http::parser::parse(), pion::tcp::connection::read_some(), pion::tcp::connection::save_read_pos(), pion::tcp::connection::set_lifecycle(), and pion::http::parser::set_read_buffer().

Referenced by receive().

## receive() [2/2]

std::size_t pion::http::message::receive | ( | tcp::connection & | tcp_conn,
|  | boost::system::error_code & | ec,
|  | bool | headers_only = `false`,
|  | std::size_t | max_content_length = `static_cast<size_t>(-1)`
| ) |  |

receives a new message from a TCP connection (blocks until finished)

Parameters

  tcp_conn | TCP connection to use
  ec | contains error code if the receive fails
  headers_only | if true then only HTTP headers are received
  max_content_length | maximum number of content bytes received

Returns
  std::size_t number of bytes read from the connection

Definition at line 143 of file http_message.cpp.

References pion::http::parser::parse_headers_only(), receive(), and pion::http::parser::set_max_content_length().

## send()

std::size_t pion::http::message::send | ( | tcp::connection & | tcp_conn,
|  | boost::system::error_code & | ec,
|  | bool | headers_only = `false`
| ) |  |

sends the message over a TCP connection (blocks until finished)

Parameters

  tcp_conn | TCP connection to use
  ec | contains error code if the send fails
  headers_only | if true then only HTTP headers are sent

Returns
  std::size_t number of bytes written to the connection

Definition at line 33 of file http_message.cpp.

References get_content(), get_content_length(), pion::tcp::connection::get_keep_alive(), prepare_buffers_for_send(), and pion::tcp::connection::write().

## write()

std::size_t pion::http::message::write | ( | std::ostream & | out,
|  | boost::system::error_code & | ec,
|  | bool | headers_only = `false`
| ) |  |

writes the message to a std::ostream (blocks until finished)

Parameters

  out | std::ostream to use
  ec | contains error code if the write fails
  headers_only | if true then only HTTP headers are written

Returns
  std::size_t number of bytes written to the connection

Definition at line 154 of file http_message.cpp.

References get_content(), get_content_length(), and prepare_buffers_for_send().

## Member Data Documentation

## m_first_line

std::string pion::http::message::m_first_line

mutable protected

first line sent in an HTTP message (i.e. "GET / HTTP/1.1" for request, or "HTTP/1.1 200 OK" for response)

Definition at line 678 of file message.hpp.

Referenced by operator=(), pion::http::request::update_first_line(), and pion::http::response::update_first_line().

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

- include/pion/http/message.hpp
- src/http_message.cpp