Add 0.12.0 docs

Author: deanberris

0.12.0/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: adbe6ea7ac2e69d5b593dfb1e312603d
+tags: 645f666f9bcd5a90fca523b33c5a78b7

0.12.0/_sources/contents.txt

@@ -0,0 +1,14 @@
+.. _contents:
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 4
+
+   index.rst
+   whats_new.rst
+   getting_started.rst
+   examples.rst
+   reference.rst
+   references.rst

0.12.0/_sources/examples.txt

@@ -0,0 +1,27 @@
+.. _examples:
+
+Examples
+========
+
+The :mod:`cpp-netlib` is a practical library that is designed to aid
+the development of applications for that need to communicate using
+common networking protocols.  The following set of examples describe a
+series of realistic examples that use the :mod:`cpp-netlib` for these
+kinds of application.  All examples are built using CMake.
+
+HTTP examples
+`````````````
+
+The HTTP component of the :mod:`cpp-netlib` contains a client and server.
+The examples that follow show how to use both for programs that can be
+embedded into larger applications.
+
+.. toctree::
+   :maxdepth: 1
+
+   examples/http/http_client
+   examples/http/simple_wget
+   examples/http/hello_world_server
+   examples/http/hello_world_client
+   examples/http/atom_reader
+   examples/http/twitter_search

0.12.0/_sources/examples/http/atom_reader.txt

@@ -0,0 +1,78 @@
+.. _atom_reader:
+
+******************
+ Atom feed reader
+******************
+
+The next examples show some simple, more practical applications using
+the HTTP client.  The first one reads a simple Atom_ feed and prints
+the titles of each entry to the console.
+
+.. _Atom: http://en.wikipedia.org/wiki/Atom_(standard)
+
+The code
+========
+
+.. code-block:: c++
+
+   #include "atom.hpp"
+   #include <boost/network/protocol/http/client.hpp>
+   #include <boost/foreach.hpp>
+   #include <iostream>
+
+   int main(int argc, char * argv[]) {
+       using namespace boost::network;
+
+       if (argc != 2) {
+           std::cout << "Usage: " << argv[0] << " <url>" << std::endl;
+           return 1;
+       }
+
+       try {
+           http::client client;
+           http::client::request request(argv[1]);
+           request << header("Connection", "close");
+           http::client::response response = client.get(request);
+           atom::feed feed(response);
+
+           std::cout << "Feed: " << feed.title()
+	   	     << " (" << feed.subtitle() << ")" << std::endl;
+           BOOST_FOREACH(const atom::entry &entry, feed) {
+               std::cout << entry.title()
+	       		 << " (" << entry.published() << ")" << std::endl;
+           }
+       }
+       catch (std::exception &e) {
+           std::cerr << e.what() << std::endl;
+       }
+
+       return 0;
+   }
+
+Building and running ``atom_reader``
+====================================
+
+.. code-block:: bash
+
+    $ cd ~/cpp-netlib-build
+    $ make atom_reader
+
+And to run the example from the command line to access the feed that
+lists of all the commits on cpp-netlib's master branch:
+
+.. code-block:: bash
+
+    $ ./example/atom_reader https://github.com/cpp-netlib/cpp-netlib/commits/master.atom
+
+Diving into the code
+====================
+
+Most of this will now be familiar.  The response is passed to the
+constructor to the ``atom::feed`` class, which parses the resultant
+XML.  To keep this example as simple as possible, `rapidxml`_, a
+header-only XML parser library, was used to parse the response.
+
+.. _`rapidxml`: http://rapidxml.sourceforge.net/
+
+A similar example using RSS feeds exists in
+``libs/network/example/rss``.

0.12.0/_sources/examples/http/hello_world_client.txt

@@ -0,0 +1,94 @@
+.. _hello_world_http_client:
+
+***************************
+ "Hello world" HTTP client
+***************************
+
+Since we have a "Hello World" HTTP server, let's then create an HTTP client to
+access that server. This client will be similar to the HTTP client we made
+earlier in the documentation.
+
+The code
+========
+
+We want to create a simple HTTP client that just makes a request to the HTTP
+server that we created earlier. This really simple client will look like this:
+
+.. code-block:: c++
+
+    #include <boost/network/protocol/http/client.hpp>
+    #include <string>
+    #include <sstream>
+    #include <iostream>
+
+    namespace http = boost::network::http;
+
+    int main(int argc, char * argv[]) {
+        if (argc != 3) {
+            std::cerr << "Usage: " << argv[0] << " address port" << std::endl;
+            return 1;
+        }
+
+        try {
+            http::client client;
+            std::ostringstream url;
+            url << "http://" << argv[1] << ":" << argv[2] << "/";
+            http::client::request request(url.str());
+            http::client::response response =
+                client.get(request);
+            std::cout << body(response) << std::endl;
+        } catch (std::exception & e) {
+            std::cerr << e.what() << std::endl;
+            return 1;
+        }
+        return 0;
+    }
+
+Building and running the client
+===============================
+
+Just like with the HTTP Server and HTTP client example before, we can build this
+example by doing the following on the shell:
+
+.. code-block:: bash
+
+    $ cd ~/cpp-netlib-build
+    $ make hello_world_client
+
+This example can be run from the command line as follows:
+
+.. code-block:: bash
+
+    $ ./example/hello_world_client http://127.0.0.1:8000
+
+.. note:: This assumes that you have the ``hello_world_server`` running on
+   localhost port 8000.
+
+Diving into the code
+====================
+
+All this example shows is how easy it is to write an HTTP client that connects
+to an HTTP server, and gets the body of the response. The relevant lines are:
+
+.. code-block:: c++
+
+    http::client client;
+    http::client::request request(url.str());
+    http::client::response response =
+        client.get(request);
+    std::cout << body(response) << std::endl;
+
+You can then imagine using this in an XML-RPC client, where you can craft the
+XML-RPC request as payload which you can pass as the body to a request, then
+perform the request via HTTP:
+
+.. code-block:: c++
+
+    http::client client;
+    http::client::request request("http://my.webservice.com/");
+    http::client::response =
+        client.post(request, some_xml_string, "application/xml");
+    std::data = body(response);
+
+The next set of examples show some more practical applications using
+the :mod:`cpp-netlib` HTTP client.

0.12.0/_sources/examples/http/hello_world_server.txt

@@ -0,0 +1,147 @@
+.. _hello_world_http_server:
+
+***************************
+ "Hello world" HTTP server
+***************************
+
+Now that we've seen how we can deal with request and response objects from the
+client side, we'll see how we can then use the same abstractions on the server
+side. In this example we're going to create a simple HTTP Server in C++ using
+:mod:`cpp-netlib`.
+
+The code
+========
+
+The :mod:`cpp-netlib` provides the framework to develop embedded HTTP
+servers.  For this example, the server is configured to return a
+simple response to any HTTP request.
+
+.. code-block:: c++
+
+    #include <boost/network/protocol/http/server.hpp>
+    #include <iostream>
+
+    namespace http = boost::network::http;
+
+    struct hello_world;
+    typedef http::server<hello_world> server;
+
+    struct hello_world {
+        void operator()(server::request const &request, server::response &response) {
+            server::string_type ip = source(request);
+            unsigned int port = request.source_port;
+            std::ostringstream data;
+            data << "Hello, " << ip << ':' << port << '!';
+            response = server::response::stock_reply(server::response::ok, data.str());
+        }
+        void log(const server::string_type& message) {
+            std::cerr << "ERROR: " << message << std::endl;
+        }
+    };
+
+    int main(int argc, char *argv[]) {
+
+        if (argc != 3) {
+            std::cerr << "Usage: " << argv[0] << " address port" << std::endl;
+            return 1;
+        }
+
+        try {
+            hello_world handler;
+            server::options options(handler);
+            server server_(options.address(argv[1]).port(argv[2]));
+            server_.run();
+        }
+        catch (std::exception &e) {
+            std::cerr << e.what() << std::endl;
+            return 1;
+        }
+
+        return 0;
+    }
+
+This is about a straightforward as server programming will get in C++.
+
+Building and running the server
+===============================
+
+Just like with the HTTP client, we can build this example by doing the following
+on the shell:
+
+.. code-block:: bash
+
+    $ cd ~/cpp-netlib-build
+    $ make hello_world_server
+
+The first two arguments to the ``server`` constructor are the host and
+the port on which the server will listen.  The third argument is the
+the handler object defined previously.  This example can be run from
+a command line as follows:
+
+.. code-block:: bash
+
+    $ ./example/hello_world_server 0.0.0.0 8000
+
+.. note:: If you're going to run the server on port 80, you may have to run it
+   as an administrator.
+
+Diving into the code
+====================
+
+Let's take a look at the code listing above in greater detail.
+
+.. code-block:: c++
+
+    #include <boost/network/protocol/http/server.hpp>
+
+This header contains all the code needed to develop an HTTP server with
+:mod:`cpp-netlib`.
+
+.. code-block:: c++
+
+    struct hello_world;
+    typedef http::server<hello_world> server;
+
+    struct hello_world {
+        void operator()(server::request const &request, server::response &response) {
+            server::string_type ip = source(request);
+            unsigned int port = request.source_port;
+            std::ostringstream data;
+            data << "Hello, " << ip << ':' << port << '!';
+            response = server::response::stock_reply(server::response::ok, data.str());
+        }
+        void log(const server::string_type& message) {
+            std::cerr << "ERROR: " << message << std::endl;
+        }
+    };
+
+``hello_world`` is a functor class which handles HTTP requests.
+All the operator does here is return an HTTP response with HTTP code 200
+and the body ``"Hello, <ip>:<port>!"``. The ``<ip>`` in this case would be
+the IP address of the client that made the request and ``<port>`` the clients port.
+
+There are a number of pre-defined stock replies differentiated by
+status code with configurable bodies.
+All the supported enumeration values for the response status codes can be found
+in ``boost/network/protocol/http/impl/response.ipp``.
+
+.. code-block:: c++
+
+    hello_world handler;
+    server::options options(handler);
+    server server_(options.address(argv[1]).port(argv[2]));
+    server_.run();
+
+The ``server`` constructor requires an object of the ``options`` class,
+this object stores all needed options, especially the host and
+the port on which the server will listen.
+The ``options`` constructor's single argument is the handler object defined previously.
+
+.. note:: In this example, the server is specifically made to be single-threaded.
+   In a multi-threaded server, you would invoke the ``hello_world::run`` member
+   method in a set of threads. In a multi-threaded environment you would also
+   make sure that the handler does all the necessary synchronization for shared
+   resources across threads. The handler is passed by reference to the server
+   constructor and you should ensure that any calls to the ``operator()`` overload
+   are thread-safe.
+