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