SPHINXOPTS =

SPHINXBUILD = sphinx-build

PAPER =

BUILDDIR = _build

PAPEROPT_a4 = -D latex_paper_size=a4

PAPEROPT_letter = -D latex_paper_size=letter

ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest

help:

@echo "Please use \`make <target>' where <target> is one of"

@echo " html to make standalone HTML files"

@echo " dirhtml to make HTML files named index.html in directories"

@echo " pickle to make pickle files"

@echo " json to make JSON files"

@echo " htmlhelp to make HTML files and a HTML help project"

@echo " qthelp to make HTML files and a qthelp project"

@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"

@echo " changes to make an overview of all changed/added/deprecated items"

@echo " linkcheck to check all external links for integrity"

@echo " doctest to run all doctests embedded in the documentation (if enabled)"

clean:

-rm -rf $(BUILDDIR)/*

html:

$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

@echo

@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

dirhtml:

$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

@echo

@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

pickle:

$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle

@echo

@echo "Build finished; now you can process the pickle files."

json:

$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json

@echo

@echo "Build finished; now you can process the JSON files."

htmlhelp:

$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp

@echo

@echo "Build finished; now you can run HTML Help Workshop with the" \

".hhp project file in $(BUILDDIR)/htmlhelp."

qthelp:

$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp

@echo

@echo "Build finished; now you can run "qcollectiongenerator" with the" \

".qhcp project file in $(BUILDDIR)/qthelp, like this:"

@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cpp-netlib.qhcp"

@echo "To view the help file:"

@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cpp-netlib.qhc"

latex:

$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

@echo

@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."

@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \

"run these through (pdf)latex."

changes:

$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes

@echo

@echo "The overview file is in $(BUILDDIR)/changes."

linkcheck:

$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck

@echo

@echo "Link check complete; look for any errors in the above output " \

"or in $(BUILDDIR)/linkcheck/output.txt."

doctest:

$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest

@echo "Testing of doctests in the sources finished, look at the " \

"results in $(BUILDDIR)/doctest/output.txt."

exclude_trees = ['_build']

The library also uses a technique for allowing message-passing

semantics in a chainable fashion in the form of directives. The basic

concept for directives is, in a general sense, an encapsulated

transformation that can be applied to objects that abide by the

directive protocol.

Using the object-oriented notion of message passing, where an object

accepts a message (usually a function call) we define a simple DSEL in

order for the protocol to be supported by certain object types. In the

:mod:`cpp-netlib` the protocol implemented is similar to that of the

standard iostream formatting system:

.. code-block:: c++

object << directive1(...)

<< directive2(...)

...

<< directiveN(...);

In :mod:`cpp-netlib` the directives are simple function objects that

take a target object as reference and returns a reference to the same

object as a result. In code the directive pattern looks like the

following:

.. code-block:: c++

struct directive_type {

template <class Input>

Input & operator()(Input & input) const {

// do something to input

return input;

}

};

To simplify directive creation, usually factory or generator functions

are defined to return concrete objects of the directive's type.

.. code-block:: c++

inline

directive_type directive(...) {

return directive_type();

}

The trivial implementation of the directive protocol then boils down

to the specialization of the shift-left operator on the target type.

.. code-block:: c++

template <class Directive>

inline target_type & operator<<

(target_type & x, Directive const & f) {

return f(x);

}

The rationale for implementing directives include the following:

* **Encapsulation** - by moving logic into the directive types the

target object's interface can remain rudimentary and even hidden

to the user's immediate attention. Adding this layer of

indirection also allows for changing the underlying

implementations while maintaining the same syntactic and semantic

properties.

* **Flexibility** - by allowing the creation of directives that are

independent from the target object's type, generic operations can

be applied based on the concept being modeled by the target

type. The flexibility also afforded comes in the directive's

generator function, which can also generate different concrete

directive specializations based on parameters to the function.

* **Extensibility** - because the directives are independent of the

target object's type, new directives can be added and supported

without having to change the target object at all.

* **Reuse** - truly generic directives can then be used for a broad

set of target object types that model the same concepts supported

by the directive. Because the directives are self-contained

objects, the state and other object references it keeps are only

accessible to it and can be re-used in different contexts as well.

Extending a system that uses directives is trivial in header-only

systems because new directives are simply additive. The protocol is

simple and can be applied to a broad class of situations.

In a header-only library, the static nature of the wiring and chaining

of the operations lends itself to compiler abuse. A deep enough

nesting of the directives can lead to prolonged compilation times.

Project history

The :mod:`cpp-netlib` was founded by Dean Michael Berris in 2007.

Initially it consisted of a message template and an HTTP client. It

found a home on Sourceforge_ but was migrated at the end of 2009 to

Github_ where development is actively continued by a committed

community.

.. _Sourceforge: http://sourceforge.net/projects/cpp-netlib/

.. _Github: http://github.com/cpp-netlib/cpp-netlib

.. toctree::

:maxdepth: 2

motivation.rst

objectives.rst

HTTP implementation

HTTP client

The cpp-netlib HTTP client is composed of three template classes:

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

}

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::request request("http://www.boost.org/");

http::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:

.. code-block:: c++

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:

.. code-block:: c++

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:

.. code-block:: c++

namespace http {

template <class RequestHandler> 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;

struct echo;

typedef http::server<echo> echo_server;

struct echo {

void operator () (const echo_server::request &request,

echo_server::response &response) const {

response = echo_server::response::stock_reply(

echo_server::response::ok,

body(request));

}

};

Here, all we're doing is returning the original request body with an HTTP OK

response (200).

HTTP URI

Firstly, cpp-netlib provides a specialization and ``typedef`` for an HTTP URI:

.. code-block:: c++

namespace http {

template <class T> class basic_uri;

typedef basic_uri<default_> uri;

}

``basic_uri`` provides a parser which breaks down a URI string passed to it's

constructor into different parts.

.. code-block:: c++

using namespace boost::network::uri;

http::uri uri_("http://www.boost.org/");

assert(valid(uri_));

assert(scheme(uri_) == "http");

assert(host(uri_) == "www.boost.org")

assert(port(uri_) == 80)

assert(path(uri_) == "/");

The syntax of the HTTP URI are defined in RFC 1738 section 3.3 [#]_ and the

default URI provided with cpp-netlib conforms to this. In such a way,

specializations that conform to any URI scheme can be provided.

.. [#] http://tools.ietf.org/html/rfc1738

http.rst

history.rst

install.rst

references.rst

Full installation guide