# 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

.. _contents:

Contents

--------

.. toctree::

:maxdepth: 4

index.rst

whats_new.rst

getting_started.rst

examples.rst

reference.rst

references.rst

.. _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

.. _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``.

.. _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.

.. _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.