Skip to content

Commit 072ac23

Browse files
committed
Documenting API changes for the HTTP Client.
1 parent dd026f3 commit 072ac23

File tree

1 file changed

+43
-12
lines changed

1 file changed

+43
-12
lines changed

libs/network/doc/reference_http_client.rst

Lines changed: 43 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,12 @@ Also, that code using the HTTP client will have use the following header:
122122

123123
#include <boost/network/include/http/client.hpp>
124124

125+
.. note:: Starting version 0.9, cpp-netlib clients and server implementations
126+
by default now have an externally-linked component. This is a breaking change
127+
for code that used to rely on cpp-netlib being a header-only library, but can
128+
inhibited by defining the ``BOOST_NETWORK_NO_LIB`` preprocessor macro before
129+
including any cpp-netlib header.
130+
125131
Constructors
126132
~~~~~~~~~~~~
127133

@@ -130,18 +136,42 @@ initialization.
130136

131137
``client()``
132138
Default constructor.
133-
``client(client::cache_resolved)``
134-
Construct a client which caches resolved endpoints.
135-
``client(client::follow_redirects)``
136-
Construct a client which follows HTTP redirects. [#]_
137-
``client(client::cache_resolved, client::follow_redirects), client(client::follow_redirects, client::cache_resolved)``
138-
Construct a client which caches resolved endpoints and follows HTTP
139-
redirects. [#]_
140-
141-
.. [#] In Asynchronous Clients, redirects are not followed. This means the
142-
response objects will contain whatever HTTP response was retrieved by the
143-
client implementation.
144-
.. [#] In Asynchronous Clients, only caching resolved endpoints take effect.
139+
``client(boost::asio::io_service & io_service)``
140+
Construct a client to use an existing Boost.Asio ``io_service`` instance.
141+
``template <class ArgPack> client(ArgPack const & args)``
142+
Pass in an argument pack. See supported parameters in the table below.
143+
144+
+-------------------+-------------------------------+-------------------------+
145+
| Parameter Name | Type | Description |
146+
+===================+===============================+=========================+
147+
| _follow_redirects | ``bool`` | Boolean to specify |
148+
| | | whether the client |
149+
| | | should follow HTTP |
150+
| | | redirects. Default is |
151+
| | | ``false``. |
152+
+-------------------+-------------------------------+-------------------------+
153+
| _cache_resolved | ``bool`` | Boolean to specify |
154+
| | | whether the client |
155+
| | | should cache resolved |
156+
| | | endpoints. The default |
157+
| | | is ``false``. |
158+
+-------------------+-------------------------------+-------------------------+
159+
| _io_service | ``boost::asio::io_service &`` | Reference to an |
160+
| | | instance of a |
161+
| | | Boost.Asio |
162+
| | | ``io_service``. |
163+
+-------------------+-------------------------------+-------------------------+
164+
165+
To use the above supported named parameters, you'll have code that looks like
166+
the following:
167+
168+
.. code-block:: c++
169+
170+
using namespace boost::network::http; // parameters are in this namespace
171+
boost::asio::io_service my_io_service;
172+
client client_(_follow_redirects=true, _cache_resolved=true,
173+
_io_service=my_io_service);
174+
// use client_ as normal from here on out.
145175

146176
HTTP Methods
147177
~~~~~~~~~~~~
@@ -193,3 +223,4 @@ Client-Specific
193223
``client_.clear_resolved_cache()``
194224
Clear the cache of resolved endpoints.
195225

226+

0 commit comments

Comments
 (0)