Skip to content

Commit 9ff82be

Browse files
deanberrisdeanberris
committed
Updating bundled documentation for 0.8.
1 parent 653c055 commit 9ff82be

17 files changed

+1559
-27
lines changed

‎libs/network/doc/html/_sources/message.txt

+2-2
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ data, depending on the type used to tag the message. This section
2828
covers the `Message Concept`_ as well as the `basic_message`_
2929
implementation.
3030

31-
``Message Concept``
32-
```````````````````
31+
Message Concept
32+
```````````````
3333

3434
The Message Concept specifies what the valid operations on a message
3535
are as well as what messages look like semantically. The following

‎libs/network/doc/html/_sources/reference.txt

+2
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,7 @@ to the different client and/or server implementations within :mod:`cpp-netlib`.
99
:maxdepth: 2
1010

1111
reference_http_client.rst
12+
reference_http_request.rst
13+
reference_http_response.rst
1214
reference_http_server.rst
1315

‎libs/network/doc/html/_sources/reference_http_request.txt

+252
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
2+
HTTP Request
3+
============
4+
5+
This part of the documentation talks about the publicly accessible API of the
6+
HTTP Request objects. This section details the `Request Concepts`_ requirements,
7+
the implemented and required Directives_, Modifiers_, and Wrappers_ that work
8+
with the HTTP Request objects.
9+
10+
Request Concepts
11+
----------------
12+
13+
There are two generally supported Request Concepts implemented in the library.
14+
The first of two is the `Normal Client Request Concept`_ and the second is the
15+
`Pod Server Request Concept`_.
16+
17+
The `Normal Client Request Concept`_ is what the HTTP Client interface requires.
18+
All operations performed internally by the HTTP Client abide by the interface
19+
required by this concept definition.
20+
21+
The `Pod Server Request Concept`_ is as the name suggests what the HTTP Server
22+
implementation requires from Request Objects.
23+
24+
Switching on whether the `Request` concept chooses either of the `Normal Client
25+
Request Concept`_ or the `Pod Server Request Concept`_ is done through the
26+
nested ``tag`` type and whether that tag derives from the root tag ``pod``.
27+
Simply, if the Request type's nested ``tag`` type derives from
28+
``boost::network::tags::pod`` then it chooses to enforce the `Pod Server Request
29+
Concept`_, otherwise it chooses the `Normal Client Request Concept`_.
30+
31+
Normal Client Request Concept
32+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33+
34+
A type models the Normal Client Request Concept if it models the `Message
35+
Concept`_ and also supports the following constructs.
36+
37+
**Legend**
38+
39+
:R: The request type.
40+
:r: An instance of R.
41+
:S: The string type.
42+
:s: An instance of S.
43+
:P: The port type.
44+
:p: An instance of P.
45+
46+
+-----------------------+-------------+----------------------------------------+
47+
| Construct | Result | Description |
48+
+=======================+=============+========================================+
49+
| ``R::string_type`` | ``S`` | The nested ``string_type`` type. |
50+
+-----------------------+-------------+----------------------------------------+
51+
| ``R::port_type`` | ``P`` | The nested ``port_type`` type. |
52+
+-----------------------+-------------+----------------------------------------+
53+
| ``R r(s)`` | **NA** | Construct a Request with an ``s`` |
54+
| | | provided. This treats ``s`` as the URI |
55+
| | | to where the request is destined for. |
56+
+-----------------------+-------------+----------------------------------------+
57+
| ``host(request)`` | Convertible | Return the host to where the request |
58+
| | to ``S`` | is destined for. |
59+
+-----------------------+-------------+----------------------------------------+
60+
| ``port(request)`` | Convertible | Return the port to where the request |
61+
| | to ``P`` | is destined for. |
62+
+-----------------------+-------------+----------------------------------------+
63+
| ``path(request)`` | Convertible | Return the path included in the URI. |
64+
| | to ``S`` | |
65+
+-----------------------+-------------+----------------------------------------+
66+
| ``query(request)`` | Convertible | Return the query part of the URI. |
67+
| | to ``S`` | |
68+
+-----------------------+-------------+----------------------------------------+
69+
| ``anchor(request)`` | Convertible | Return the anchor part of the URI. |
70+
| | to ``S`` | |
71+
+-----------------------+-------------+----------------------------------------+
72+
| ``protocol(request)`` | Convertible | Return the protocol/scheme part of the |
73+
| | to ``S`` | URI. |
74+
+-----------------------+-------------+----------------------------------------+
75+
| ``r << uri(s)`` | ``R&`` | Set the URI of the request. |
76+
+-----------------------+-------------+----------------------------------------+
77+
| ``uri(r, s)`` | ``void`` | Set the URI of the request. |
78+
+-----------------------+-------------+----------------------------------------+
79+
80+
Pod Server Request Concept
81+
~~~~~~~~~~~~~~~~~~~~~~~~~~
82+
83+
A type models the Pod Server Request Concept if it models the `Message Concept`_
84+
and also supports the following constructs.
85+
86+
**Legend**
87+
88+
:R: The request type.
89+
:r: An instance of R.
90+
:S: The string type.
91+
:I: An unsigned 8 bit integer.
92+
:V: The vector type for headers.
93+
94+
+-------------------------------+--------+-------------------------------------+
95+
| Construct | Result | Description |
96+
+===============================+========+=====================================+
97+
| ``R::string_type`` | ``S`` | The nested ``string_type`` type. |
98+
+-------------------------------+--------+-------------------------------------+
99+
| ``R::headers_container_type`` | ``V`` | The nested |
100+
| | | ``headers_container_type`` type. |
101+
+-------------------------------+--------+-------------------------------------+
102+
| ``r.source`` | ``S`` | The nested source of the request. |
103+
+-------------------------------+--------+-------------------------------------+
104+
| ``r.method`` | ``S`` | The method of the request. |
105+
+-------------------------------+--------+-------------------------------------+
106+
| ``r.destination`` | ``S`` | The destination of the request. |
107+
| | | This is normally the URI of the |
108+
| | | request. |
109+
+-------------------------------+--------+-------------------------------------+
110+
| ``r.version_major`` | ``I`` | The major version number part of |
111+
| | | the request. |
112+
+-------------------------------+--------+-------------------------------------+
113+
| ``r.version_minor`` | ``I`` | The minor version number part of |
114+
| | | the request. |
115+
+-------------------------------+--------+-------------------------------------+
116+
| ``r.headers`` | ``V`` | The vector of headers. |
117+
+-------------------------------+--------+-------------------------------------+
118+
| ``r.body`` | ``S`` | The body of the request. |
119+
+-------------------------------+--------+-------------------------------------+
120+
121+
.. _Message Concept: message.html#message-concept
122+
123+
Directives
124+
----------
125+
126+
This section details the provided directives that are provided by
127+
:mod:`cpp-netlib`. The section was written to assume that an appropriately
128+
constructed request instance is either of the following:
129+
130+
.. code-block:: c++
131+
132+
boost::network::http::basic_request<
133+
boost::network::http::tags::http_default_8bit_udp_resolve
134+
> request;
135+
136+
// or
137+
138+
boost::network::http::basic_request<
139+
boost::network::http::tags::http_server
140+
> request;
141+
142+
The section also assumes that there following using namespace declaration is in
143+
effect:
144+
145+
.. code-block:: c++
146+
147+
using namespace boost::network;
148+
149+
Directives are meant to be used in the following manner:
150+
151+
.. code-block:: c++
152+
153+
request << directive(...);
154+
155+
.. warning:: There are two versions of directives, those that are applicable to
156+
messages that support narrow strings (``std::string``) and those that are
157+
applicable to messages that support wide strings (``std::wstring``). The
158+
:mod:`cpp-netlib` implementation still does not convert wide strings into
159+
UTF-8 encoded narrow strings. This will be implemented in subsequent
160+
library releases.
161+
162+
For now all the implemented directives are listed, even if some of them still
163+
do not implement things correctly.
164+
165+
*unspecified* ``source(std::string const & source_)``
166+
Create a source directive with a ``std::string`` as a parameter, to be set
167+
as the source of the request.
168+
*unspecified* ``source(std::wstring const & source_)``
169+
Create a source directive with a ``std::wstring`` as a parameter, to be set
170+
as the source of the request.
171+
*unspecified* ``destination(std::string const & source_)``
172+
Create a destination directive with a ``std::string`` as a parameter, to be
173+
set as the destination of the request.
174+
*unspecified* ``destination(std::wstring const & source_)``
175+
Create a destination directive with a ``std::wstring`` as a parameter, to be
176+
set as the destination of the request.
177+
*unspecified* ``header(std::string const & name, std::string const & value)``
178+
Create a header directive that will add the given name and value pair to the
179+
headers already associated with the request. In this case the name and
180+
values are both ``std::string``.
181+
*unspecified* ``header(std::wstring const & name, std::wstring const & value)``
182+
Create a header directive that will add the given name and value pair to the
183+
headers already associated with the request. In this case the name and
184+
values are both ``std::wstring``.
185+
*unspecified* ``remove_header(std::string const & name)``
186+
Create a remove_header directive that will remove all the occurences of the
187+
given name from the headers already associated with the request. In this
188+
case the name of the header is of type ``std::string``.
189+
*unspecified* ``remove_header(std::wstring const & name)``
190+
Create a remove_header directive that will remove all the occurences of the
191+
given name from the headers already associated with the request. In this
192+
case the name of the header is of type ``std::wstring``.
193+
*unspecified* ``body(std::string const & body_)``
194+
Create a body directive that will set the request's body to the given
195+
parameter. In this case the type of the body is an ``std::string``.
196+
*unspecified* ``body(std::wstring const & body_)``
197+
Create a body directive that will set the request's body to the given
198+
parameter. In this case the type of the body is an ``std::wstring``.
199+
200+
Modifiers
201+
---------
202+
203+
This section details the provided modifiers that are provided by
204+
:mod:`cpp-netlib`.
205+
206+
``template <class Tag> inline void source(basic_request<Tag> & request, typename string<Tag>::type const & source_)``
207+
Modifies the source of the given ``request``. The type of ``source_`` is
208+
dependent on the ``Tag`` specialization of ``basic_request``.
209+
``template <class Tag> inline void destination(basic_request<Tag> & request, typename string<Tag>::type const & destination_)``
210+
Modifies the destination of the given ``request``. The type of ``destination_`` is
211+
dependent on the ``Tag`` specialization of ``basic_request``.
212+
``template <class Tag> inline void add_header(basic_request<Tag> & request, typename string<Tag>::type const & name, typename string<Tag>::type const & value)``
213+
Adds a header to the given ``request``. The type of the ``name`` and
214+
``value`` parameters are dependent on the ``Tag`` specialization of
215+
``basic_request``.
216+
``template <class Tag> inline void remove_header(basic_request<Tag> & request, typename string<Tag>::type const & name)``
217+
Removes a header from the given ``request``. The type of the ``name``
218+
parameter is dependent on the ``Tag`` specialization of ``basic_request``.
219+
``template <class Tag> inline void clear_headers(basic_request<Tag> & request)``
220+
Removes all headers from the given ``request``.
221+
``template <class Tag> inline void body(basic_request<Tag> & request, typename string<Tag>::type const & body_)``
222+
Modifies the body of the given ``request``. The type of ``body_`` is
223+
dependent on the ``Tag`` specialization of ``basic_request``.
224+
225+
Wrappers
226+
--------
227+
228+
This section details the provided request wrappers that come with
229+
:mod:`cpp-netlib`. Wrappers are used to convert a message into a different type,
230+
usually providing accessor operations to retrieve just part of the message. This
231+
section assumes that the following using namespace directives are in
232+
effect:
233+
234+
.. code-block:: c++
235+
236+
using namespace boost::network;
237+
using namespace boost::network::http;
238+
239+
``template <class Tag>`` *unspecified* ``source(basic_request<Tag> const & request)``
240+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
241+
provides the source of a given request.
242+
``template <class Tag>`` *unspecified* ``destination(basic_request<Tag> const & request)``
243+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
244+
provides the destination of a given request.
245+
``template <class Tag>`` *unspecified* ``headers(basic_request<Tag> const & request)``
246+
Returns a wrapper convertible to ``typename headers_range<basic_request<Tag>
247+
>::type`` or ``typename basic_request<Tag>::headers_container_type`` that
248+
provides the headers of a given request.
249+
``template <class Tag>`` *unspecified* ``body(basic_request<Tag> const & request)``
250+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
251+
provides the body of a given request.
252+

0 commit comments

Comments
 (0)