HTTP implementation — cpp-netlib v0.11.0

### Navigation

- next
- previous |
- cpp-netlib v0.11.0 »
- An in-depth look at the `cpp-netlib` »

# HTTP implementation

## HTTP client

At the heart of the HTTP client implementation is a single class aptly named `basic_client`, which is also a template. The template `basic_client` takes three template parameters:

    namespace boost { namespace http {

        template <class Tag, unsigned version_major, unsigned version_minor>
        struct basic_client;

    } // namespace http

    } // namespace boost

The `Tag` template parameter follows the same tag-dispatch mechanism to determine the behavior of the `basic_client`. The interface of `basic_client` may change depending on certain properties defined for the tag you provide. Below is a table of predefined supported tags you can use in your overload of the `basic_client`:

Tag | Description
--- | ---
http_default_8bit_tcp_resolve | This is the default HTTP implementation tag that resolves addresses with a TCP resolver and provides a synchronous/blocking HTTP client interface.
http_default_8bit_udp_resolve | This is similar to the above tag except that it specifies the HTTP client to use a UDP resolver. It also provides a synchronous/ blocking HTTP client interface.
http_keepalive_8bit_tcp_resolve | This tag specifies that the HTTP client by default will keep connections to the server alive. It only makes sense if the `version_major` and `version_minor` are both `1`, to indicate HTTP 1.1. This tag causes the HTTP client to resolve using a TCP resolver and provides a synchronous/ blocking HTTP client interface.
http_keepalive_8bit_udp_resolve | This is similar to the above tag except that it specifies the HTTP client to use a UDP resolver. It also provides a synchronous/ blocking HTTP client interface.
http_async_8bit_tcp_resolve | This tag provides an active HTTP client object implementation that uses a TCP resolver. Response objects returned will encapsulate a number of Boost.Thread shared futures to hold values. Users don’t have to see this as they are implementation details.
http_async_8bit_udp_resolve | This is similar to the above tag except that specifies the HTTP client to use a UDP resolver.

The default typedef for the HTTP client that is provided uses the `http_async_8bit_udp_resolve` tag, and implements HTTP 1.1. The exact typedef is in the `boost::network::http` namespace as the following:

    namespace boost { namespace network { namespace http {

        typedef basic_client<tags::http_async_8bit_udp_resolve, 1, 1>
            client;

    }}}

This type has nested typedefs for the correct types for the `basic_request` and `basic_response` templates. To use the correct types for `basic_request` or `basic_response` you can use these nested typedefs like so:

    boost::network::http::client::request request;
    boost::network::http::client::response response;

    // or...
    using namespace boost::network;
    http::client::request request;
    http::client::response response;

Typical use cases for the HTTP client would look something like the following:

    using namespace boost::network;
    http::request request("http://www.boost.org/");
    request << header("Connection", "close");

The `basic_client` implements all HTTP methods as member functions (HEAD, GET, POST, PUT, DELETE). Therefore, the code to make an HTTP request looks trivially simple:

    using namespace boost::network;
    http::client client;
    http::client::request request("http://www.boost.org/");
    http::client::response response = client.get(request);

Accessing data from `http::response` is done using wrappers. To get the response headers, we use the `headers` wrapper which returns, in the default case, a multimap of strings to strings:

    using namespace boost::network;
    typedef headers_range<http_client::response>::type response_headers;
    boost::range_iterator<response_headers>::type iterator;

    response_headers headers_ = headers(response);
    for (iterator it = headers_.begin(); it != headers_.end(); ++it) {
        std::cout << it->first << ": " << it->second << std::endl;
    }
    std::cout << std::endl;

## HTTP server

As with the HTTP client, the HTTP server that is provided with cpp-netlib is extensible through the tag mechanism and is embeddable. The template class declaration of `basic_server` is given below:

    namespace boost { namespace network { namespace http {

        template <class Tag, class RequestHandler> basic_server;

    }}}

The second template argument is used to specify the request handler type. The request handler type is a functor type which should overload the function call operator (`RequestHandler::operator()` should be overloaded) that takes two parameters: the first one being a reference to a `const basic_request<Tag>` and the second being a reference to a `basic_response<Tag>` instance.

All the logic for parsing the HTTP request and building the `const basic_request<Tag>` object resides internally in the `basic_server` template. Processing the request is delegated to the `RequestHandler` type, and the assumption of which would be that the response is formed inside the `RequestHandler` function call operator overload.

The `basic_server` template however is only an underlying implementation while the user-visible implementation is the `http::server` template. This simply specializes the `basic_server` template to use the `default_` tag and forwards the `RequestHandler` parameter:

    namespace boost { namespace network { namespace http {

        template <class RequestHandler>
        class server :
            public basic_server<default_, RequestHandler> {};

    }}}

To use the forwarding server type you just supply the request handler implementation as the parameter. For example, an “echo” server example might look something like this:

    using namespace boost::network;
    struct echo;
    typedef http::server<echo> echo_server;

    struct echo {
        void operator () (const echo_server::request &request,
                          echo_server::response &response) const {
            std::string ip = source(request);
            response = echo_server::response::stock_reply(
                echo_server::response::ok,
                body(request));
            std::cerr << "[" << ip << "]: " << request.uri <<
                " status = " << echo_server::response::ok << '\n';
        }
    };

Here, all we’re doing is returning the original request body with an HTTP OK response (200). We are also printing the IP address from where the request came from. Notice that we are using a wrapper to access the source of the request.

### Navigation

- next
- previous |
- cpp-netlib v0.11.0 »
- An in-depth look at the `cpp-netlib` »