# pion::net::HTTPMessage Class Reference

`#include <HTTPMessage.hpp>`

Inherits pion::net::HTTPTypes.

Inherited by pion::net::HTTPRequest, and pion::net::HTTPResponse.

List of all members.

## Detailed Description

HTTPMessage: base container for HTTP messages

Definition at line 37 of file HTTPMessage.hpp.

## Public Types

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

## Public Member Functions

| HTTPMessage (void)
| constructs a new HTTP message object
| HTTPMessage (const HTTPMessage &http_msg)
| copy constructor
HTTPMessage & | operator= (const HTTPMessage &http_msg)
| assignment operator
virtual | ~HTTPMessage ()
| virtual destructor
virtual void | clear (void)
| clears all message data
virtual bool | isContentLengthImplied (void) const =0
| should return true if the content length can be implied without headers
bool | isValid (void) const
| returns true if the message is valid
bool | getChunksSupported (void) const
| returns true if chunked transfer encodings are supported
boost::asio::ip::address & | getRemoteIp (void)
| returns IP address of the remote endpoint
boost::uint16_t | getVersionMajor (void) const
| returns the major HTTP version number
boost::uint16_t | getVersionMinor (void) const
| returns the minor HTTP version number
std::string | getVersionString (void) const
| returns a string representation of the HTTP version (i.e. "HTTP/1.1")
std::size_t | getContentLength (void) const
| returns the length of the payload content (in bytes)
bool | isChunked (void) const
| returns true if the message content is chunked
char * | getContent (void)
| returns a pointer to the payload content, or NULL if there is none
const char * | getContent (void) const
| returns a const pointer to the payload content, or NULL if there is none
ChunkCache & | getChunkCache (void)
| returns a reference to the chunk cache
const std::string & | getHeader (const std::string &key) const
| returns a value for the header if any are defined; otherwise, an empty string
Headers & | getHeaders (void)
| returns a reference to the HTTP headers
bool | hasHeader (const std::string &key) const
| returns true if at least one value for the header is defined
const std::string & | getCookie (const std::string &key) const
CookieParams & | getCookieParams (void)
| returns the cookie parameters
bool | hasCookie (const std::string &key) const
void | addCookie (const std::string &key, const std::string &value)
void | changeCookie (const std::string &key, const std::string &value)
void | deleteCookie (const std::string &key)
const std::string & | getFirstLine (void) const
| returns a string containing the first line for the HTTP message
bool | hasMissingPackets () const
| true if there were missing packets
void | setMissingPackets (bool newVal)
| set to true when missing packets detected
bool | hasDataAfterMissingPackets () const
| true if more data seen after the missing packets
void | setDataAfterMissingPacket (bool newVal)
void | setIsValid (bool b=true)
| sets whether or not the message is valid
void | setChunksSupported (bool b)
| set to true if chunked transfer encodings are supported
void | setRemoteIp (const boost::asio::ip::address &ip)
| sets IP address of the remote endpoint
void | setVersionMajor (const boost::uint16_t n)
| sets the major HTTP version number
void | setVersionMinor (const boost::uint16_t n)
| sets the minor HTTP version number
void | setContentLength (const std::size_t n)
| sets the length of the payload content (in bytes)
void | setDoNotSendContentLength (void)
| if called, the content-length will not be sent in the HTTP headers
DataStatus | getStatus () const
| return the data receival status
void | setStatus (DataStatus newVal)
void | updateContentLengthUsingHeader (void)
| sets the length of the payload content using the Content-Length header
void | updateTransferCodingUsingHeader (void)
| sets the transfer coding using the Transfer-Encoding header
char * | createContentBuffer (void)
void | setContent (const std::string &content)
| resets payload content to match the value of a string
void | clearContent (void)
| clears payload content buffer
void | setContentType (const std::string &type)
| sets the content type for the message payload
void | addHeader (const std::string &key, const std::string &value)
| adds a value for the HTTP header named key
void | changeHeader (const std::string &key, const std::string &value)
| changes the value for the HTTP header named key
void | deleteHeader (const std::string &key)
| removes all values for the HTTP header named key
bool | checkKeepAlive (void) const
| returns true if the HTTP connection may be kept alive
void | prepareBuffersForSend (WriteBuffers &write_buffers, const bool keep_alive, const bool using_chunks)
std::size_t | send (TCPConnection &tcp_conn, boost::system::error_code &ec, bool headers_only=false)
std::size_t | receive (TCPConnection &tcp_conn, boost::system::error_code &ec, bool headers_only=false)
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, bool headers_only=false)
void | concatenateChunks (void)

## Protected Member Functions

void | prepareHeadersForSend (const bool keep_alive, const bool using_chunks)
void | appendHeaders (WriteBuffers &write_buffers)
void | clearFirstLine (void) const
virtual void | updateFirstLine (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 & | getValue (const DictionaryType &dict, const std::string &key)
template<typename DictionaryType>
static void | changeValue (DictionaryType &dict, const std::string &key, const std::string &value)
template<typename DictionaryType>
static void | deleteValue (DictionaryType &dict, const std::string &key)

## Protected Attributes

std::string | m_first_line

## Classes

struct | ReceiveError
| data type for library errors returned during receive() operations More...

## Member Function Documentation

void pion::net::HTTPMessage::addCookie | ( | 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 229 of file HTTPMessage.hpp.

void pion::net::HTTPMessage::appendHeaders | ( | WriteBuffers & | 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 468 of file HTTPMessage.hpp.

void pion::net::HTTPMessage::changeCookie | ( | 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 235 of file HTTPMessage.hpp.

template<typename DictionaryType>

static void pion::net::HTTPMessage::changeValue | ( | 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 506 of file HTTPMessage.hpp.

Referenced by pion::net::HTTPRequest::changeQuery().

void pion::net::HTTPMessage::clearFirstLine | ( | void |  | ) | const`[inline, protected]`

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

Definition at line 548 of file HTTPMessage.hpp.

Referenced by pion::net::HTTPRequest::setMethod(), pion::net::HTTPRequest::setQueryString(), pion::net::HTTPRequest::setResource(), pion::net::HTTPResponse::setStatusCode(), and pion::net::HTTPResponse::setStatusMessage().

void pion::net::HTTPMessage::concatenateChunks | ( | void |  | ) |

pieces together all the received chunks

Definition at line 206 of file HTTPMessage.cpp.

References createContentBuffer(), and setContentLength().

Referenced by pion::net::HTTPParser::checkPrematureEOF(), pion::net::HTTPParser::finish(), and pion::net::HTTPParser::parse().

char* pion::net::HTTPMessage::createContentBuffer | ( | void |  | ) | `[inline]`

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

Definition at line 321 of file HTTPMessage.hpp.

Referenced by concatenateChunks(), pion::net::HTTPParser::finish(), pion::net::HTTPParser::finishHeaderParsing(), pion::net::HTTPRequest::setContent(), and pion::net::HTTPRequest::useQueryParamsForPostContent().

void pion::net::HTTPMessage::deleteCookie | ( | const std::string & | key | ) | `[inline]`

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

Reimplemented in pion::net::HTTPResponse.

Definition at line 241 of file HTTPMessage.hpp.

template<typename DictionaryType>

static void pion::net::HTTPMessage::deleteValue | ( | 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 537 of file HTTPMessage.hpp.

Referenced by pion::net::HTTPRequest::deleteQuery().

const std::string& pion::net::HTTPMessage::getCookie | ( | 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 212 of file HTTPMessage.hpp.

template<typename DictionaryType>

static const std::string& pion::net::HTTPMessage::getValue | ( | 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 489 of file HTTPMessage.hpp.

Referenced by pion::net::HTTPRequest::getQuery().

bool pion::net::HTTPMessage::hasCookie | ( | 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 223 of file HTTPMessage.hpp.

void pion::net::HTTPMessage::prepareBuffersForSend | ( | WriteBuffers & | 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 375 of file HTTPMessage.hpp.

Referenced by send(), and write().

void pion::net::HTTPMessage::prepareHeadersForSend | ( | 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 451 of file HTTPMessage.hpp.

std::size_t pion::net::HTTPMessage::read | ( | std::istream & | in,
|  | boost::system::error_code & | ec,
|  | bool | headers_only = `false` |
| ) |  |  |

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

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

Definition at line 163 of file HTTPMessage.cpp.

References pion::net::HTTPParser::checkPrematureEOF(), clear(), pion::net::HTTPParser::getTotalBytesRead(), pion::net::HTTPParser::parse(), pion::net::HTTPParser::parseHeadersOnly(), and pion::net::HTTPParser::setReadBuffer().

std::size_t pion::net::HTTPMessage::receive | ( | TCPConnection & | tcp_conn,
|  | boost::system::error_code & | ec,
|  | bool | headers_only = `false` |
| ) |  |  |

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

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

Definition at line 47 of file HTTPMessage.cpp.

References checkKeepAlive(), pion::net::HTTPParser::checkPrematureEOF(), clear(), pion::net::HTTPParser::eof(), pion::net::TCPConnection::getPipelined(), pion::net::TCPConnection::getReadBuffer(), pion::net::HTTPParser::getTotalBytesRead(), pion::net::HTTPParser::loadReadPosition(), pion::net::TCPConnection::loadReadPosition(), pion::net::HTTPParser::parse(), pion::net::HTTPParser::parseHeadersOnly(), pion::net::TCPConnection::read_some(), pion::net::TCPConnection::saveReadPosition(), pion::net::TCPConnection::setLifecycle(), and pion::net::HTTPParser::setReadBuffer().

std::size_t pion::net::HTTPMessage::send | ( | TCPConnection & | 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 31 of file HTTPMessage.cpp.

References getContent(), getContentLength(), pion::net::TCPConnection::getKeepAlive(), prepareBuffersForSend(), and pion::net::TCPConnection::write().

std::size_t pion::net::HTTPMessage::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 137 of file HTTPMessage.cpp.

References getContent(), getContentLength(), and prepareBuffersForSend().

## Member Data Documentation

std::string pion::net::HTTPMessage::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 559 of file HTTPMessage.hpp.

Referenced by operator=(), pion::net::HTTPResponse::updateFirstLine(), and pion::net::HTTPRequest::updateFirstLine().

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

- net/include/pion/net/HTTPMessage.hpp
- net/src/HTTPMessage.cpp