This part of the documentation talks about the publicly accessible API of the HTTP Request objects. This section details the Request Concepts requirements, the implemented and required Directives, Modifiers, and Wrappers that work with the HTTP Request objects.
There are two generally supported Request Concepts implemented in the library. The first of two is the Normal Client Request Concept and the second is the Pod Server Request Concept.
The Normal Client Request Concept is what the HTTP Client interface requires. All operations performed internally by the HTTP Client abide by the interface required by this concept definition.
The Pod Server Request Concept is as the name suggests what the HTTP Server implementation requires from Request Objects.
Switching on whether the Request concept chooses either of the Normal Client Request Concept or the Pod Server Request Concept is done through the nested tag type and whether that tag derives from the root tag pod. Simply, if the Request type’s nested tag type derives from boost::network::tags::pod then it chooses to enforce the Pod Server Request Concept, otherwise it chooses the Normal Client Request Concept.
A type models the Normal Client Request Concept if it models the Message Concept and also supports the following constructs.
Legend
| R: | The request type. |
|---|---|
| r: | An instance of R. |
| S: | The string type. |
| s: | An instance of S. |
| P: | The port type. |
| p: | An instance of P. |
| Construct | Result | Description |
|---|---|---|
| R::string_type | S | The nested string_type type. |
| R::port_type | P | The nested port_type type. |
| R r(s) | NA | Construct a Request with an s provided. This treats s as the URI to where the request is destined for. |
| host(request) | Convertible to S | Return the host to where the request is destined for. |
| port(request) | Convertible to P | Return the port to where the request is destined for. |
| path(request) | Convertible to S | Return the path included in the URI. |
| query(request) | Convertible to S | Return the query part of the URI. |
| anchor(request) | Convertible to S | Return the anchor part of the URI. |
| protocol(request) | Convertible to S | Return the protocol/scheme part of the URI. |
| r << uri(s) | R& | Set the URI of the request. |
| uri(r, s) | void | Set the URI of the request. |
A type models the Pod Server Request Concept if it models the Message Concept and also supports the following constructs.
Legend
| R: | The request type. |
|---|---|
| r: | An instance of R. |
| S: | The string type. |
| I: | An unsigned 8 bit integer. |
| V: | The vector type for headers. |
| Construct | Result | Description |
|---|---|---|
| R::string_type | S | The nested string_type type. |
| R::headers_container_type | V | The nested headers_container_type type. |
| r.source | S | The nested source of the request. |
| r.method | S | The method of the request. |
| r.destination | S | The destination of the request. This is normally the URI of the request. |
| r.version_major | I | The major version number part of the request. |
| r.version_minor | I | The minor version number part of the request. |
| r.headers | V | The vector of headers. |
| r.body | S | The body of the request. |
This section details the provided directives that are provided by cpp-netlib. The section was written to assume that an appropriately constructed request instance is either of the following:
boost::network::http::basic_request<
boost::network::http::tags::http_default_8bit_udp_resolve
> request;
// or
boost::network::http::basic_request<
boost::network::http::tags::http_server
> request;
The section also assumes that there following using namespace declaration is in effect:
using namespace boost::network;
Directives are meant to be used in the following manner:
request << directive(...);
Warning
There are two versions of directives, those that are applicable to messages that support narrow strings (std::string) and those that are applicable to messages that support wide strings (std::wstring). The cpp-netlib implementation still does not convert wide strings into UTF-8 encoded narrow strings. This will be implemented in subsequent library releases.
For now all the implemented directives are listed, even if some of them still do not implement things correctly.
This section details the provided modifiers that are provided by cpp-netlib.
This section details the provided request wrappers that come with cpp-netlib. Wrappers are used to convert a message into a different type, usually providing accessor operations to retrieve just part of the message. This section assumes that the following using namespace directives are in effect:
using namespace boost::network;
using namespace boost::network::http;