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