C++ Network Library Code

113 lines (73 with data), 4.3 kB

[/
  (C) Copyright 2008 Glyn Matthews.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]


[section:http HTTP]
The __cnl__ provides direct support for HTTP.  A motivating example will show how it's intended to work:

 #include <boost/network/protocol/http.hpp>
 #include <iostream>

 int
 main(int argc, char *argv[]) {
     using boost::network;

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

     // print response headers
     headers_range<http::response>::type hdrs = headers(response);
     boost::range_iterator<headers_range<http::response>::type>::type
         it = boost::begin(hdrs), end = boost::end(hdrs);
     for (; it != end; ++it) {
         std::cout << it->first << ": " << it->second << std::endl;
     }

     // print response body
     std::cout << body(response) << std::endl;
     return 0;
 }


Before walking through exactly what is happening in this example, the principle components are described below:

[heading HTTP Request]

 #include <boost/network/protocol/http/request.hpp>

The [^request] encapsulates information about the request and the resource.

[heading HTTP Client]

 #include <boost/network/protocol/http/client.hpp>

The [^client] encapsulates the connection-mapping logic between the domain and the underlying socket.  Access to a resource is managed through the [^client] object.

[heading HTTP Response]

 #include <boost/network/protocol/http/response.hpp>

The [^response] encapsulates the data received from the server.

[heading Walkthrough]

 http::request request("http://www.boost.org/");

This line frames the request for the resource __boost_org__.  This is slightly different to what one would normally expect from a request type, but there are good reasons for this.  Consider a [^request] object as the base unit of data used to instruct the client what to do.

 http::client client;

Then a client is created that handles all HTTP requests and responses.

 http::response response = client.get(request);

The client performs the requests on the developer's behalf.  This might initially appear counter-intuitive, since the methods GET, POST, PUT and DELETE are associated with a request to an HTTP server.

There are several advantages to this design:

# A [^client] object manages the connection, unencumbering the developer with this task, allowing them to better craft requests;
# A [^request] can be used with any instance of the [^client] without binding the [^client] to any destination;
# By decoupling the method from the [^request] object it allows developers to create requests that may be re-used (e.g. perform a HEAD first; if the the headers don't fulfil a certain criteria, perform a GET using the same resource).

 // print response headers
 headers_range<http::response>::type hdrs = headers(response);
 boost::range_iterator<headers_range<http::response>::type>::type
     it = boost::begin(hdrs), end = boost::end(hdrs);
 for (; it != end; ++it) 
    std::cout << it->first << ": " << it->second << std::endl;
 }

 // print response body
 std::cout << body(response) << std::endl;

Once the request has been made, and the [^client] returns a [^response] object, the rest is simple.  This example outputs all the response headers and body, in this case just the Boost homepage.


[heading Using [^http::client]]

The [^http::client] supports the following operations:

* [^http::client::head]
* [^http::client::get]
* [^http::client::post]
* [^http::client::put]
* [^http::client::delete_]

HTTP features can be enabled by using constructor arguments:

* [^http::client(http::client::cache_resolved)]
* [^http::client(http::client::follow_redirect)]

[h5 [^http::client::cache_resolved]]
This argument enables the caching of resolved endpoints and prevents the client from resolving IP addresses of previously resolved hostnames.

[h5 [^http::client::follow_redirect(s)]]
[^http::client::follow_redirects] / [^http::client::follow_redirect] follow HTTP redirect(s) (300..307) by looking at the "Location" header provided by the response(s); headers present in the original request are preserved in the subsequent request(s).

[endsect]