Skip to content

Commit 186899f

Browse files
committed
Completing the HTTP Request API Reference.
1 parent 63d78d4 commit 186899f

File tree

1 file changed

+153
-11
lines changed

1 file changed

+153
-11
lines changed

libs/network/doc/reference_http_request.rst

Lines changed: 153 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -88,23 +88,165 @@ and also supports the following constructs.
8888
:R: The request type.
8989
:r: An instance of R.
9090
:S: The string type.
91-
:n,v: Instances of S.
92-
93-
+--------------------+--------+----------------------------------+
94-
| Construct | Result | Description |
95-
+====================+========+==================================+
96-
| ``R::string_type`` | ``S`` | The nested ``string_type`` type. |
97-
+--------------------+--------+----------------------------------+
98-
| ``R r = {n,v};`` | **NA** | Static initialization of ``r``. |
99-
+--------------------+--------+----------------------------------+
100-
101-
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: message.html#message-concept
102122

103123
Directives
104124
----------
105125

126+
This section details the provided directives that are provided by
127+
:mod:`cpp-netlib`. The section was written to assume that an appropriately
128+
constructed 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+
142+
The section also assumes that there following using namespace declaration is in
143+
effect:
144+
145+
.. code-block:: c++
146+
147+
using namespace boost::network;
148+
149+
Directives are meant to be used in the following manner:
150+
151+
.. code-block:: c++
152+
153+
request << directive(...);
154+
155+
.. warning:: There are two versions of directives, those that are applicable to
156+
messages that support narrow strings (``std::string``) and those that are
157+
applicable to messages that support wide strings (``std::wstring``). The
158+
:mod:`cpp-netlib` implementation still does not convert wide strings into
159+
UTF-8 encoded narrow strings. This will be implemented in subsequent
160+
library releases.
161+
162+
For now all the implemented directives are listed, even if some of them still
163+
do not implement things correctly.
164+
165+
*unspecified* ``source(std::string const & source_)``
166+
Create a source directive with a ``std::string`` as a parameter, to be set
167+
as the source of the request.
168+
*unspecified* ``source(std::wstring const & source_)``
169+
Create a source directive with a ``std::wstring`` as a parameter, to be set
170+
as the source of the request.
171+
*unspecified* ``destination(std::string const & source_)``
172+
Create a destination directive with a ``std::string`` as a parameter, to be
173+
set as the destination of the request.
174+
*unspecified* ``destination(std::wstring const & source_)``
175+
Create a destination directive with a ``std::wstring`` as a parameter, to be
176+
set as the destination of the request.
177+
*unspecified* ``header(std::string const & name, std::string const & value)``
178+
Create a header directive that will add the given name and value pair to the
179+
headers already associated with the request. In this case the name and
180+
values are both ``std::string``.
181+
*unspecified* ``header(std::wstring const & name, std::wstring const & value)``
182+
Create a header directive that will add the given name and value pair to the
183+
headers already associated with the request. In this case the name and
184+
values are both ``std::wstring``.
185+
*unspecified* ``remove_header(std::string const & name)``
186+
Create a remove_header directive that will remove all the occurences of the
187+
given name from the headers already associated with the request. In this
188+
case the name of the header is of type ``std::string``.
189+
*unspecified* ``remove_header(std::wstring const & name)``
190+
Create a remove_header directive that will remove all the occurences of the
191+
given name from the headers already associated with the request. In this
192+
case the name of the header is of type ``std::wstring``.
193+
*unspecified* ``body(std::string const & body_)``
194+
Create a body directive that will set the request's body to the given
195+
parameter. In this case the type of the body is an ``std::string``.
196+
*unspecified* ``body(std::wstring const & body_)``
197+
Create a body directive that will set the request's body to the given
198+
parameter. In this case the type of the body is an ``std::wstring``.
199+
106200
Modifiers
107201
---------
108202

203+
This section details the provided modifiers that are provided by
204+
:mod:`cpp-netlib`.
205+
206+
``template <class Tag> inline void source(basic_request<Tag> & request, typename string<Tag>::type const & source_)``
207+
Modifies the source of the given ``request``. The type of ``source_`` is
208+
dependent on the ``Tag`` specialization of ``basic_request``.
209+
``template <class Tag> inline void destination(basic_request<Tag> & request, typename string<Tag>::type const & destination_)``
210+
Modifies the destination of the given ``request``. The type of ``destination_`` is
211+
dependent on the ``Tag`` specialization of ``basic_request``.
212+
``template <class Tag> inline void add_header(basic_request<Tag> & request, typename string<Tag>::type const & name, typename string<Tag>::type const & value)``
213+
Adds a header to the given ``request``. The type of the ``name`` and
214+
``value`` parameters are dependent on the ``Tag`` specialization of
215+
``basic_request``.
216+
``template <class Tag> inline void remove_header(basic_request<Tag> & request, typename string<Tag>::type const & name)``
217+
Removes a header from the given ``request``. The type of the ``name``
218+
parameter is dependent on the ``Tag`` specialization of ``basic_request``.
219+
``template <class Tag> inline void clear_headers(basic_request<Tag> & request)``
220+
Removes all headers from the given ``request``.
221+
``template <class Tag> inline void body(basic_request<Tag> & request, typename string<Tag>::type const & body_)``
222+
Modifies the body of the given ``request``. The type of ``body_`` is
223+
dependent on the ``Tag`` specialization of ``basic_request``.
224+
109225
Wrappers
110226
--------
227+
228+
This section details the provided request wrappers that come with
229+
:mod:`cpp-netlib`. Wrappers are used to convert a message into a different type,
230+
usually providing accessor operations to retrieve just part of the message. This
231+
section assumes that the following using namespace directives are in
232+
effect:
233+
234+
.. code-block:: c++
235+
236+
using namespace boost::network;
237+
using namespace boost::network::http;
238+
239+
``template <class Tag>`` *unspecified* ``source(basic_request<Tag> const & request)``
240+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
241+
provides the source of a given request.
242+
``template <class Tag>`` *unspecified* ``destination(basic_request<Tag> const & request)``
243+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
244+
provides the destination of a given request.
245+
``template <class Tag>`` *unspecified* ``headers(basic_request<Tag> const & request)``
246+
Returns a wrapper convertible to ``typename headers_range<basic_request<Tag>
247+
>::type`` or ``typename basic_request<Tag>::headers_container_type`` that
248+
provides the headers of a given request.
249+
``template <class Tag>`` *unspecified* ``body(basic_request<Tag> const & request)``
250+
Returns a wrapper convertible to ``typename string<Tag>::type`` that
251+
provides the body of a given request.
252+

0 commit comments

Comments
 (0)