1 2HTTP Request 3============ 4 5This part of the documentation talks about the publicly accessible API of the 6HTTP Request objects. This section details the `Request Concepts`_ requirements, 7the implemented and required Directives_, Modifiers_, and Wrappers_ that work 8with the HTTP Request objects. 9 10Request Concepts 11---------------- 12 13There are two generally supported Request Concepts implemented in the library. 14The first of two is the `Normal Client Request Concept`_ and the second is the 15`Pod Server Request Concept`_. 16 17The `Normal Client Request Concept`_ is what the HTTP Client interface requires. 18All operations performed internally by the HTTP Client abide by the interface 19required by this concept definition. 20 21The `Pod Server Request Concept`_ is as the name suggests what the HTTP Server 22implementation requires from Request Objects. 23 24Switching on whether the `Request` concept chooses either of the `Normal Client 25Request Concept`_ or the `Pod Server Request Concept`_ is done through the 26nested ``tag`` type and whether that tag derives from the root tag ``pod``. 27Simply, if the Request type's nested ``tag`` type derives from 28``boost::network::tags::pod`` then it chooses to enforce the `Pod Server Request 29Concept`_, otherwise it chooses the `Normal Client Request Concept`_. 30 31Normal Client Request Concept 32~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 33 34A type models the Normal Client Request Concept if it models the `Message 35Concept`_ 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 80Pod Server Request Concept 81~~~~~~~~~~~~~~~~~~~~~~~~~~ 82 83A type models the Pod Server Request Concept if it models the `Message Concept`_ 84and 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: ../in_depth/message.html#message-concept 122 123Directives 124---------- 125 126This section details the provided directives that are provided by 127:mod:`cpp-netlib`. The section was written to assume that an appropriately 128constructed 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 142The section also assumes that there following using namespace declaration is in 143effect: 144 145.. code-block:: c++ 146 147 using namespace boost::network; 148 149Directives are meant to be used in the following manner: 150 151.. code-block:: c++ 152 153 request << directive(...); 154 155.. warning:: 156 157 There are two versions of directives, those that are applicable to 158 messages that support narrow strings (``std::string``) and those that are 159 applicable to messages that support wide strings (``std::wstring``). The 160 :mod:`cpp-netlib` implementation still does not convert wide strings into 161 UTF-8 encoded narrow strings. This will be implemented in subsequent 162 library releases. 163 164 For now all the implemented directives are listed, even if some of them still 165 do not implement things correctly. 166 167*unspecified* ``source(std::string const & source_)`` 168 Create a source directive with a ``std::string`` as a parameter, to be set 169 as the source of the request. 170*unspecified* ``source(std::wstring const & source_)`` 171 Create a source directive with a ``std::wstring`` as a parameter, to be set 172 as the source of the request. 173*unspecified* ``destination(std::string const & source_)`` 174 Create a destination directive with a ``std::string`` as a parameter, to be 175 set as the destination of the request. 176*unspecified* ``destination(std::wstring const & source_)`` 177 Create a destination directive with a ``std::wstring`` as a parameter, to be 178 set as the destination of the request. 179*unspecified* ``header(std::string const & name, std::string const & value)`` 180 Create a header directive that will add the given name and value pair to the 181 headers already associated with the request. In this case the name and 182 values are both ``std::string``. 183*unspecified* ``header(std::wstring const & name, std::wstring const & value)`` 184 Create a header directive that will add the given name and value pair to the 185 headers already associated with the request. In this case the name and 186 values are both ``std::wstring``. 187*unspecified* ``remove_header(std::string const & name)`` 188 Create a remove_header directive that will remove all the occurences of the 189 given name from the headers already associated with the request. In this 190 case the name of the header is of type ``std::string``. 191*unspecified* ``remove_header(std::wstring const & name)`` 192 Create a remove_header directive that will remove all the occurences of the 193 given name from the headers already associated with the request. In this 194 case the name of the header is of type ``std::wstring``. 195*unspecified* ``body(std::string const & body_)`` 196 Create a body directive that will set the request's body to the given 197 parameter. In this case the type of the body is an ``std::string``. 198*unspecified* ``body(std::wstring const & body_)`` 199 Create a body directive that will set the request's body to the given 200 parameter. In this case the type of the body is an ``std::wstring``. 201 202Modifiers 203--------- 204 205This section details the provided modifiers that are provided by 206:mod:`cpp-netlib`. 207 208``template <class Tag> inline void source(basic_request<Tag> & request, typename string<Tag>::type const & source_)`` 209 Modifies the source of the given ``request``. The type of ``source_`` is 210 dependent on the ``Tag`` specialization of ``basic_request``. 211``template <class Tag> inline void destination(basic_request<Tag> & request, typename string<Tag>::type const & destination_)`` 212 Modifies the destination of the given ``request``. The type of ``destination_`` is 213 dependent on the ``Tag`` specialization of ``basic_request``. 214``template <class Tag> inline void add_header(basic_request<Tag> & request, typename string<Tag>::type const & name, typename string<Tag>::type const & value)`` 215 Adds a header to the given ``request``. The type of the ``name`` and 216 ``value`` parameters are dependent on the ``Tag`` specialization of 217 ``basic_request``. 218``template <class Tag> inline void remove_header(basic_request<Tag> & request, typename string<Tag>::type const & name)`` 219 Removes a header from the given ``request``. The type of the ``name`` 220 parameter is dependent on the ``Tag`` specialization of ``basic_request``. 221``template <class Tag> inline void clear_headers(basic_request<Tag> & request)`` 222 Removes all headers from the given ``request``. 223``template <class Tag> inline void body(basic_request<Tag> & request, typename string<Tag>::type const & body_)`` 224 Modifies the body of the given ``request``. The type of ``body_`` is 225 dependent on the ``Tag`` specialization of ``basic_request``. 226 227Wrappers 228-------- 229 230This section details the provided request wrappers that come with 231:mod:`cpp-netlib`. Wrappers are used to convert a message into a different type, 232usually providing accessor operations to retrieve just part of the message. This 233section assumes that the following using namespace directives are in 234effect: 235 236.. code-block:: c++ 237 238 using namespace boost::network; 239 using namespace boost::network::http; 240 241``template <class Tag>`` *unspecified* ``source(basic_request<Tag> const & request)`` 242 Returns a wrapper convertible to ``typename string<Tag>::type`` that 243 provides the source of a given request. 244``template <class Tag>`` *unspecified* ``destination(basic_request<Tag> const & request)`` 245 Returns a wrapper convertible to ``typename string<Tag>::type`` that 246 provides the destination of a given request. 247``template <class Tag>`` *unspecified* ``headers(basic_request<Tag> const & request)`` 248 Returns a wrapper convertible to ``typename headers_range<basic_request<Tag> 249 >::type`` or ``typename basic_request<Tag>::headers_container_type`` that 250 provides the headers of a given request. 251``template <class Tag>`` *unspecified* ``body(basic_request<Tag> const & request)`` 252 Returns a wrapper convertible to ``typename string<Tag>::type`` that 253 provides the body of a given request. 254 255