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

.. note:: Starting version 0.9, cpp-netlib clients and server implementations

by default now have an externally-linked component. This is a breaking change

for code that used to rely on cpp-netlib being a header-only library, but can

inhibited by defining the ``BOOST_NETWORK_NO_LIB`` preprocessor macro before

including any cpp-netlib header.

Constructors

~~~~~~~~~~~~

``client()``

Default constructor.

``client(client::cache_resolved)``

Construct a client which caches resolved endpoints.

``client(client::follow_redirects)``

Construct a client which follows HTTP redirects. [#]_

``client(client::cache_resolved, client::follow_redirects), client(client::follow_redirects, client::cache_resolved)``

Construct a client which caches resolved endpoints and follows HTTP

redirects. [#]_

.. [#] In Asynchronous Clients, redirects are not followed. This means the

response objects will contain whatever HTTP response was retrieved by the

client implementation.

.. [#] In Asynchronous Clients, only caching resolved endpoints take effect.

``client(boost::asio::io_service & io_service)``

Construct a client to use an existing Boost.Asio ``io_service`` instance.

``template <class ArgPack> client(ArgPack const & args)``

Pass in an argument pack. See supported parameters in the table below.

+----------------------+-------------------------------+-------------------------+

| Parameter Name | Type | Description |

+======================+===============================+=========================+

| _follow_redirects | ``bool`` | Boolean to specify |

| | | whether the client |

| | | should follow HTTP |

| | | redirects. Default is |

| | | ``false``. |

+----------------------+-------------------------------+-------------------------+

| _cache_resolved | ``bool`` | Boolean to specify |

| | | whether the client |

| | | should cache resolved |

| | | endpoints. The default |

| | | is ``false``. |

+----------------------+-------------------------------+-------------------------+

| _io_service | ``boost::asio::io_service &`` | Reference to an |

| | | instance of a |

| | | Boost.Asio |

| | | ``io_service``. |

+----------------------+-------------------------------+-------------------------+

| _openssl_certificate | string | The filename of the |

| | | certificate to load for |

| | | the SSL connection for |

| | | verification. |

+----------------------+-------------------------------+-------------------------+

| _openssl_verify_path | string | The directory from |

| | | which the certificate |

| | | authority files are |

| | | located. |

+----------------------+-------------------------------+-------------------------+

To use the above supported named parameters, you'll have code that looks like

the following:

.. code-block:: c++

using namespace boost::network::http; // parameters are in this namespace

boost::asio::io_service my_io_service;

client client_(_follow_redirects=true, _cache_resolved=true,

_io_service=my_io_service

, _openssl_certificate="/tmp/my-cert"

, _openssl_verify_path="/tmp/ca-certs/");

// use client_ as normal from here on out.

HTTP Methods

~~~~~~~~~~~~

``client_.clear_resolved_cache()``

Clear the cache of resolved endpoints.

``std::string const &`` and handler being of type ``handler_type`` but

passed in as an lvalue reference.

``template <class ArgPack> client(ArgPack const & args)``

Pass in an argument pack. See supported parameters in the table below.

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| Parameter Name | Type | Description |

+========================+==========================================+==================================================================================================+

| _address | string_type | The hostname or IP address from which the server should be bound to. This parameter is required. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _port | string_type | The port to which the server should bind and listen to. This parameter is required. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _handler | ``Handler &`` | An lvalue reference to an instance of ``Handler``. This parameter is required. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _thread_pool | ``boost::network::utils::thread_pool &`` | An lvalue reference to an instance of ``boost::network::utils::thread_pool`` -- this is the |

| | | thread pool from where the handler is invoked. This parameter is only applicable and required |

| | | for ``async_server`` instances. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _io_service | ``boost::asio::io_service &`` | An optional lvalue to an instance of ``boost::asio::io_service`` which allows the server to use |

| | | an already-constructed ``boost::asio::io_service`` instance instead of instantiating one that it |

| | | manages. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _reuse_address | ``bool`` | A boolean that specifies whether to re-use the address and port on which the server will be |

| | | bound to. This enables or disables the socket option for listener sockets. The default is |

| | | ``false``. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _report_aborted | ``bool`` | A boolean that specifies whether the listening socket should report aborted connection attempts |

| | | to the accept handler (an internal detail of cpp-netlib). This is put in place to allow for |

| | | future-proofing the code in case an optional error handler function is supported in later |

| | | releases of cpp-netlib. The default is ``false``. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _receive_buffer_size | ``int`` | The size of the socket's receive buffer. The default is defined by Boost.Asio and is |

| | | platform-dependent. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _send_buffer_size | ``int`` | The size of the socket's send buffer. The default is defined by Boost.Asio and is |

| | | platform-dependent. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _receive_low_watermark | ``int`` | The size of the socket's low watermark for its receive buffer. The default is defined by |

| | | Boost.Asio and is platform-dependent. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _send_buffer_size | ``int`` | The size of the socket's send low watermark for its send buffer. The default is defined by |

| | | Boost.Asio and is platform-dependent. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _non_blocking_io | ``bool`` | An optional bool to define whether the socket should use non-blocking I/O in case the platform |

| | | supports it. The default is ``true``. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _linger | ``bool`` | An optional bool to determine whether the socket should linger in case there's still data to be |

| | | sent out at the time of its closing. The default is ``true``. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

| _linger_timeout | ``int`` | An optional int to define the timeout to wait for socket closes before it is set to linger. |

| | | The default is ``0``. |

+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+

To use the above supported named parameters, you'll have code that looks like the following:

.. code-block:: c++

using namespace boost::network::http; // parameters are in this namespace

boost::asio::io_service my_io_service;

boost::network::utils::thread_pool pool(2);

handler handler_instance;

async_server<handler> instance(_address="0.0.0.0", _port="80", _handler=handler_instance,

_io_service=my_io_service, _thread_pool=pool,

_reuse_address=true);

instance.run();

Public Members

``````````````

What's New

************

:mod:`cpp-netlib` 0.9

---------------------

* **IMPORTANT BREAKING CHANGE**: By default all compile-time heavy parser

implementations are now compiled to external static libraries. In order to use

:mod:`cpp-netlib` in header-only mode, users must define the preprocessor

macro ``BOOST_NETWORK_NO_LIB`` before including any :mod:`cpp-netlib` header.

This breaks code that relied on the version 0.8.x line where the library is

strictly header-only.

* More consistent message API for client and server messages (request and

response objects).

* Refactoring of internal implementations to allow better separation of concerns

and more manageable coding/documentation.

* Client and Server constructors that support Boost.Parameter named parameters.

* Client and Server cosntructors now take in an optional reference to a Boost.Asio

``io_service`` to use internally.

* Documentation updates to reflect new APIs.

:mod:`cpp-netlib` 0.8

---------------------

font-weight: bold;

}

img.align-left, .figure.align-left,object.align-left {

clear: left;

float: left;

margin-right:1em;

}

img.align-right, .figure.align-right,object.align-right {

clear: right;

float: right;

margin-left:1em;

}

img.align-center, .figure.align-center,object.align-center {

display: block;

margin-left: auto;

margin-right: auto;

}

.align-left {

text-align: left;

}

}

.footnote:target {

}

.line-block {

pre {

overflow: auto;

overflow-y: hidden;/* fixes display issues on Chrome browsers */

}

td.linenospre {

@importurl(reset-fonts-grids.css);

html,body {background-image:url(./background.jpg);background-repeat:no-repeat;background-position:right top;background-attachment:fixed}

html,body {background-image:url(./orange-background.jpg);background-repeat:no-repeat;background-position:left top;background-attachment:fixed;background-color:black}

body {font:12pt"Times New Roman", Lucida, serif;color:black}

#custom-doc {width:80%;*width:720px;min-width:720px;max-width:960px;margin:auto;text-align:left;padding-top:16px;margin-top:0}

#hd {padding:4px012px0}