Skip to content

Commit 653c055

Browse files
committed
Finishing the HTTP Response reference manual API.
1 parent 186899f commit 653c055

File tree

1 file changed

+304
-0
lines changed

1 file changed

+304
-0
lines changed
Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
2+
HTTP Response
3+
=============
4+
5+
This part of the documentation talks about the publicly accessible API of the
6+
HTTP Response objects. This section details the `Response Concept`_ requirements,
7+
the implemented and required Directives_, Modifiers_, and Wrappers_ that work
8+
with the HTTP Response objects.
9+
10+
Response Concept
11+
----------------
12+
13+
A type models the Response Concept if it models the `Message Concept`_ and also
14+
supports the following constructs.
15+
16+
**Legend**
17+
18+
:R: The response type.
19+
:r: An instance of R.
20+
:S: The string type.
21+
:s,e,g: Instances of S.
22+
:P: The port type.
23+
:p: An instance of P.
24+
:V: The version type.
25+
:v: An instance of v.
26+
:T: The status type.
27+
:t: An instance of T.
28+
:M: The status message type.
29+
:m: An instance of M.
30+
:U: An unsigned 16-bit int.
31+
:u: An instance of U.
32+
33+
.. note:: In the table below, the namespace ``traits`` is an alias for
34+
``boost::network::http::traits``.
35+
36+
+-------------------------------------+----------+-----------------------------+
37+
| Construct | Result | Description |
38+
+=====================================+==========+=============================+
39+
| ``R::string_type`` | ``S`` | The nested ``string_type`` |
40+
| | | type. |
41+
+-------------------------------------+----------+-----------------------------+
42+
| ``traits::version<R>::type`` | ``V`` | The version type associated |
43+
| | | with R. |
44+
+-------------------------------------+----------+-----------------------------+
45+
| ``traits::status<R>::type`` | ``T`` | The status type associated |
46+
| | | with R. |
47+
+-------------------------------------+----------+-----------------------------+
48+
| ``traits::status_message<R>::type`` | ``M`` | The status message type |
49+
| | | associated with R. |
50+
+-------------------------------------+----------+-----------------------------+
51+
| ``r << version(v)`` | ``R&`` | Sets the version of ``r``. |
52+
+-------------------------------------+----------+-----------------------------+
53+
| ``r << status(t)`` | ``R&`` | Sets the status of ``r``. |
54+
+-------------------------------------+----------+-----------------------------+
55+
| ``r << status_message(m)`` | ``R&`` | Sets the status message of |
56+
| | | ``r``. |
57+
+-------------------------------------+----------+-----------------------------+
58+
| ``version(r, v)`` | ``void`` | Sets the version of ``r``. |
59+
+-------------------------------------+----------+-----------------------------+
60+
| ``status(r, t)`` | ``void`` | Sets the status of ``r``. |
61+
+-------------------------------------+----------+-----------------------------+
62+
| ``status_message(r, m)`` | ``void`` | Sets the status message of |
63+
| | | ``r``. |
64+
+-------------------------------------+----------+-----------------------------+
65+
| ``S e = version(r)`` | **NA** | Get the version of ``r``. |
66+
+-------------------------------------+----------+-----------------------------+
67+
| ``U u = status(r)`` | **NA** | Get the status of ``r``. |
68+
+-------------------------------------+----------+-----------------------------+
69+
| ``S g = status_message(r)`` | **NA** | Get the status message of |
70+
| | | ``r``. |
71+
+-------------------------------------+----------+-----------------------------+
72+
73+
.. _Message Concept: message.html#message-concept
74+
75+
Directives
76+
----------
77+
78+
This section details the provided directives that are provided by
79+
:mod:`cpp-netlib`. The section was written to assume that an appropriately
80+
constructed response instance is either of the following:
81+
82+
.. code-block:: c++
83+
84+
boost::network::http::basic_response<
85+
boost::network::http::tags::http_default_8bit_udp_resolve
86+
> response;
87+
88+
// or
89+
90+
boost::network::http::basic_response<
91+
boost::network::http::tags::http_server
92+
> response;
93+
94+
The section also assumes that there following using namespace declaration is in
95+
effect:
96+
97+
.. code-block:: c++
98+
99+
using namespace boost::network;
100+
101+
Directives are meant to be used in the following manner:
102+
103+
.. code-block:: c++
104+
105+
response << directive(...);
106+
107+
.. warning:: There are four versions of directives, those that are applicable
108+
to messages that support narrow strings (``std::string``), those that are
109+
applicable to messages that support wide strings (``std::wstring``), those
110+
that are applicable to messages that support future-wrapped narrow and wide
111+
strings (``boost::shared_future<std::string>`` and
112+
``boost::shared_future<std::wstring>``).
113+
114+
The :mod:`cpp-netlib` implementation still does not convert wide strings into
115+
UTF-8 encoded narrow strings. This will be implemented in subsequent
116+
library releases.
117+
118+
For now all the implemented directives are listed, even if some of them still
119+
do not implement things correctly.
120+
121+
*unspecified* ``source(std::string const & source_)``
122+
Create a source directive with a ``std::string`` as a parameter, to be set
123+
as the source of the response.
124+
*unspecified* ``source(std::wstring const & source_)``
125+
Create a source directive with a ``std::wstring`` as a parameter, to be set
126+
as the source of the response.
127+
*unspecified* ``source(boost::shared_future<std::string> const & source_)``
128+
Create a source directive with a ``boost::shared_future<std::string>`` as a parameter, to be set
129+
as the source of the response.
130+
*unspecified* ``source(boost::shared_future<std::wstring> const & source_)``
131+
Create a source directive with a ``boost::shared_future<std::wstring>`` as a parameter, to be set
132+
as the source of the response.
133+
*unspecified* ``destination(std::string const & source_)``
134+
Create a destination directive with a ``std::string`` as a parameter, to be
135+
set as the destination of the response.
136+
*unspecified* ``destination(std::wstring const & source_)``
137+
Create a destination directive with a ``std::wstring`` as a parameter, to be
138+
set as the destination of the response.
139+
*unspecified* ``destination(boost::shared_future<std::string> const & destination_)``
140+
Create a destination directive with a ``boost::shared_future<std::string>`` as a parameter, to be set
141+
as the destination of the response.
142+
*unspecified* ``destination(boost::shared_future<std::wstring> const & destination_)``
143+
Create a destination directive with a ``boost::shared_future<std::wstring>`` as a parameter, to be set
144+
as the destination of the response.
145+
*unspecified* ``header(std::string const & name, std::string const & value)``
146+
Create a header directive that will add the given name and value pair to the
147+
headers already associated with the response. In this case the name and
148+
values are both ``std::string``.
149+
*unspecified* ``header(std::wstring const & name, std::wstring const & value)``
150+
Create a header directive that will add the given name and value pair to the
151+
headers already associated with the response. In this case the name and
152+
values are both ``std::wstring``.
153+
*unspecified* ``remove_header(std::string const & name)``
154+
Create a remove_header directive that will remove all the occurences of the
155+
given name from the headers already associated with the response. In this
156+
case the name of the header is of type ``std::string``.
157+
*unspecified* ``remove_header(std::wstring const & name)``
158+
Create a remove_header directive that will remove all the occurences of the
159+
given name from the headers already associated with the response. In this
160+
case the name of the header is of type ``std::wstring``.
161+
*unspecified* ``body(std::string const & body_)``
162+
Create a body directive that will set the response's body to the given
163+
parameter. In this case the type of the body is an ``std::string``.
164+
*unspecified* ``body(std::wstring const & body_)``
165+
Create a body directive that will set the response's body to the given
166+
parameter. In this case the type of the body is an ``std::wstring``.
167+
*unspecified* ``body(boost::shared_future<std::string> const & body_)``
168+
Create a body directive that will set the response's body to the given
169+
parameter. In this case the type of the body is an ``boost::shared_future<std::string>``.
170+
*unspecified* ``body(boost::shared_future<std::wstring> const & body_)``
171+
Create a body directive that will set the response's body to the given
172+
parameter. In this case the type of the body is an ``boost::shared_future<std::wstring>``.
173+
*unspecified* ``version(std::string const & version_)``
174+
Create a version directive that will set the response's version to the given
175+
parameter. In this case the type of the version is an ``std::string``.
176+
177+
Note that this version includes the full ``"HTTP/"`` string.
178+
*unspecified* ``version(std::wstring const & version_)``
179+
Create a version directive that will set the response's version to the given
180+
parameter. In this case the type of the version is an ``std::wstring``.
181+
182+
Note that this version includes the full ``"HTTP/"`` string.
183+
*unspecified* ``version(boost::shared_future<std::string> const & version_)``
184+
Create a version directive that will set the response's version to the given
185+
parameter. In this case the type of the version is an ``boost::shared_future<std::string>``.
186+
187+
Note that this version includes the full ``"HTTP/"`` string.
188+
*unspecified* ``version(boost::shared_future<std::wstring> const & version_)``
189+
Create a version directive that will set the response's version to the given
190+
parameter. In this case the type of the version is an ``boost::shared_future<std::wstring>``.
191+
192+
Note that this version includes the full ``"HTTP/"`` string.
193+
*unspecified* ``status_message(std::string const & status_message_)``
194+
Create a status_message directive that will set the response's status_message to the given
195+
parameter. In this case the type of the status_message is an ``std::string``.
196+
197+
Note that this status_message includes the full ``"HTTP/"`` string.
198+
*unspecified* ``status_message(std::wstring const & status_message_)``
199+
Create a status_message directive that will set the response's status_message to the given
200+
parameter. In this case the type of the status_message is an ``std::wstring``.
201+
202+
Note that this status_message includes the full ``"HTTP/"`` string.
203+
*unspecified* ``status_message(boost::shared_future<std::string> const & status_message_)``
204+
Create a status_message directive that will set the response's status_message to the given
205+
parameter. In this case the type of the status_message is an ``boost::shared_future<std::string>``.
206+
207+
Note that this status_message includes the full ``"HTTP/"`` string.
208+
*unspecified* ``status_message(boost::shared_future<std::wstring> const & status_message_)``
209+
Create a status_message directive that will set the response's status_message to the given
210+
parameter. In this case the type of the status_message is an ``boost::shared_future<std::wstring>``.
211+
212+
Note that this status_message includes the full ``"HTTP/"`` string.
213+
*unspecified* ``status(boost::uint16_t status_)``
214+
Create a status directive that will set the response's status to the given
215+
parameter. In this case the type of ``status_`` is ``boost::uint16_t``.
216+
*unspecified* ``status(boost::shared_future<boost::uint16_t> const & status_)``
217+
Create a status directive that will set the response's status to the given
218+
parameter. In this case the type of ``status_`` is ``boost::shared_future<boost::uint16_t>``.
219+
220+
Modifiers
221+
---------
222+
223+
This section details the provided modifiers that are provided by
224+
:mod:`cpp-netlib`.
225+
226+
``template <class Tag> inline void source(basic_response<Tag> & response, typename string<Tag>::type const & source_)``
227+
Modifies the source of the given ``response``. The type of ``source_`` is
228+
dependent on the ``Tag`` specialization of ``basic_response``.
229+
``template <class Tag> inline void source(basic_response<Tag> & response, boost::shared_future<typename string<Tag>::type> const & source_)``
230+
Modifies the source of the given ``response``. The type of ``source_`` is
231+
dependent on the ``Tag`` specialization of ``basic_response``.
232+
``template <class Tag> inline void destination(basic_response<Tag> & response, typename string<Tag>::type const & destination_)``
233+
Modifies the destination of the given ``response``. The type of ``destination_`` is
234+
dependent on the ``Tag`` specialization of ``basic_response``.
235+
``template <class Tag> inline void destination(basic_response<Tag> & response, boost::shared_future<typename string<Tag>::type> const & destination_)``
236+
Modifies the destination of the given ``response``. The type of ``destination_`` is
237+
dependent on the ``Tag`` specialization of ``basic_response``.
238+
``template <class Tag> inline void add_header(basic_response<Tag> & response, typename string<Tag>::type const & name, typename string<Tag>::type const & value)``
239+
Adds a header to the given ``response``. The type of the ``name`` and
240+
``value`` parameters are dependent on the ``Tag`` specialization of
241+
``basic_response``.
242+
``template <class Tag> inline void remove_header(basic_response<Tag> & response, typename string<Tag>::type const & name)``
243+
Removes a header from the given ``response``. The type of the ``name``
244+
parameter is dependent on the ``Tag`` specialization of ``basic_response``.
245+
``template <class Tag> inline void headers(basic_response<Tag> & response, typename headers_container<basic_response<Tag> >::type const & headers_)``
246+
Sets the whole headers contained in ``response`` as the given parameter
247+
``headers_``.
248+
``template <class Tag> inline void headers(basic_response<Tag> & response, boost::shared_future<typename headers_container<basic_response<Tag> >::type> const & headers_)``
249+
Sets the whole headers contained in ``response`` as the given parameter
250+
``headers_``.
251+
``template <class Tag> inline void clear_headers(basic_response<Tag> & response)``
252+
Removes all headers from the given ``response``.
253+
``template <class Tag> inline void body(basic_response<Tag> & response, typename string<Tag>::type const & body_)``
254+
Modifies the body of the given ``response``. The type of ``body_`` is
255+
dependent on the ``Tag`` specialization of ``basic_response``.
256+
``template <class Tag> inline void body(basic_response<Tag> & response, boost::shared_future<typename string<Tag>::type> const & body_)``
257+
Modifies the body of the given ``response``. The type of ``body_`` is
258+
dependent on the ``Tag`` specialization of ``basic_response``.
259+
``template <class Tag> inline void version(basic_response<Tag> & response, typename traits::version<basic_response<Tag> >::type const & version_)``
260+
Modifies the version of the given ``response``. The type of ``version_`` is
261+
dependent on the ``Tag`` specialization of ``basic_response``.
262+
``template <class Tag> inline void status(basic_response<Tag> & response, typename traits::status<basic_response<Tag> >::type const & status_)``
263+
Modifies the status of the given ``response``. The type of ``status_`` is
264+
dependent on the ``Tag`` specialization of ``basic_response``.
265+
``template <class Tag> inline void status_message(basic_response<Tag> & response, typename traits::status_message<basic_response<Tag> >::type const & status_message_)``
266+
Modifies the status message of the given ``response``. The type of ``status_message_`` is
267+
dependent on the ``Tag`` specialization of ``basic_response``.
268+
269+
Wrappers
270+
--------
271+
272+
This section details the provided response wrappers that come with
273+
:mod:`cpp-netlib`. Wrappers are used to convert a message into a different type,
274+
usually providing accessor operations to retrieve just part of the message. This
275+
section assumes that the following using namespace directives are in
276+
effect:
277+
278+
.. code-block:: c++
279+
280+
using namespace boost::network;
281+
using namespace boost::network::http;
282+
283+
``template <class Tag>`` *unspecified* ``source(basic_response<Tag> const & response)``
284+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
285+
provides the source of a given response.
286+
``template <class Tag>`` *unspecified* ``destination(basic_response<Tag> const & response)``
287+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
288+
provides the destination of a given response.
289+
``template <class Tag>`` *unspecified* ``headers(basic_response<Tag> const & response)``
290+
Returns a wrapper convertible to ``typename headers_range<basic_response<Tag>
291+
>::type`` or ``typename basic_response<Tag>::headers_container_type`` that
292+
provides the headers of a given response.
293+
``template <class Tag>`` *unspecified* ``body(basic_response<Tag> const & response)``
294+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
295+
provides the body of a given response.
296+
``template <class Tag>`` *unspecified* ``version(basic_response<Tag> const & response)``
297+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
298+
provides the version of the given response.
299+
``template <class Tag>`` *unspecified* ``status(basic_response<Tag> const & response)``
300+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
301+
provides the status of the given response.
302+
``template <class Tag>`` *unspecified* ``status_message(basic_response<Tag> const & response)``
303+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
304+
provides the status message of the given response.

0 commit comments

Comments
 (0)