Describing the available tags for the HTTP client, changing the description of the implementation.

Author: deanberris

libs/network/doc/http.rst

@@ -4,49 +4,128 @@ HTTP implementation
 HTTP client
 ```````````
 
-The cpp-netlib HTTP client is composed of three template classes:
+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:
 
 .. code-block:: c++
 
-    namespace http {
-    template <class Tag> basic_request;
-    template <class Tag> basic_response;
-    template <class Tag> basic_client;
-    typedef basic_request<default_> request;
-    typedef basic_response<default_> response;
-    typedef basic_client<default_> client;
-    }
+    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.                                   |
++---------------------------------+---------------------------------------------+
+
+.. _Boost.Thread: http://www.boost.org/libs/thread
+
+
+The default typedef for the HTTP client that is provided uses the
+``http_default_8bit_udp_resolve`` tag, and implements HTTP 1.0. The exact
+typedef is in the ``boost::network::http`` namespace as the following:
+
+.. code-block:: c++
+
+    namespace boost { namespace network { namespace http {
+
+        typedef basic_client<tags::http_default_8bit_udp_resolve, 1, 0>
+            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:
+
+
+.. code-block:: c++
+
+    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:
 
-Each of these use again the tag-based static polymorphism that was
-described in previous sections.  A default, human-readable typedef is
-provided for each one of the ``basic_request``, ``basic_response`` and
-``basic_client``.  ``basic_request`` and ``basic_response`` each model
-the message concept. They make use of directives to set and get HTTP
-headers, body etc. The code snippet below shows how to set the HTTP
-header field "Connection" with the option "close" using the DSEL
-described in the directives section:
 
 .. code-block:: c++
 
     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:
 
+
 .. code-block:: c++
 
     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 also done using directives.
-To get the response headers, we use the ``headers`` directive which
-returns, in the default case, a map of strings to strings:
+
+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:
+
 
 .. code-block:: c++
 
@@ -60,18 +139,23 @@ returns, in the default case, a map of strings to strings:
     }    
     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:
 
+
 .. code-block:: c++
 
-    namespace http {
-    template <class Tag, class RequestHandler> basic_server;
-    }
+    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
@@ -95,18 +179,19 @@ implementation while the user-visible implementation is the
 
 .. code-block:: c++
 
-    namespace http {
-    template <
-        class RequestHandler
-    >
-    class server
-        : public basic_server<default_, RequestHandler> {};
-    }
+    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:
 
+
 .. code-block:: c++
 
     using namespace boost::network;
@@ -116,15 +201,20 @@ might look something like this:
     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).
+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.
 
 HTTP URI
 ````````