@@ -19,14 +19,6 @@ The HTTP clients all share the same API, but the internals are documented in
1919terms of what is different and what to expect with the different
2020implementations.
2121
22- As of 0.9.1 the default implementation for the:mod: `cpp-netlib ` HTTP client is
23- asynchronous.
24-
25- As of 0.11 the `Synchronous Clients `_ are now *DEPRECATED * and will be removed
26- in subsequent releases.
27-
28- In 0.12.x the `Synchronous Clients `_ have been removed.
29-
3022Features
3123--------
3224
@@ -55,8 +47,8 @@ This dependency is imposed by `Boost.Asio`_
5547.. _OpenSSL :http://www.openssl.org/
5648.. _`Boost.Asio` :http://www.boost.org/libs/asio
5749
58- Implementations
59- ---------------
50+ Client Implementation
51+ ---------------------
6052
6153There is a single user-facing template class named ``basic_client `` which takes
6254three template parameters:
@@ -69,14 +61,6 @@ three template parameters:
6961 * **http_version_minor ** - an unsigned int that defines the HTTP minor version
7062 number.
7163
72- There are two major different class of implementations of the ``basic_client ``
73- template that depend on which tag you choose: `Synchronous Clients `_ and
74- `Asynchronous Clients `_. These two different classes are described in their own
75- sections following this one. What follows is a table of all tags supported by
76- the HTTP client implementation provided by:mod: `cpp-netlib `.
77-
78- ---------------
79-
8064..include ::../in_depth/http_client_tags.rst
8165
8266In the above table the tags follow a pattern for describing the behavior
@@ -88,61 +72,24 @@ For example, the tag ``http_default_8bit_tcp_resolve`` indicates the protocol
8872``http ``, a modifier ``default ``, a character width of ``8bit ``, and a resolve
8973strategy of ``tcp_resolve ``.
9074
91- Synchronous Clients
92- ~~~~~~~~~~~~~~~~~~~
93-
94- Of the client tags shown in the table, the following makes the ``basic_client ``
95- behave as a fully synchronous client.
96-
97- * **http_default_8bit_tcp_resolve **
98- * **http_default_8bit_udp_resolve **
99- * **http_keepalive_8bit_tcp_resolve **
100- * **http_keepalive_8bit_udp_resolve **
101-
102- The synchronous client implements all the operations of the client underneath
103- the interface all block to wait for I/O to finish. All the member methods are
104- synchronous and will block until the response object is ready or throws if errors
105- are encountered in the performance of the HTTP requests.
106-
107- ..warning ::The synchronous clients are **NOT** thread safe. You will need to do
108- external synchronization to use synchronous client implementations.
109-
110- ..note ::As of version 0.11, all the synchronous client implementations are
111- deprecated. They will be removed in the next version of the library.
112-
113- Asynchronous Clients
114- ~~~~~~~~~~~~~~~~~~~~
75+ The client is implemented as an `Active Object `_. This means that the client
76+ has and manages its own lifetime thread, and returns values that are
77+ asynchronously filled in. The response object encapsulates futures which get
78+ filled in once the values are available.
11579
116- The following tags specify the ``basic_client `` to behave in an asynchronous
117- manner:
118-
119- * **http_async_8bit_tcp_resolve **
120- * **http_async_8bit_udp_resolve **
121-
122- An asynchronous client implementation means that``basic_client<...>`` is an
123- `Active Object `_. This means that the client has and manages its own lifetime
124- thread, and returns values that are asynchronously filled in. The response
125- object encapsulatesBoost.Thread _ futures which get filled in once the values
126- are available.
127-
128- .. _Boost.Thread :http://www.boost.org/libs/thread
12980.. _`Active Object` :http://en.wikipedia.org/wiki/Active_object
13081
131- The asynchronous clients implement all operations asynchronously which are hidden
132- from the user. The interface is still synchronous but the fetching of data
133- happens on a different thread.
82+ ..note ::The client objects are thread safe, and can be shared across many
83+ threads. Each request starts a sequence of asynchronous operations dedicated
84+ to that request. The client does not re-cycle connections and uses a
85+ one-request-one-connection model.
13486
135- ..note ::The asynchronous clients are thread safe, and can be shared across
136- many threads. Each request starts a sequence of asynchronous operations
137- dedicated to that request. The client does not re-cycle connections and uses
138- a one-request-one-connection model.
139-
140- When an asynchronous client object is destroyed, it waits for all pending
141- asynchronous operations to finish. Errors encountered during operations on
142- retrieving data from the response objects cause exceptions to be thrown --
143- therefore it is best that if a client object is constructed, it should outlive
144- the response object or be outside the try-catch block handling the errors from
145- operations on responses. In code, usage should look like the following:
87+ When a client object is destroyed, it waits for all pending asynchronous
88+ operations to finish. Errors encountered during operations on retrieving data
89+ from the response objects cause exceptions to be thrown -- therefore it is best
90+ that if a client object is constructed, it should outlive the response object
91+ or be outside the try-catch block handling the errors from operations on
92+ responses. In code, usage should look like the following:
14693
14794..code-block ::c++
14895
@@ -180,15 +127,6 @@ Also, that code using the HTTP client will have use the following header:
180127
181128 #include <boost/network/include/http/client.hpp>
182129
183- ..note ::Starting version 0.9, cpp-netlib clients and server implementations
184- by default now have an externally-linked component. This is a breaking change
185- for code that used to rely on cpp-netlib being a header-only library, but can
186- inhibited by defining the ``BOOST_NETWORK_NO_LIB `` preprocessor macro before
187- including any cpp-netlib header.
188-
189- ..note ::Starting version 0.11, cpp-netlib clients and server implementations
190- no longer support the ``BOOST_NETWORK_NO_LIB `` option.
191-
192130Constructors
193131~~~~~~~~~~~~
194132
@@ -201,56 +139,12 @@ initialization.
201139 Constructor taking a ``client_options<Tag> `` object. The following table
202140 shows the options you can set on a ``client_options<Tag> `` instance.
203141
204- +--------------------------+----------------------------+--------------------------+
205- | Parameter Name| Type| Description|
206- +==========================+============================+==========================+
207- | follow_redirects| ``bool ``| Boolean to specify|
208- | | | whether the client|
209- | | | should follow HTTP|
210- | | | redirects. Default is|
211- | | | ``false ``.|
212- +--------------------------+----------------------------+--------------------------+
213- | cache_resolved| ``bool ``| Boolean to specify|
214- | | | whether the client|
215- | | | should cache resolved|
216- | | | endpoints. The default|
217- | | | is ``false ``.|
218- +--------------------------+----------------------------+--------------------------+
219- | io_service| ``shared_ptr<io_service> ``| Shared pointer to a|
220- | | | Boost.Asio|
221- | | | ``io_service ``.|
222- +--------------------------+----------------------------+--------------------------+
223- | openssl_certificate| ``string ``| The filename of the|
224- | | | certificate to load for|
225- | | | the SSL connection for|
226- | | | verification.|
227- +--------------------------+----------------------------+--------------------------+
228- | openssl_verify_path| ``string ``| The directory from|
229- | | | which the certificate|
230- | | | authority files are|
231- | | | located.|
232- +--------------------------+----------------------------+--------------------------+
233- | always_verify_peer| ``bool ``| Boolean to specify|
234- | | | whether the client|
235- | | | should always verify|
236- | | | peers in SSL connections|
237- +--------------------------+----------------------------+--------------------------+
238- | openssl_certificate_file| ``string ``| Filename of the|
239- | | | certificate to use for|
240- | | | client-side SSL session|
241- | | | establishment.|
242- +--------------------------+----------------------------+--------------------------+
243- | openssl_private_key_file| ``string ``| Filename of the|
244- | | | private key to use for|
245- | | | client-side SSL session|
246- | | | establishment.|
247- +--------------------------+----------------------------+--------------------------+
248- | timeout| ``int ``| Number of seconds to|
249- | | | wait for client requests|
250- | | | before considering a|
251- | | | timeout has occurred.|
252- +--------------------------+----------------------------+--------------------------+
142+ Client Options
143+ ~~~~~~~~~~~~~~
253144
145+ ..doxygenclass ::boost::network::http::client_options
146+ :project: cppnetlib
147+ :members:
254148
255149To use the above supported named parameters, you'll have code that looks like
256150the following:
@@ -284,144 +178,14 @@ and that there is an appropriately constructed response object named
284178 client::request request_("http://cpp-netib.github.com/");
285179 client::responseresponse _;
286180
287- ``response_ = client_.get(request_) ``
288- Perform an HTTP GET request.
289- ``response_ = client_.get(request_, callback) ``
290- Perform an HTTP GET request, and have the body chunks be handled by the
291- ``callback `` parameter. The signature of ``callback `` should be the following:
292- ``void(iterator_range<char const *> const &, boost::system::error_code const
293- &) ``.
294- ``response_ = client_.head(request_) ``
295- Perform an HTTP HEAD request.
296- ``response_ = client_.post(request_) ``
297- Perform an HTTP POST, use the data already set in the request object which
298- includes the headers, and the body.
299- ``response_ = client_.post(request_, callback) ``
300- Perform an HTTP POST request, and have the body chunks be handled by the
301- ``callback `` parameter. The signature of ``callback `` should be the following:
302- ``void(iterator_range<char const *> const &, boost::system::error_code const
303- &) ``.
304- ``response_ = client_.post(request_, body) ``
305- Body is a string of type ``boost::network::string<Tag>::type `` where ``Tag ``
306- is the HTTP Client's ``Tag ``. The default content-type used is
307- ``x-application/octet-stream ``.
308- ``response_ = client_.post(request_, body, callback) ``
309- Body is a string of type ``boost::network::string<Tag>::type `` where ``Tag ``
310- is the HTTP Client's ``Tag ``. The default content-type used is
311- ``x-application/octet-stream ``. Have the response body chunks be handled by
312- the ``callback `` parameter. The signature of ``callback `` should be the
313- following: ``void(iterator_range<char const *> const &,
314- boost::system::error_code const &) ``.
315- ``response_ = client_.post(request_, body, content_type) ``
316- The body and content_type parameters are of type
317- ``boost::network::string<Tag>::type `` where ``Tag `` is the HTTP Client's
318- ``Tag ``. This uses the request object's other headers.
319- ``response_ = client_.post(request_, body, content_type, callback) ``
320- The body and content_type parameters are of type
321- ``boost::network::string<Tag>::type `` where ``Tag `` is the HTTP Client's
322- ``Tag ``. This uses the request object's other headers. Have the response
323- body chunks be handled by the ``callback `` parameter. The signature of
324- ``callback `` should be the following: ``void(iterator_range<char const *> const
325- &, boost::system::error_code const &) ``.
326- ``response_ = client_.post(request_, body, content_type, callback, streaming_callback) ``
327- The body and content_type parameters are of type
328- ``boost::network::string<Tag>::type `` where ``Tag `` is the HTTP Client's
329- ``Tag ``. This uses the request object's other headers. Have the response
330- body chunks be handled by the ``callback `` parameter. The signature of
331- ``callback `` should be the following: ``void(iterator_range<char const *> const
332- &, boost::system::error_code const &) ``. The ``streaming_callback ``
333- argument should have a which has a signature of the form:
334- ``bool(string_type&) ``. The provided ``string_type& `` will be streamed as
335- soon as the function returns. A return value of ``false `` signals the
336- client that the most recent invocation is the last chunk to be sent.
337- ``response_ = client_.post(request_, streaming_callback) ``
338- Perform and HTTP POST request, and have the request's body chunks be
339- generated by the ``streaming_callback `` which has a signature of the form:
340- ``bool(string_type&) ``. The provided ``string_type& `` will be streamed as
341- soon as the function returns. A return value of ``false `` signals the client
342- that the most recent invocation is the last chunk to be sent.
343- ``response_ = client_.post(request_, callback, streaming_callback) ``
344- Perform an HTTP POST request, and have the body chunks be handled by the
345- ``callback `` parameter. The signature of ``callback `` should be the
346- following: ``void(iterator_range<char const *> const &,
347- boost::system::error_code const &) ``. This form also has the request's body
348- chunks be generated by the ``streaming_callback `` which has a signature of
349- the form: ``bool(string_type&) ``. The provided ``string_type& `` will be
350- streamed as soon as the function returns. A return value of ``false ``
351- signals the client that the most recent invocation is the last chunk to be
352- sent.
353- ``response_ = client_.put(request_) ``
354- Perform an HTTP PUT, use the data already set in the request object which
355- includes the headers, and the body.
356- ``response_ = client_.put(request_, callback) ``
357- Perform an HTTP PUT request, and have the body chunks be handled by the
358- ``callback `` parameter. The signature of ``callback `` should be the following:
359- ``void(iterator_range<char const *> const &, boost::system::error_code const
360- &) ``.
361- ``response_ = client_.put(request_, body) ``
362- Body is a string of type ``boost::network::string<Tag>::type `` where ``Tag ``
363- is the HTTP Client's ``Tag ``. The default content-type used is
364- ``x-application/octet-stream ``.
365- ``response_ = client_.put(request_, body, callback) ``
366- Body is a string of type ``boost::network::string<Tag>::type `` where ``Tag ``
367- is the HTTP Client's ``Tag ``. The default content-type used is
368- ``x-application/octet-stream ``. Have the response body chunks be handled by
369- the ``callback `` parameter. The signature of ``callback `` should be the
370- following: ``void(iterator_range<char const *> const &,
371- boost::system::error_code const &) ``.
372- ``response_ = client_.put(request_, body, content_type) ``
373- The body and content_type parameters are of type
374- ``boost::network::string<Tag>::type `` where ``Tag `` is the HTTP Client's
375- ``Tag ``. This uses the request object's other headers.
376- ``response_ = client_.put(request_, body, content_type, callback) ``
377- The body and content_type parameters are of type
378- ``boost::network::string<Tag>::type `` where ``Tag `` is the HTTP Client's
379- ``Tag ``. This uses the request object's other headers. Have the response
380- body chunks be handled by the ``callback `` parameter. The signature of
381- ``callback `` should be the following: ``void(iterator_range<char const *> const
382- &, boost::system::error_code const &) ``.
383- ``response_ = client_.put(request_, body, content_type, callback, streaming_callback) ``
384- The body and content_type parameters are of type
385- ``boost::network::string<Tag>::type `` where ``Tag `` is the HTTP Client's
386- ``Tag ``. This uses the request object's other headers. Have the response
387- body chunks be handled by the ``callback `` parameter. The signature of
388- ``callback `` should be the following: ``void(iterator_range<char const *> const
389- &, boost::system::error_code const &) ``. This form also has the request's body
390- chunks be generated by the ``streaming_callback `` which has a signature of
391- the form: ``bool(string_type&) ``. The provided ``string_type& `` will be
392- streamed as soon as the function returns. A return value of ``false ``
393- signals the client that the most recent invocation is the last chunk to be
394- sent
395- ``response_ = client_.put(request_, streaming_callback) ``
396- Perform and HTTP PUT request, and have the request's body chunks be
397- generated by the ``streaming_callback `` which has a signature of the form:
398- ``bool(string_type&) ``. The provided ``string_type& `` will be streamed as
399- soon as the function returns. A return value of ``false `` signals the client
400- that the most recent invocation is the last chunk to be sent.
401- ``response_ = client_.put(request_, callback, streaming_callback) ``
402- Perform an HTTP PUT request, and have the body chunks be handled by the
403- ``callback `` parameter. The signature of ``callback `` should be the
404- following: ``void(iterator_range<char const *> const &,
405- boost::system::error_code const &) ``. This form also has the request's body
406- chunks be generated by the ``streaming_callback `` which has a signature of
407- the form: ``bool(string_type&) ``. The provided ``string_type& `` will be
408- streamed as soon as the function returns. A return value of ``false ``
409- signals the client that the most recent invocation is the last chunk to be
410- sent.
411- ``response_ = client_.delete_(request_) ``
412- Perform an HTTP DELETE request.
413- ``response_ = client_.delete_(request_, body_handler=callback) ``
414- Perform an HTTP DELETE request, and have the response body chunks be handled
415- by the ``callback `` parameter. The signature of ``callback `` should be the
416- following: ``void(iterator_range<char const *> const &,
417- boost::system::error_code const &) ``.
418-
419- Client-Specific
420- ~~~~~~~~~~~~~~~
421-
422- ``client_.clear_resolved_cache() ``
423- Clear the cache of resolved endpoints.
424181
182+ ..doxygenclass ::boost::network::http::basic_client
183+ :project: cppnetlib
184+ :members:
185+ :undoc-members:
186+
187+ ..doxygentypedef ::boost::network::http::client
188+ :project: cppnetlib
425189
426190Streaming Body Handler
427191~~~~~~~~~~~~~~~~~~~~~~
@@ -475,19 +239,3 @@ to create a function object.
475239
476240The ``BOOST_NETWORK_HTTP_BODY_CALLBACK `` macro is defined in
477241``boost/network/protocol/http/client/macros.hpp ``.
478-
479- Generated Documentation
480- -----------------------
481-
482- ..doxygenclass ::boost::network::http::client_options
483- :project: cppnetlib
484- :members:
485- :undoc-members:
486-
487- ..doxygenclass ::boost::network::http::basic_client
488- :project: cppnetlib
489- :members:
490- :undoc-members:
491-
492- ..doxygentypedef ::boost::network::http::client
493- :project: cppnetlib