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