Skip to content

Commit c3f9780

Browse files
glynosglynos
committed
It's still a hodge-podge of unrelated documentation stubs, but there is now enough structure to start writing and re-writing more content.
1 parent c34fd77 commit c3f9780

File tree

13 files changed

+516
-14
lines changed

13 files changed

+516
-14
lines changed

‎libs/network/doc/rst/directives.rst

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,88 @@
11
Directives
22
==========
33

4+
The library also uses a technique for allowing message-passing
5+
semantics in a chainable fashion in the form of directives. The basic
6+
concept for directives is, in a general sense, an encapsulated
7+
transformation that can be applied to objects that abide by the
8+
directive protocol.
9+
10+
Using the object-oriented notion of message passing, where an object
11+
accepts a message (usually a function call) we define a simple DSEL in
12+
order for the protocol to be supported by certain object types. In the
13+
:mod:`cpp-netlib` the protocol implemented is similar to that of the
14+
standard iostream formatting system:
15+
16+
.. code-block:: c++
17+
18+
object << directive1(...)
19+
<< directive2(...)
20+
...
21+
<< directiveN(...);
22+
23+
In :mod:`cpp-netlib` the directives are simple function objects that
24+
take a target object as reference and returns a reference to the same
25+
object as a result. In code the directive pattern looks like the
26+
following:
27+
28+
.. code-block:: c++
29+
30+
struct directive_type {
31+
template <class Input>
32+
Input & operator()(Input & input) const {
33+
// do something to input
34+
return input;
35+
}
36+
};
37+
38+
To simplify directive creation, usually factory or generator functions
39+
are defined to return concrete objects of the directive's type.
40+
41+
.. code-block:: c++
42+
43+
inline
44+
directive_type directive(...) {
45+
return directive_type();
46+
}
47+
48+
The trivial implementation of the directive protocol then boils down
49+
to the specialization of the shift-left operator on the target type.
50+
51+
.. code-block:: c++
52+
53+
template <class Directive>
54+
inline target_type & operator<<
55+
(target_type & x, Directive const & f) {
56+
return f(x);
57+
}
58+
59+
The rationale for implementing directives include the following:
60+
61+
* **Encapsulation** - by moving logic into the directive types the
62+
target object's interface can remain rudimentary and even hidden
63+
to the user's immediate attention. Adding this layer of
64+
indirection also allows for changing the underlying
65+
implementations while maintaining the same syntactic and semantic
66+
properties.
67+
* **Flexibility** - by allowing the creation of directives that are
68+
independent from the target object's type, generic operations can
69+
be applied based on the concept being modeled by the target
70+
type. The flexibility also afforded comes in the directive's
71+
generator function, which can also generate different concrete
72+
directive specializations based on parameters to the function.
73+
* **Extensibility** - because the directives are independent of the
74+
target object's type, new directives can be added and supported
75+
without having to change the target object at all.
76+
* **Reuse** - truly generic directives can then be used for a broad
77+
set of target object types that model the same concepts supported
78+
by the directive. Because the directives are self-contained
79+
objects, the state and other object references it keeps are only
80+
accessible to it and can be re-used in different contexts as well.
81+
82+
Extending a system that uses directives is trivial in header-only
83+
systems because new directives are simply additive. The protocol is
84+
simple and can be applied to a broad class of situations.
85+
86+
In a header-only library, the static nature of the wiring and chaining
87+
of the operations lends itself to compiler abuse. A deep enough
88+
nesting of the directives can lead to prolonged compilation times.

‎libs/network/doc/rst/history.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Project history
2+
===============
3+
4+
The :mod:`cpp-netlib` was founded by Dean Michael Berris in 2007.
5+
Initially it consisted of a message template and an HTTP client. It
6+
found a home on Sourceforge_ but was migrated at the end of 2009 to
7+
Github_ where development is actively continued by a committed
8+
community.
9+
10+
.. _Sourceforge: http://sourceforge.net/projects/cpp-netlib/
11+
.. _Github: http://github.com/cpp-netlib/cpp-netlib
12+
13+
.. toctree::
14+
:maxdepth: 2
15+
16+
motivation.rst
17+
objectives.rst

‎libs/network/doc/rst/http.rst

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
HTTP implementation
2+
===================
3+
4+
HTTP client
5+
```````````
6+
7+
The cpp-netlib HTTP client is composed of three template classes:
8+
9+
.. code-block:: c++
10+
11+
namespace http {
12+
template <class Tag> basic_request;
13+
template <class Tag> basic_response;
14+
template <class Tag> basic_client;
15+
typedef basic_request<default_> request;
16+
typedef basic_response<default_> response;
17+
typedef basic_client<default_> client;
18+
}
19+
20+
21+
Each of these use again the tag-based static polymorphism that was described in
22+
previous sections. A default, human-readable typedef is provided for each one
23+
of the ``basic_request``, ``basic_response`` and ``basic_client``.
24+
``basic_request`` and ``basic_response`` each model the message concept. They
25+
make use of directives to set and get HTTP headers, body etc. The code snippet
26+
below shows how to set the HTTP header field "Connection" with the option
27+
"close" using the DSEL described in the directives section:
28+
29+
.. code-block:: c++
30+
31+
using namespace boost::network;
32+
http::request request("http://www.boost.org/");
33+
request << header("Connection", "close");
34+
35+
The ``basic_client`` implements all HTTP methods as member functions (HEAD,
36+
GET, POST, PUT, DELETE). Therefore, the code to make an HTTP request looks
37+
trivially simple:
38+
39+
.. code-block:: c++
40+
41+
using namespace boost::network;
42+
http::client client;
43+
http::request request("http://www.boost.org/");
44+
http::response response = client.get(request);
45+
46+
Accessing data from ``http::response`` is also done using directives. To
47+
get the response headers, we use the ``headers`` directive which returns,
48+
in the default case, a map of strings to strings:
49+
50+
.. code-block:: c++
51+
52+
using namespace boost::network;
53+
typedef headers_range<http_client::response>::type response_headers;
54+
boost::range_iterator<response_headers>::type iterator;
55+
56+
response_headers headers_ = headers(response);
57+
for (iterator it = headers_.begin(); it != headers_.end(); ++it) {
58+
std::cout << it->first << ": " << it->second << std::endl;
59+
}
60+
std::cout << std::endl;
61+
62+
HTTP server
63+
```````````
64+
65+
As with the HTTP client, the HTTP server that is provided with cpp-netlib is
66+
extensible through the tag mechanism and is embeddable. The template class
67+
declaration of ``basic_server`` is given below:
68+
69+
.. code-block:: c++
70+
71+
namespace http {
72+
template <class Tag, class RequestHandler> basic_server;
73+
}
74+
75+
The second template argument is used to specify the request handler type. The
76+
request handler type is a functor type which should overload the function call
77+
operator (``RequestHandler::operator()`` should be overloaded) that takes two
78+
parameters: the first one being a reference to a ``const basic_request<Tag>``
79+
and the second being a reference to a ``basic_response<Tag>`` instance.
80+
81+
All the logic for parsing the HTTP request and building the ``const
82+
basic_request<Tag>`` object resides internally in the ``basic_server`` template.
83+
Processing the request is delegated to the ``RequestHandler`` type, and the
84+
assumption of which would be that the response is formed inside the
85+
``RequestHandler`` function call operator overload.
86+
87+
The ``basic_server`` template however is only an underlying implementation while
88+
the user-visible implementation is the ``http::server`` template. This simply
89+
specializes the ``basic_server`` template to use the ``default_`` tag and
90+
forwards the ``RequestHandler`` parameter:
91+
92+
.. code-block:: c++
93+
94+
namespace http {
95+
template <class RequestHandler> server
96+
: public basic_server<default_, RequestHandler>
97+
{};
98+
}
99+
100+
To use the forwarding server type you just supply the request handler
101+
implementation as the parameter. For example, an "echo" server example might
102+
look something like this:
103+
104+
.. code-block:: c++
105+
106+
using namespace boost::network;
107+
struct echo;
108+
typedef http::server<echo> echo_server;
109+
110+
struct echo {
111+
void operator () (const echo_server::request &request,
112+
echo_server::response &response) const {
113+
response = echo_server::response::stock_reply(
114+
echo_server::response::ok,
115+
body(request));
116+
}
117+
};
118+
119+
120+
Here, all we're doing is returning the original request body with an HTTP OK
121+
response (200).
122+
123+
HTTP URI
124+
````````
125+
126+
Firstly, cpp-netlib provides a specialization and ``typedef`` for an HTTP URI:
127+
128+
.. code-block:: c++
129+
130+
namespace http {
131+
template <class T> class basic_uri;
132+
typedef basic_uri<default_> uri;
133+
}
134+
135+
``basic_uri`` provides a parser which breaks down a URI string passed to it's
136+
constructor into different parts.
137+
138+
.. code-block:: c++
139+
140+
using namespace boost::network::uri;
141+
http::uri uri_("http://www.boost.org/");
142+
assert(valid(uri_));
143+
assert(scheme(uri_) == "http");
144+
assert(host(uri_) == "www.boost.org")
145+
assert(port(uri_) == 80)
146+
assert(path(uri_) == "/");
147+
148+
The syntax of the HTTP URI are defined in RFC 1738 section 3.3 [#]_ and the
149+
default URI provided with cpp-netlib conforms to this. In such a way,
150+
specializations that conform to any URI scheme can be provided.
151+
152+
.. [#] http://tools.ietf.org/html/rfc1738

‎libs/network/doc/rst/in_depth.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ An in-depth look at the :mod:`cpp-netlib`
66

77
message.rst
88
uri.rst
9-
protocol.rst
9+
http.rst

‎libs/network/doc/rst/index.rst

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,9 @@ Contents
2727
tutorials.rst
2828
in_depth.rst
2929
techniques.rst
30-
.. uri.rst
31-
.. install.rst
32-
.. motivation.rst
33-
.. objectives.rst
34-
.. history.rst
35-
.. pitfalls.rst
36-
.. portability.rst
37-
.. reference.rst
30+
history.rst
31+
install.rst
32+
references.rst
3833

3934
Indices and tables
4035
==================

‎libs/network/doc/rst/install.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Full installation guide
2+
=======================

‎libs/network/doc/rst/message.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -84,15 +84,15 @@ available in cpp-netlib. This default implementation is named ``basic_message``
8484
which supports a ``Tag`` template parameter. The definition of ``basic_message``
8585
looks like this:
8686

87-
::
87+
.. code-block:: c++
8888

8989
template <class Tag>
90-
struct basic_message;
90+
class basic_message;
9191

9292
The ``basic_message`` template requires that the following tag-dispatched
9393
metafunctions are defined for the type ``Tag``:
9494

95-
::
95+
.. code-block:: c++
9696

9797
template <class Tag>
9898
struct string;

‎libs/network/doc/rst/motivation.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Motivation
2+
==========
3+
4+
Modern applications that communicate over the internet have never been
5+
more prevalent, ranging through diverse areas such as high performance
6+
servers to embedded systems for smart phones and navigation systems.
7+
8+
Currently, there are no open source network libraries available that
9+
use modern object-oriented techniques in C++. Any developer will
10+
understand the familiar problem of searching for a protocol library
11+
for their project, failing to find anything suitable and too often
12+
having to hand-roll their own.
13+
14+
By leveraging Boost_, and in particular `Boost.Asio`_, developers can
15+
create portable network C++ applications much more easily. What is
16+
still lacking is a set of libraries that utilise `Boost.Asio`_ in
17+
order to provide application level support so that C++ developers are
18+
able to develop internet and distributed applications more
19+
effectively. This is the niche that the developers of the
20+
:mod:`cpp-netlib` see their project filling.
21+
22+
.. _Boost: http://www.boost.org/
23+
.. _`Boost.Asio`: http://www.boost.org/libs/asio/

‎libs/network/doc/rst/objectives.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Objectives
2+
==========
3+
4+
5+
The objectives of the :mod:`cpp-netlib` are to:
6+
7+
* develop a high quality, portable, easy to use C++ networking library
8+
* enable developers to easily extend the library
9+
* lower the barrier to entry for cross-platform network-aware C++
10+
applications
11+
12+
The goal the of :mod:`cpp-netlib` has never been to build a
13+
fully-featured web server - there are plenty of excellent options
14+
already available. The niche that this library targets is for
15+
light-weight networking functionality for C++ applications that have
16+
demanding performance requirements or memory constraints, but that
17+
also need to be portable. This type of application is becoming
18+
increasingly common as software becomes more distributed, and
19+
applications need to communicate with services.
20+
21+
While many languages provide direct library support for high level
22+
network programming, this feature is missing in C++. Therefore, this
23+
library has been developed with the intention of eventually being
24+
submitted to Boost_, a collection of general, high quality
25+
libraries for C++ developers.
26+
27+
.. _Boost: http://www.boost.org/
28+
29+
Eventually, the :mod:`cpp-netlib` will be extended to support many of
30+
the application layer protocols such as SMTP, FTP, SOAP, XMPP etc.

0 commit comments

Comments
 (0)