Kea: isc::http::HttpMessage Class Reference

| Kea 3.2.0-git

isc::http::HttpMessage Class Referenceabstract

Base class for HttpRequest and HttpResponse. More...

`#include <http_message.h>`

Inheritance diagram for isc::http::HttpMessage:
[legend]

## Public Types
enum | Direction { INBOUND , OUTBOUND }
| Specifies the direction of the HTTP message. More...

## Public Member Functions
| HttpMessage (const Direction &direction)
| Constructor.
virtual | ~HttpMessage ()
| Destructor.
virtual void | create ()=0
| Reads parsed message from the context, validates the message and stores parsed information.
virtual void | finalize ()=0
| Complete parsing HTTP message or creating an HTTP outbound message.
virtual std::string | getBody () const =0
| Returns HTTP message body as string.
Direction | getDirection () const
| Returns HTTP message direction.
HttpHeaderPtr | getHeader (const std::string &header_name) const
| Returns object encapsulating HTTP header.
std::string | getHeaderValue (const std::string &header_name) const
| Returns a value of the specified HTTP header.
uint64_t | getHeaderValueAsUint64 (const std::string &header_name) const
| Returns a value of the specified HTTP header as number.
HttpVersion | getHttpVersion () const
| Returns HTTP version number (major and minor).
bool | isFinalized () const
| Checks if the message has been successfully finalized.
void | requireHeader (const std::string &header_name)
| Specifies a required HTTP header for the HTTP message.
void | requireHeaderValue (const std::string &header_name, const std::string &header_value)
| Specifies a required value of a header in the message.
void | requireHttpVersion (const HttpVersion &version)
| Specifies HTTP version allowed.
bool | requiresBody () const
| Checks if the body is required for the HTTP message.
virtual void | reset ()=0
| Reset the state of the object.
void | setDirection (const Direction &direction)
| Sets direction for the HTTP message.
virtual std::string | toString () const =0
| Returns HTTP message as text.

## Protected Types
typedef std::map< std::string, HttpHeaderPtr > | HttpHeaderMap
| Map of HTTP headers indexed by lower case header names.

## Protected Member Functions
void | checkCreated () const
| Checks if the create was called.
void | checkFinalized () const
| Checks if the finalize was called.
template<typename T>
bool | inRequiredSet (const T &element, const std::set< T > &element_set) const
| Checks if the set is empty or the specified element belongs to this set.

## Protected Attributes
bool | created_
| Flag indicating whether create was called.
Direction | direction_
| Message direction (inbound or outbound).
bool | finalized_
| Flag indicating whether finalize was called.
HttpHeaderMap | headers_
| Parsed HTTP headers.
HttpVersion | http_version_
| HTTP version numbers.
HttpHeaderMap | required_headers_
| Map holding required HTTP headers.
std::set< HttpVersion > | required_versions_
| Set of required HTTP versions.

## Detailed Description

Base class for HttpRequest and HttpResponse.

This abstract class provides a common functionality for the HTTP requests and responses. Each such message can be marked as outbound or inbound. An HTTP inbound request is the one received by the server and HTTP inbound response is the response received by the client. Conversely, an HTTP outbound request is the request created by the client and HTTP outbound response is the response created by the server. There are differences in how the inbound and outbound messages are created. The inbound messages are received over the TCP sockets and parsed by the parsers. The parsed information is stored in a context, i.e. structure holding raw information and associated with the given `HttpMessage` instance. Once the message is parsed and all required information is stored in the context, the `create` method is called to validate and fetch information from the context into the message. The `finalize` method is called to commit the HTTP message body into the message.

The outbound message is created locally from the known data, e.g. HTTP version number, URI, method etc. The headers can be then appended to the message via the context. In order to use this message the `finalize` method must be called to commit this information. Them, `toString` method can be called to generate the message in the textual form, which can be transferred via TCP socket.

Definition at line 62 of file http_message.h.

## Member Typedef Documentation

## ◆ HttpHeaderMap

typedef std::map<std::string, HttpHeaderPtr> isc::http::HttpMessage::HttpHeaderMap
| protected

Map of HTTP headers indexed by lower case header names.

Definition at line 241 of file http_message.h.

## Member Enumeration Documentation

## ◆ Direction

enum isc::http::HttpMessage::Direction

Specifies the direction of the HTTP message.

Enumerator
INBOUND |
OUTBOUND |

Definition at line 66 of file http_message.h.

## Constructor & Destructor Documentation

## ◆ HttpMessage()

isc::http::HttpMessage::HttpMessage | ( | const Direction & | direction | ) |
| explicit

Constructor.

Parameters

  direction | Direction of the message (inbound or outbound).

Definition at line 14 of file http_message.cc.

References created_, direction_, finalized_, headers_, http_version_, required_headers_, and required_versions_.

Referenced by isc::http::HttpRequest::HttpRequest(), isc::http::HttpRequest::HttpRequest(), isc::http::HttpResponse::HttpResponse(), and isc::http::HttpResponse::HttpResponse().

## ◆ ~HttpMessage()

isc::http::HttpMessage::~HttpMessage | ( |  | ) |
| virtual

Destructor.

Definition at line 20 of file http_message.cc.

## Member Function Documentation

## ◆ checkCreated()

void isc::http::HttpMessage::checkCreated | ( |  | ) | const
| protected

Checks if the create was called.

Exceptions

  HttpMessageError | if create wasn't called.

Definition at line 90 of file http_message.cc.

References created_, and isc_throw.

Referenced by getHeader(), getHttpVersion(), isc::http::HttpRequest::getMethod(), isc::http::HttpResponse::getStatusCode(), isc::http::HttpResponse::getStatusPhrase(), and isc::http::HttpRequest::getUri().

## ◆ checkFinalized()

void isc::http::HttpMessage::checkFinalized | ( |  | ) | const
| protected

Checks if the finalize was called.

Exceptions

  HttpMessageError | if finalize wasn't called.

Definition at line 99 of file http_message.cc.

References finalized_, and isc_throw.

Referenced by isc::http::HttpRequest::getBody(), isc::http::HttpResponse::getBody(), isc::http::HttpResponseJson::getBodyAsJson(), isc::http::PostHttpRequestJson::getBodyAsJson(), isc::http::HttpRequest::toBriefString(), isc::http::HttpResponse::toBriefString(), and isc::http::HttpRequest::toString().

## ◆ create()

virtual void isc::http::HttpMessage::create | ( |  | ) |
| pure virtual

Reads parsed message from the context, validates the message and stores parsed information.

This method must be called before retrieving parsed data using accessors. This method doesn't parse the HTTP request body.

Implemented in isc::http::HttpRequest, and isc::http::HttpResponse.

## ◆ finalize()

virtual void isc::http::HttpMessage::finalize | ( |  | ) |
| pure virtual

Complete parsing HTTP message or creating an HTTP outbound message.

This method is used in two situations: when a message has been received into a context and may be fully parsed (including the body) or when the data for the creation of the outbound message have been stored in a context and the message can be now created from the context.

This method should call `create` method if it hasn't been called yet and then read the message body from the context and interpret it. If the body doesn't adhere to the requirements for the message (in particular, when the content type of the body is invalid) an exception should be thrown.

Implemented in isc::http::HttpRequest, isc::http::HttpResponse, isc::http::HttpResponseJson, and isc::http::PostHttpRequestJson.

## ◆ getBody()

virtual std::string isc::http::HttpMessage::getBody | ( |  | ) | const
| pure virtual

Returns HTTP message body as string.

Implemented in isc::http::HttpRequest, and isc::http::HttpResponse.

## ◆ getDirection()

Direction isc::http::HttpMessage::getDirection | ( |  | ) | const
| inline

Returns HTTP message direction.

Definition at line 80 of file http_message.h.

References direction_.

Referenced by isc::http::HttpRequest::create(), and isc::http::HttpResponse::create().

## ◆ getHeader()

HttpHeaderPtr isc::http::HttpMessage::getHeader | ( | const std::string & | header_name | ) | const

Returns object encapsulating HTTP header.

Parameters

  header_name | HTTP header name.

Returns
  Non-null pointer to the header.

Exceptions

  HttpMessageNonExistingHeader | if header with the specified name doesn't exist.
  HttpMessageError | if the request hasn't been created.

Definition at line 60 of file http_message.cc.

References checkCreated(), isc::http::HttpHeader::getLowerCaseName(), headers_, and isc_throw.

Referenced by getHeaderValue(), getHeaderValueAsUint64(), isc::http::HttpRequest::isPersistent(), and isc::http::HttpRequest::toString().

Here is the call graph for this function:

## ◆ getHeaderValue()

std::string isc::http::HttpMessage::getHeaderValue | ( | const std::string & | header_name | ) | const

Returns a value of the specified HTTP header.

Parameters

  header_name | Name of the HTTP header.

Exceptions

  HttpMessageError | if the header doesn't exist.

Definition at line 74 of file http_message.cc.

References getHeader().

Here is the call graph for this function:

## ◆ getHeaderValueAsUint64()

uint64_t isc::http::HttpMessage::getHeaderValueAsUint64 | ( | const std::string & | header_name | ) | const

Returns a value of the specified HTTP header as number.

Parameters

  header_name | Name of the HTTP header.

Exceptions

  HttpMessageError | if the header doesn't exist or if the header value is not number.

Definition at line 79 of file http_message.cc.

References getHeader(), and isc_throw.

Here is the call graph for this function:

## ◆ getHttpVersion()

HttpVersion isc::http::HttpMessage::getHttpVersion | ( |  | ) | const

Returns HTTP version number (major and minor).

Definition at line 54 of file http_message.cc.

References checkCreated(), and http_version_.

Referenced by isc::http::HttpRequest::isPersistent(), and isc::http::HttpRequest::toBriefString().

Here is the call graph for this function:

## ◆ inRequiredSet()

template<typename T>

bool isc::http::HttpMessage::inRequiredSet | ( | const T & | element,
|  | const std::set< T > & | element_set ) const
| inlineprotected

Checks if the set is empty or the specified element belongs to this set.

This is a convenience method used by the class to verify that the given HTTP method belongs to "required methods", HTTP version belongs to "required versions" etc.

Parameters

  element | Reference to the element.
  element_set | Reference to the set of elements.

Template Parameters

  T | Element type, HttpVersion etc.

Returns
  true if the element set is empty or if the element belongs to the set.

Definition at line 224 of file http_message.h.

Referenced by isc::http::HttpRequest::create(), and isc::http::HttpResponse::create().

## ◆ isFinalized()

bool isc::http::HttpMessage::isFinalized | ( |  | ) | const
| inline

Checks if the message has been successfully finalized.

The message gets finalized on successful call to `finalize`.

Returns
  true if the message has been finalized, false otherwise.

Definition at line 194 of file http_message.h.

References finalized_.

## ◆ requireHeader()

void isc::http::HttpMessage::requireHeader | ( | const std::string & | header_name | ) |

Specifies a required HTTP header for the HTTP message.

Required headers must be specified prior to calling create method. The specified header must exist in the received HTTP request. This puts no requirement on the header value.

Parameters

  header_name | Required header name.

Definition at line 29 of file http_message.cc.

References required_headers_.

Referenced by isc::http::PostHttpRequest::PostHttpRequest(), and isc::http::PostHttpRequest::PostHttpRequest().

## ◆ requireHeaderValue()

void isc::http::HttpMessage::requireHeaderValue | ( | const std::string & | header_name,
|  | const std::string & | header_value )

Specifies a required value of a header in the message.

Required header values must be specified prior to calling create method. The specified header must exist and its value must be equal to the value specified as second parameter.

Parameters

  header_name | HTTP header name.
  header_value | HTTP header value.

Definition at line 37 of file http_message.cc.

References required_headers_.

Referenced by isc::http::PostHttpRequestJson::PostHttpRequestJson(), and isc::http::PostHttpRequestJson::PostHttpRequestJson().

## ◆ requireHttpVersion()

void isc::http::HttpMessage::requireHttpVersion | ( | const HttpVersion & | version | ) |

Specifies HTTP version allowed.

Allowed HTTP versions must be specified prior to calling create method. If no version is specified, all versions are allowed.

Parameters

  version | Version number allowed for the request.

Definition at line 24 of file http_message.cc.

References required_versions_, and version().

Here is the call graph for this function:

## ◆ requiresBody()

bool isc::http::HttpMessage::requiresBody | ( |  | ) | const

Checks if the body is required for the HTTP message.

Current implementation simply checks if the "Content-Length" header is required.

Returns
  true if the body is required, false otherwise.

Definition at line 44 of file http_message.cc.

References required_headers_.

## ◆ reset()

virtual void isc::http::HttpMessage::reset | ( |  | ) |
| pure virtual

Reset the state of the object.

Implemented in isc::http::HttpRequest, isc::http::HttpResponse, isc::http::HttpResponseJson, and isc::http::PostHttpRequestJson.

Referenced by isc::http::PostHttpRequestJson::reset().

## ◆ setDirection()

void isc::http::HttpMessage::setDirection | ( | const Direction & | direction | ) |
| inline

Sets direction for the HTTP message.

This is mostly useful in unit testing.

Parameters

  direction | New direction of the HTTP message.

Definition at line 89 of file http_message.h.

References direction_.

## ◆ toString()

virtual std::string isc::http::HttpMessage::toString | ( |  | ) | const
| pure virtual

Returns HTTP message as text.

This method is called to generate the outbound HTTP message. Make sure to call `finalize` prior to calling this method.

Implemented in isc::http::HttpRequest, and isc::http::HttpResponse.

## Member Data Documentation

## ◆ created_

bool isc::http::HttpMessage::created_
| protected

Flag indicating whether create was called.

Definition at line 253 of file http_message.h.

Referenced by HttpMessage(), checkCreated(), isc::http::HttpRequest::create(), isc::http::HttpResponse::create(), isc::http::HttpRequest::finalize(), isc::http::HttpResponse::finalize(), isc::http::HttpResponseJson::finalize(), isc::http::PostHttpRequestJson::finalize(), isc::http::HttpRequest::reset(), and isc::http::HttpResponse::reset().

## ◆ direction_

Direction isc::http::HttpMessage::direction_
| protected

Message direction (inbound or outbound).

Definition at line 230 of file http_message.h.

Referenced by HttpMessage(), getDirection(), and setDirection().

## ◆ finalized_

bool isc::http::HttpMessage::finalized_
| protected

Flag indicating whether finalize was called.

Definition at line 256 of file http_message.h.

Referenced by HttpMessage(), checkFinalized(), isc::http::HttpRequest::finalize(), isc::http::HttpResponse::finalize(), isc::http::HttpResponseJson::finalize(), isc::http::PostHttpRequestJson::finalize(), isFinalized(), isc::http::HttpRequest::reset(), and isc::http::HttpResponse::reset().

## ◆ headers_

HttpHeaderMap isc::http::HttpMessage::headers_
| protected

Parsed HTTP headers.

Definition at line 259 of file http_message.h.

Referenced by HttpMessage(), isc::http::HttpRequest::create(), isc::http::HttpResponse::create(), getHeader(), isc::http::HttpRequest::reset(), isc::http::HttpResponse::reset(), isc::http::HttpRequest::toString(), and isc::http::HttpResponse::toString().

## ◆ http_version_

HttpVersion isc::http::HttpMessage::http_version_
| protected

HTTP version numbers.

Definition at line 238 of file http_message.h.

Referenced by HttpMessage(), isc::http::HttpRequest::create(), isc::http::HttpResponse::create(), getHttpVersion(), and isc::http::HttpResponse::toBriefString().

## ◆ required_headers_

HttpHeaderMap isc::http::HttpMessage::required_headers_
| protected

Map holding required HTTP headers.

The key of this map specifies the lower case HTTP header name. If the value of the HTTP header is empty, the header is required but the value of the header is not checked. If the value is non-empty, the value in the HTTP request must be equal (case insensitive) to the value in the map.

Definition at line 250 of file http_message.h.

Referenced by HttpMessage(), isc::http::HttpRequest::create(), isc::http::HttpResponse::create(), requireHeader(), requireHeaderValue(), and requiresBody().

## ◆ required_versions_

std::set<HttpVersion> isc::http::HttpMessage::required_versions_
| protected

Set of required HTTP versions.

If the set is empty, all versions are allowed.

Definition at line 235 of file http_message.h.

Referenced by HttpMessage(), isc::http::HttpRequest::create(), isc::http::HttpResponse::create(), and requireHttpVersion().

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

- http_message.h
- http_message.cc