cpp-netlib.github.com/0.13.0/reference/http_client.html at master · cpp-netlib/cpp-netlib.github.com

731 lines (677 loc) · 71.8 KB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>HTTP Client API &#8212; cpp-netlib v0.13.0</title>
    <link rel="stylesheet" href="../_static/pyramid.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '0.13.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="HTTP Request" href="http_request.html" />
    <link rel="prev" title="Reference Manual" href="../reference.html" />
<!--[if lte IE 6]>
<link rel="stylesheet" href="../_static/ie6.css" type="text/css" media="screen" charset="utf-8" />
<![endif]-->
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
        <li class="right" style="margin-right: 10px">
          <a href="http_request.html" title="HTTP Request"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="../reference.html" title="Reference Manual"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../contents.html">cpp-netlib v0.13.0</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../reference.html" accesskey="U">Reference Manual</a> &#187;</li> 
      </ul>
    </div>  
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
  <div class="section" id="http-client-api">
<h1>HTTP Client API<a class="headerlink" href="#http-client-api" title="Permalink to this headline">¶</a></h1>
<div class="section" id="general">
<h2>General<a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
<p><code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> includes and implements a number of HTTP clients that you can
use and embed in your own applications. All of the HTTP client implementations:</p>
<blockquote>
<div><ul class="simple">
<li><strong>Cannot be copied.</strong> This means you may have to store instances of the
clients in dynamic memory if you intend to use them as function parameters
or pass them around in smart pointers or by reference.</li>
<li><strong>Assume that requests made are independent of each other.</strong> There currently
is no cookie or session management system built-in to cpp-netlib&#8217;s HTTP client
implementations.</li>
</div></blockquote>
<p>The HTTP clients all share the same API, but the internals are documented in
terms of what is different and what to expect with the different
implementations.</p>
<div class="section" id="features">
<h2>Features<a class="headerlink" href="#features" title="Permalink to this headline">¶</a></h2>
<p>The HTTP client implementation supports requesting secure HTTP (HTTPS) content
only in the following situations:</p>
<blockquote>
<div><ul class="simple">
<li><strong>Client libraries are built with ``BOOST_NETWORK_ENABLE_HTTPS``.</strong> This
tells the implementation to use HTTPS-specific code to handle HTTPS-based
content when making connections associated with HTTPS URI&#8217;s. This requires
a dependency on <a class="reference external" href="http://www.openssl.org/">OpenSSL</a>.</li>
<li><strong>The ``BOOST_NETWORK_ENABLE_HTTPS`` macro is set when compiling user
code.</strong> It is best to define this either at compile-time of all code using
the library, or before including any of the client headers.</li>
</div></blockquote>
<p>To use the client implementations that support HTTPS URIs, you may explicitly
do the following:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#define BOOST_NETWORK_ENABLE_HTTPS</span>
<span class="cp">#include</span> <span class="cpf">&lt;boost/network/include/http/client.hpp&gt;</span><span class="cp"></span>
</pre></div>
<p>This forces HTTPS support to be enabled and forces a dependency on <a class="reference external" href="http://www.openssl.org/">OpenSSL</a>.
This dependency is imposed by <a class="reference external" href="http://www.boost.org/libs/asio">Boost.Asio</a></p>
<div class="section" id="client-implementation">
<h2>Client Implementation<a class="headerlink" href="#client-implementation" title="Permalink to this headline">¶</a></h2>
<p>There is a single user-facing template class named <code class="docutils literal"><span class="pre">basic_client</span></code> which takes
three template parameters:</p>
<blockquote>
<div><ul class="simple">
<li><strong>Tag</strong> - which static tag you choose that defines the behavior of the client.</li>
<li><strong>http_version_major</strong> - an unsigned int that defines the HTTP major version
number, this directly affects the HTTP messages sent by the client.</li>
<li><strong>http_version_minor</strong> - an unsigned int that defines the HTTP minor version
number.</li>
</div></blockquote>
<p>In the above table the tags follow a pattern for describing the behavior
introduced by the tags. This pattern is shown below:</p>
<blockquote>
<div>&lt;protocol&gt;_&lt;modifier&gt;_&lt;character-width&gt;_&lt;resolve-strategy&gt;</div></blockquote>
<p>For example, the tag <code class="docutils literal"><span class="pre">http_default_8bit_tcp_resolve</span></code> indicates the protocol
<code class="docutils literal"><span class="pre">http</span></code>, a modifier <code class="docutils literal"><span class="pre">default</span></code>, a character width of <code class="docutils literal"><span class="pre">8bit</span></code>, and a resolve
strategy of <code class="docutils literal"><span class="pre">tcp_resolve</span></code>.</p>
<p>The  client is implemented as an <a class="reference external" href="http://en.wikipedia.org/wiki/Active_object">Active Object</a>. This means that the client
has and manages its own lifetime thread, and returns values that are
asynchronously filled in. The response object encapsulates futures which get
filled in once the values are available.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The client objects are thread safe, and can be shared across many
threads. Each request starts a sequence of asynchronous operations dedicated
to that request. The client does not re-cycle connections and uses a
one-request-one-connection model.</p>
<p>When a client object is destroyed, it waits for all pending asynchronous
operations to finish. Errors encountered during operations on retrieving data
from the response objects cause exceptions to be thrown &#8211; therefore it is best
that if a client object is constructed, it should outlive the response object
or be outside the try-catch block handling the errors from operations on
responses. In code, usage should look like the following:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">http</span><span class="o">::</span><span class="n">client</span> <span class="n">client</span><span class="p">;</span>
<span class="k">try</span> <span class="p">{</span>
  <span class="n">http</span><span class="o">::</span><span class="n">client</span><span class="o">::</span><span class="n">response</span> <span class="n">response</span> <span class="o">=</span> <span class="n">client</span><span class="p">.</span><span class="n">get</span><span class="p">(</span><span class="s">&quot;http://www.example.com/&quot;</span><span class="p">);</span>
  <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o">&lt;&lt;</span> <span class="n">body</span><span class="p">(</span><span class="n">response</span><span class="p">);</span>
<span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="o">&amp;</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
  <span class="c1">// deal with exceptions here</span>
<span class="p">}</span>
</pre></div>
<p>A common mistake is to declare the client inside the try block which invokes
undefined behavior when errors arise from the handling of response objects.
Previous examples cited by the documentation showed the short version of the
code which didn&#8217;t bother moving the <code class="docutils literal"><span class="pre">http::client</span></code> object outside of the same
<code class="docutils literal"><span class="pre">try</span></code> block where the request/response objects are being used.</p>
<div class="section" id="member-functions">
<h2>Member Functions<a class="headerlink" href="#member-functions" title="Permalink to this headline">¶</a></h2>
<p>In this section we assume that the following typedef is in effect:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="n">boost</span><span class="o">::</span><span class="n">network</span><span class="o">::</span><span class="n">http</span><span class="o">::</span><span class="n">basic_client</span><span class="o">&lt;</span>
    <span class="n">boost</span><span class="o">::</span><span class="n">network</span><span class="o">::</span><span class="n">http</span><span class="o">::</span><span class="n">tags</span><span class="o">::</span><span class="n">http_default_8bit_udp_resolve</span>
    <span class="p">,</span> <span class="mi">1</span>
    <span class="p">,</span> <span class="mi">1</span>
    <span class="o">&gt;</span>
    <span class="n">client</span><span class="p">;</span>
</pre></div>
<p>Also, that code using the HTTP client will have use the following header:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">&lt;boost/network/include/http/client.hpp&gt;</span><span class="cp"></span>
</pre></div>
<div class="section" id="constructors">
<h3>Constructors<a class="headerlink" href="#constructors" title="Permalink to this headline">¶</a></h3>
<p>The client implementation can be default constructed, or customized at
initialization.</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">client()</span></code></dt>
<dd>Default constructor.</dd>
<dt><code class="docutils literal"><span class="pre">explicit</span> <span class="pre">client(client::options</span> <span class="pre">const</span> <span class="pre">&amp;)</span></code></dt>
<dd>Constructor taking a <code class="docutils literal"><span class="pre">client_options&lt;Tag&gt;</span></code> object. The following table
shows the options you can set on a <code class="docutils literal"><span class="pre">client_options&lt;Tag&gt;</span></code> instance.</dd>
<div class="section" id="client-options">
<h3>Client Options<a class="headerlink" href="#client-options" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<span class="target" id="classboost_1_1network_1_1http_1_1client__options"></span><em class="property">template </em>&lt;class <em>Tag</em>&gt;</dt>
<dt id="_CPPv2N5boost7network4http14client_optionsE">
<span id="boost::network::http::client_options"></span><em class="property">class </em><code class="descclassname">boost::network::http::</code><code class="descname">client_options</code><a class="headerlink" href="#_CPPv2N5boost7network4http14client_optionsE" title="Permalink to this definition">¶</a><br /></dt>
<dd><div class="breathe-sectiondef docutils container">
<p class="breathe-sectiondef-title rubric">Public Functions</p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options14client_optionsEv">
<span id="boost::network::http::client_options::client_options"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1a86694f2abd05ea19710356b2316521db"></span><code class="descname">client_options</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options14client_optionsEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set all the options to default. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options14cache_resolvedEb">
<span id="boost::network::http::client_options::cache_resolved__b"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1aba352b068fa1c56d5523579b3a6c95b7"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">cache_resolved</code><span class="sig-paren">(</span>bool <em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options14cache_resolvedEb" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Specify whether the client should cache resolved endpoints.</p>
<p>Default: false. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options16follow_redirectsEb">
<span id="boost::network::http::client_options::follow_redirects__b"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1abf23a249d6452a1c01aefa5442dc6169"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">follow_redirects</code><span class="sig-paren">(</span>bool <em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options16follow_redirectsEb" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Specify whether the client should follow redirects.</p>
<p>Default: false. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options19openssl_certificateER11string_type">
<span id="boost::network::http::client_options::openssl_certificate__string_typeCR"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1a82bc1d5a8ea7a3afbd0fee4b9f4ed036"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">openssl_certificate</code><span class="sig-paren">(</span>string_type <em class="property">const</em> &amp;<em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options19openssl_certificateER11string_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set the filename of the certificate to load for the SSL connection for verification. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options19openssl_verify_pathER11string_type">
<span id="boost::network::http::client_options::openssl_verify_path__string_typeCR"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1a1ff45cc952acd9602a1a3dd55785645e"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">openssl_verify_path</code><span class="sig-paren">(</span>string_type <em class="property">const</em> &amp;<em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options19openssl_verify_pathER11string_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set the directory for which the certificate authority files are located. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options24openssl_certificate_fileER11string_type">
<span id="boost::network::http::client_options::openssl_certificate_file__string_typeCR"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1ada9794a5f1811fa0aac203a0d63b5bba"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">openssl_certificate_file</code><span class="sig-paren">(</span>string_type <em class="property">const</em> &amp;<em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options24openssl_certificate_fileER11string_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set the filename of the certificate to use for client-side SSL session establishment. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options24openssl_private_key_fileER11string_type">
<span id="boost::network::http::client_options::openssl_private_key_file__string_typeCR"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1a452eb90ab82b64e3bf19283c7d67014a"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">openssl_private_key_file</code><span class="sig-paren">(</span>string_type <em class="property">const</em> &amp;<em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options24openssl_private_key_fileER11string_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set the filename of the private key to use for client-side SSL session establishment. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options15openssl_ciphersER11string_type">
<span id="boost::network::http::client_options::openssl_ciphers__string_typeCR"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1afb67676c01d280c98734aba73a99fabf"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">openssl_ciphers</code><span class="sig-paren">(</span>string_type <em class="property">const</em> &amp;<em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options15openssl_ciphersER11string_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set the ciphers to support for SSL negotiation. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options20openssl_sni_hostnameER11string_type">
<span id="boost::network::http::client_options::openssl_sni_hostname__string_typeCR"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1afce001d16222b4100cfd8807dbc9938f"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">openssl_sni_hostname</code><span class="sig-paren">(</span>string_type <em class="property">const</em> &amp;<em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options20openssl_sni_hostnameER11string_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set the hostname for SSL SNI hostname support. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options15openssl_optionsEl">
<span id="boost::network::http::client_options::openssl_options__l"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1a8ac8cb6c6ee4a8f40cab38918c6c111a"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">openssl_options</code><span class="sig-paren">(</span>long <em>o</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options15openssl_optionsEl" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set the raw OpenSSL options to use for HTTPS requests. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options10io_serviceENSt10shared_ptrIN5boost4asio10io_serviceEEE">
<span id="boost::network::http::client_options::io_service__std::shared_ptr:boost::asio::io_service:"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1a60ef5526c56434b559032a0ee384da9b"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">io_service</code><span class="sig-paren">(</span>std::shared_ptr&lt;boost::asio::io_service&gt; <em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options10io_serviceENSt10shared_ptrIN5boost4asio10io_serviceEEE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Provide an <code class="docutils literal"><span class="pre">boost::asio::io_service</span></code> hosted in a shared pointer. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options18always_verify_peerEb">
<span id="boost::network::http::client_options::always_verify_peer__b"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1afe678ecb12a05ea5c1b7ba24dcc7286d"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">always_verify_peer</code><span class="sig-paren">(</span>bool <em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options18always_verify_peerEb" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set whether we always verify the peer on the other side of the HTTPS connection.</p>
<p>Default: true. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http14client_options7timeoutEi">
<span id="boost::network::http::client_options::timeout__i"></span><span class="target" id="classboost_1_1network_1_1http_1_1client__options_1a93127811abd1fe2d6e5f39e05d697c29"></span><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a> &amp;<code class="descname">timeout</code><span class="sig-paren">(</span>int <em>v</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http14client_options7timeoutEi" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Set an overall timeout for HTTP requests. </p>
<p>To use the above supported named parameters, you&#8217;ll have code that looks like
the following:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">using</span> <span class="k">namespace</span> <span class="n">boost</span><span class="o">::</span><span class="n">network</span><span class="o">::</span><span class="n">http</span><span class="p">;</span> <span class="c1">// parameters are in this namespace</span>
<span class="n">client</span><span class="o">::</span><span class="n">options</span> <span class="n">options</span><span class="p">;</span>
<span class="n">options</span><span class="p">.</span><span class="n">follow_redirects</span><span class="p">(</span><span class="nb">true</span><span class="p">)</span>
       <span class="p">.</span><span class="n">cache_resolved</span><span class="p">(</span><span class="nb">true</span><span class="p">)</span>
       <span class="p">.</span><span class="n">io_service</span><span class="p">(</span><span class="n">boost</span><span class="o">::</span><span class="n">make_shared</span><span class="o">&lt;</span><span class="n">boost</span><span class="o">::</span><span class="n">asio</span><span class="o">::</span><span class="n">io_service</span><span class="o">&gt;</span><span class="p">())</span>
       <span class="p">.</span><span class="n">openssl_certificate</span><span class="p">(</span><span class="s">&quot;/tmp/my-cert&quot;</span><span class="p">)</span>
       <span class="p">.</span><span class="n">openssl_verify_path</span><span class="p">(</span><span class="s">&quot;/tmp/ca-certs&quot;</span><span class="p">)</span>
       <span class="p">.</span><span class="n">timeout</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<span class="n">client</span> <span class="nf">client_</span><span class="p">(</span><span class="n">options</span><span class="p">);</span>
<span class="c1">// use client_ as normal from here on out.</span>
</pre></div>
<div class="section" id="http-methods">
<h3>HTTP Methods<a class="headerlink" href="#http-methods" title="Permalink to this headline">¶</a></h3>
<p>The client implementation supports various HTTP methods. The following
constructs assume that a client has been properly constructed named <code class="docutils literal"><span class="pre">client_</span></code>
and that there is an appropriately constructed request object named <code class="docutils literal"><span class="pre">request_</span></code>
and that there is an appropriately constructed response object named
<code class="docutils literal"><span class="pre">response_</span></code> like the following:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">using</span> <span class="k">namespace</span> <span class="n">boost</span><span class="o">::</span><span class="n">network</span><span class="o">::</span><span class="n">http</span><span class="p">;</span>  <span class="c1">// parameters are here</span>
<span class="n">client</span> <span class="nf">client_</span><span class="p">();</span>
<span class="n">client</span><span class="o">::</span><span class="n">request</span> <span class="n">request_</span><span class="p">(</span><span class="s">&quot;http://cpp-netib.github.com/&quot;</span><span class="p">);</span>
<span class="n">client</span><span class="o">::</span><span class="n">response</span> <span class="n">response_</span><span class="p">;</span>
</pre></div>
<dl class="class">
<span class="target" id="classboost_1_1network_1_1http_1_1basic__client"></span><em class="property">template </em>&lt;<em class="property">class</em> Tag, unsigned <em>version_major</em>, unsigned <em>version_minor</em>&gt;</dt>
<dt id="_CPPv2N5boost7network4http12basic_clientE">
<span id="boost::network::http::basic_client"></span><em class="property">class </em><code class="descclassname">boost::network::http::</code><code class="descname">basic_client</code><a class="headerlink" href="#_CPPv2N5boost7network4http12basic_clientE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Basic Client API.</p>
<p>This template defines an HTTP client object that is non-copyable and is implemented depending on the <code class="docutils literal"><span class="pre">Tag</span></code> parameter. It also hard-codes the version of HTTP to support.</p>
<p><dl class="docutils">
<dt><strong>Template Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">Tag</span></code>: The Tag type used to determine certain traits of the implementation. We use the Tag as an input to other template metafunctions to determine things like the string type, whether to use TCP or UDP for the resolver, etc. </li>
<li><code class="docutils literal"><span class="pre">version_major</span></code>: The HTTP major version. </li>
<li><code class="docutils literal"><span class="pre">version_minor</span></code>: The HTTP minor version. </li>
<p>Inherits from boost::network::http::basic_client_facade&lt; Tag, version_major, version_minor &gt;</p>
<div class="breathe-sectiondef docutils container">
<p class="breathe-sectiondef-title rubric">Public Types</p>
<dl class="type">
<dt id="_CPPv2N5boost7network4http12basic_client8tag_typeE">
<span id="boost::network::http::basic_client::tag_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client_1a483ed2fd706b2c8b6b9e2f094a751566"></span><em class="property">typedef </em>Tag <code class="descname">tag_type</code><a class="headerlink" href="#_CPPv2N5boost7network4http12basic_client8tag_typeE" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>
<dl class="type">
<dt id="_CPPv2N5boost7network4http12basic_client7optionsE">
<span id="boost::network::http::basic_client::options"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client_1af467cac98f0d5c36968c4797790cdc6e"></span><em class="property">typedef </em><a class="reference internal" href="#_CPPv2N5boost7network4http14client_optionsE" title="boost::network::http::client_options">client_options</a>&lt;Tag&gt; <code class="descname">options</code><a class="headerlink" href="#_CPPv2N5boost7network4http12basic_client7optionsE" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>
<dl class="type">
<dt id="_CPPv2N5boost7network4http19basic_client_facade11string_typeE">
<span id="boost::network::http::basic_client_facade::string_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a76c78d521b58d2abad39db9363e55d9a"></span><em class="property">typedef </em>string&lt;Tag&gt;::type <code class="descname">string_type</code><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade11string_typeE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>The type to use for strings associated with this client. Typically resolves to <code class="docutils literal"><span class="pre">std::string</span></code>. </p>
<dl class="type">
<dt id="_CPPv2N5boost7network4http19basic_client_facade7requestE">
<span id="boost::network::http::basic_client_facade::request"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a467d347dfe2fd9f2e7fd4cd0db593236"></span><em class="property">typedef </em>basic_request&lt;Tag&gt; <code class="descname">request</code><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>The request type. This models the HTTP Request concept. </p>
<dl class="type">
<dt id="_CPPv2N5boost7network4http19basic_client_facade8responseE">
<span id="boost::network::http::basic_client_facade::response"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a938acb3c2000ca0da774d0cc6ebccf45"></span><em class="property">typedef </em>basic_response&lt;Tag&gt; <code class="descname">response</code><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>The response type. This models the HTTP Response concept. </p>
<dl class="type">
<dt id="_CPPv2N5boost7network4http19basic_client_facade14const_iteratorE">
<span id="boost::network::http::basic_client_facade::const_iterator"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a52d2e33580d9ee605fe5664a4b66273b"></span><em class="property">typedef </em>std::array&lt;<em class="property">typename</em> char_&lt;Tag&gt;::type, 1024&gt;::const_iterator <code class="descname">const_iterator</code><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade14const_iteratorE" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>
<dl class="type">
<dt id="_CPPv2N5boost7network4http19basic_client_facade16char_const_rangeE">
<span id="boost::network::http::basic_client_facade::char_const_range"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a248e21fd40109dc2efec22879a94059c"></span><em class="property">typedef </em>iterator_range&lt;<a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade14const_iteratorE" title="boost::network::http::basic_client_facade::const_iterator">const_iterator</a>&gt; <code class="descname">char_const_range</code><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade16char_const_rangeE" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>
<dl class="type">
<dt id="_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE">
<span id="boost::network::http::basic_client_facade::body_callback_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a5fc067227434c1722acf944d1189868c"></span><em class="property">typedef </em>std::function&lt;void<span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade16char_const_rangeE" title="boost::network::http::basic_client_facade::char_const_range">char_const_range</a>, boost::system::error_code <em class="property">const</em>&amp;<span class="sig-paren">)</span>&gt; <code class="descname">body_callback_function_type</code><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>This callback is invoked with a range representing part of the response&#8217;s body as it comes in. In case of errors, the second argument is an error code. </p>
<dl class="type">
<dt id="_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE">
<span id="boost::network::http::basic_client_facade::body_generator_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a072d6ad63d747c62a9f99a8af77aae90"></span><em class="property">typedef </em>std::function&lt;bool<span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade11string_typeE" title="boost::network::http::basic_client_facade::string_type">string_type</a>&amp;<span class="sig-paren">)</span>&gt; <code class="descname">body_generator_function_type</code><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Functions that model this signature will be used to generate part of the body while the request is being performed. This allows users to provide a generator function that will generate the body of the request piece-wise.</p>
<p>Implementations should return <code class="docutils literal"><span class="pre">true</span></code> if there is more to the body of the request, and <code class="docutils literal"><span class="pre">false</span></code> otherwise. </p>
<div class="breathe-sectiondef docutils container">
<p class="breathe-sectiondef-title rubric">Public Functions</p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http12basic_client12basic_clientER7options">
<span id="boost::network::http::basic_client::basic_client__optionsCR"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client_1ab9dd2f520d3134a162147f021a89eee4"></span><code class="descname">basic_client</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http12basic_client7optionsE" title="boost::network::http::basic_client::options">options</a> <em class="property">const</em> &amp;<em>options</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http12basic_client12basic_clientER7options" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>This constructor takes a single options argument of type <a class="reference internal" href="#classboost_1_1network_1_1http_1_1client__options"><span class="std std-ref">client_options</span></a>. See boost/network/protocol/http/client/options.hpp for more details. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http12basic_client12basic_clientEv">
<span id="boost::network::http::basic_client::basic_client"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client_1a6b2c55e5ed7b909832118f11ec81b39f"></span><code class="descname">basic_client</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http12basic_client12basic_clientEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>This default constructor sets up the default options. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade4headER7request">
<span id="boost::network::http::basic_client_facade::head__requestCR"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a32cf25ea4bcc8ff108b96f41a769bfe2"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">head</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em class="property">const</em> &amp;<em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade4headER7request" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a HEAD request. </p>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade3getER7request27body_callback_function_type">
<span id="boost::network::http::basic_client_facade::get__requestCR.body_callback_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a0f5bb208454697b056444b0c4f413120"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">get</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em class="property">const</em> &amp;<em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>body_handler</em> = body_callback_function_type ()<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade3getER7request27body_callback_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a GET request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: The request object including the URI and headers. </li>
<li><code class="docutils literal"><span class="pre">body_handler</span></code>: If provided, a callback invoked for parts of the response&#8217;s body. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions on errors, derived from <code class="docutils literal"><span class="pre">std::exception</span></code>. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade4postE7requestR11string_typeR11string_type27body_callback_function_type28body_generator_function_type">
<span id="boost::network::http::basic_client_facade::post__request.string_typeCR.string_typeCR.body_callback_function_type.body_generator_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a00c4a3923f313c9ec06c54cce9747d2e"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">post</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade11string_typeE" title="boost::network::http::basic_client_facade::string_type">string_type</a> <em class="property">const</em> &amp;<em>body</em> = string_type (), <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade11string_typeE" title="boost::network::http::basic_client_facade::string_type">string_type</a> <em class="property">const</em> &amp;<em>content_type</em> = string_type (), <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>body_handler</em> = body_callback_function_type (), <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE" title="boost::network::http::basic_client_facade::body_generator_function_type">body_generator_function_type</a> <em>body_generator</em> = body_generator_function_type ()<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade4postE7requestR11string_typeR11string_type27body_callback_function_type28body_generator_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a POST request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: A copy of the request object including the URI and headers. </li>
<li><code class="docutils literal"><span class="pre">body</span></code>: The whole contents of the body. If provided, this overrides the body in the <code class="docutils literal"><span class="pre">request</span></code>. </li>
<li><code class="docutils literal"><span class="pre">content_type</span></code>: The content type for the request. This overrides the content type in the <code class="docutils literal"><span class="pre">request</span></code>. </li>
<li><code class="docutils literal"><span class="pre">body_handler</span></code>: The callback invoked for parts of the response body as they come in. </li>
<li><code class="docutils literal"><span class="pre">body_generator</span></code>: If provided, is invoked to generate parts of the request&#8217;s body as it is being sent. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions on errors, derived from <code class="docutils literal"><span class="pre">std::exception</span></code>. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade4postER7request28body_generator_function_type27body_callback_function_type">
<span id="boost::network::http::basic_client_facade::post__requestCR.body_generator_function_type.body_callback_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a65534f48fd4fc2f59a1849fbfaf85700"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">post</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em class="property">const</em> &amp;<em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE" title="boost::network::http::basic_client_facade::body_generator_function_type">body_generator_function_type</a> <em>body_generator</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>body_handler</em> = body_callback_function_type ()<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade4postER7request28body_generator_function_type27body_callback_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a POST request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: The request including the URI and headers. </li>
<li><code class="docutils literal"><span class="pre">body_generator</span></code>: The function to call to generate part of the body while the request is being performed. </li>
<li><code class="docutils literal"><span class="pre">callback</span></code>: If provided, the function to call for parts of the response&#8217;s body as they come in. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions derived from std::exception in case of errors. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade4postER7request27body_callback_function_type28body_generator_function_type">
<span id="boost::network::http::basic_client_facade::post__requestCR.body_callback_function_type.body_generator_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a848ceb7014c9ba5c5e7d11ad64c7110d"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">post</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em class="property">const</em> &amp;<em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>body_handler</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE" title="boost::network::http::basic_client_facade::body_generator_function_type">body_generator_function_type</a> <em>body_generator</em> = body_generator_function_type ()<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade4postER7request27body_callback_function_type28body_generator_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a POST request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: The request including the URI and headers. </li>
<li><code class="docutils literal"><span class="pre">body_generator</span></code>: The function to call to generate part of the body while the request is being performed. </li>
<li><code class="docutils literal"><span class="pre">callback</span></code>: If provided, the function to call for parts of the response&#8217;s body as they come in. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions derived from std::exception in case of errors. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade4postER7requestR11string_type27body_callback_function_type28body_generator_function_type">
<span id="boost::network::http::basic_client_facade::post__requestCR.string_typeCR.body_callback_function_type.body_generator_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1ab92a0133f3a4836b1e95d8babc39663a"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">post</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em class="property">const</em> &amp;<em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade11string_typeE" title="boost::network::http::basic_client_facade::string_type">string_type</a> <em class="property">const</em> &amp;<em>body</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>body_handler</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE" title="boost::network::http::basic_client_facade::body_generator_function_type">body_generator_function_type</a> <em>body_generator</em> = body_generator_function_type ()<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade4postER7requestR11string_type27body_callback_function_type28body_generator_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a POST request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: The request object including the URI and headers. </li>
<li><code class="docutils literal"><span class="pre">body</span></code>: The whole contents of the body. </li>
<li><code class="docutils literal"><span class="pre">body_handler</span></code>: The callback invoked for parts of the response body as they come in. </li>
<li><code class="docutils literal"><span class="pre">body_generator</span></code>: If provided, is invoked to generate parts of the request&#8217;s body as it is being sent. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions on errors, derived from <code class="docutils literal"><span class="pre">std::exception</span></code>. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade3putE7requestR11string_typeR11string_type27body_callback_function_type28body_generator_function_type">
<span id="boost::network::http::basic_client_facade::put__request.string_typeCR.string_typeCR.body_callback_function_type.body_generator_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1ab50f01d265ed427e6d09be61a3202da7"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">put</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade11string_typeE" title="boost::network::http::basic_client_facade::string_type">string_type</a> <em class="property">const</em> &amp;<em>body</em> = string_type (), <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade11string_typeE" title="boost::network::http::basic_client_facade::string_type">string_type</a> <em class="property">const</em> &amp;<em>content_type</em> = string_type (), <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>body_handler</em> = body_callback_function_type (), <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE" title="boost::network::http::basic_client_facade::body_generator_function_type">body_generator_function_type</a> <em>body_generator</em> = body_generator_function_type ()<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade3putE7requestR11string_typeR11string_type27body_callback_function_type28body_generator_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a PUT request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: A copy of the request object including the URI and headers. </li>
<li><code class="docutils literal"><span class="pre">body</span></code>: The whole contents of the body. If provided, this overrides the body in the <code class="docutils literal"><span class="pre">request</span></code>. </li>
<li><code class="docutils literal"><span class="pre">content_type</span></code>: The content type for the request. This overrides the content type in the <code class="docutils literal"><span class="pre">request</span></code>. </li>
<li><code class="docutils literal"><span class="pre">body_handler</span></code>: The callback invoked for parts of the response body as they come in. </li>
<li><code class="docutils literal"><span class="pre">body_generator</span></code>: If provided, is invoked to generate parts of the request&#8217;s body as it is being sent. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions on errors, derived from <code class="docutils literal"><span class="pre">std::exception</span></code>. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade3putER7request27body_callback_function_type28body_generator_function_type">
<span id="boost::network::http::basic_client_facade::put__requestCR.body_callback_function_type.body_generator_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a190dc9aec44d5e02bb2983b848fd639c"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">put</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em class="property">const</em> &amp;<em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>callback</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE" title="boost::network::http::basic_client_facade::body_generator_function_type">body_generator_function_type</a> <em>body_generator</em> = body_generator_function_type ()<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade3putER7request27body_callback_function_type28body_generator_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a PUT request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: The request including the URI and headers. </li>
<li><code class="docutils literal"><span class="pre">callback</span></code>: If provided, the function to call for parts of the response&#8217;s body as they come in. </li>
<li><code class="docutils literal"><span class="pre">body_generator</span></code>: The function to call to generate part of the body while the request is being performed. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions derived from std::exception in case of errors. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade3putER7request11string_type27body_callback_function_type28body_generator_function_type">
<span id="boost::network::http::basic_client_facade::put__requestCR.string_type.body_callback_function_type.body_generator_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1a261a3012fbee4237ca631ad17407af8b"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">put</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em class="property">const</em> &amp;<em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade11string_typeE" title="boost::network::http::basic_client_facade::string_type">string_type</a> <em>body</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>body_handler</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade28body_generator_function_typeE" title="boost::network::http::basic_client_facade::body_generator_function_type">body_generator_function_type</a> <em>body_generator</em> = {}<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade3putER7request11string_type27body_callback_function_type28body_generator_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a POST request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: The request object including the URI and headers. </li>
<li><code class="docutils literal"><span class="pre">body</span></code>: The whole contents of the body. </li>
<li><code class="docutils literal"><span class="pre">body_handler</span></code>: The callback invoked for parts of the response body as they come in. </li>
<li><code class="docutils literal"><span class="pre">body_generator</span></code>: If provided, is invoked to generate parts of the request&#8217;s body as it is being sent. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions on errors, derived from <code class="docutils literal"><span class="pre">std::exception</span></code>. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade7delete_ER7request27body_callback_function_type">
<span id="boost::network::http::basic_client_facade::delete___requestCR.body_callback_function_type"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1ababa4526386fb237c957d69a4137fc27"></span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade8responseE" title="boost::network::http::basic_client_facade::response">response</a> <code class="descname">delete_</code><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade7requestE" title="boost::network::http::basic_client_facade::request">request</a> <em class="property">const</em> &amp;<em>request</em>, <a class="reference internal" href="#_CPPv2N5boost7network4http19basic_client_facade27body_callback_function_typeE" title="boost::network::http::basic_client_facade::body_callback_function_type">body_callback_function_type</a> <em>body_handler</em> = {}<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade7delete_ER7request27body_callback_function_type" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Perform a DELETE request.</p>
<p><dl class="docutils">
<dt><strong>Return</strong></dt>
<dd>A response object. </dd>
<dt><strong>Parameters</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">request</span></code>: The request object including the URI and the headers. </li>
<li><code class="docutils literal"><span class="pre">body_handler</span></code>: The callback invoked for parts of the response body as they come in, if provided. </li>
<dt><strong>Exceptions</strong></dt>
<dd><ul class="breatheparameterlist first last simple">
<li><code class="docutils literal"><span class="pre">std::exception</span></code>: May throw exceptions on errors, derived from <code class="docutils literal"><span class="pre">std::exception</span></code>. </li>
<dl class="function">
<dt id="_CPPv2N5boost7network4http19basic_client_facade20clear_resolved_cacheEv">
<span id="boost::network::http::basic_client_facade::clear_resolved_cache"></span><span class="target" id="classboost_1_1network_1_1http_1_1basic__client__facade_1ab1be5f08266664c6f967d70ccf29ff4d"></span>void <code class="descname">clear_resolved_cache</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N5boost7network4http19basic_client_facade20clear_resolved_cacheEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Clears the cache of resolved endpoints. </p>
<dl class="type">
<dt id="_CPPv2N5boost7network4http6clientE">
<span id="boost::network::http::client"></span><span class="target" id="namespaceboost_1_1network_1_1http_1a0bafd7b8229c83638dc38eb646ce9ed0"></span><em class="property">typedef </em><a class="reference internal" href="#_CPPv2N5boost7network4http12basic_clientE" title="boost::network::http::basic_client">basic_client</a>&lt;BOOST_NETWORK_HTTP_CLIENT_DEFAULT_TAG, 1, 1&gt; <code class="descclassname">boost::network::http::</code><code class="descname">client</code><a class="headerlink" href="#_CPPv2N5boost7network4http6clientE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>The default HTTP client type is an asynchronous UDP-resolving HTTP/1.1 client. </p>
<div class="section" id="streaming-body-handler">
<h3>Streaming Body Handler<a class="headerlink" href="#streaming-body-handler" title="Permalink to this headline">¶</a></h3>
<p>As of v0.9.1 the library now offers a way to support a streaming body callback
function in all HTTP requests that expect a body part (GET, PUT, POST, DELETE).
A convenience macro is also provided to make callback handlers easier to write.
This macro is called <code class="docutils literal"><span class="pre">BOOST_NETWORK_HTTP_BODY_CALLBACK</span></code> which allows users to
write the following code to easily create functions or function objects that
are compatible with the callback function requirements.</p>
<p>An example of how to use the macro is shown below:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">body_handler</span> <span class="p">{</span>
    <span class="k">explicit</span> <span class="n">body_handler</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&amp;</span> <span class="n">body</span><span class="p">)</span>
    <span class="o">:</span> <span class="n">body</span><span class="p">(</span><span class="n">body</span><span class="p">)</span> <span class="p">{}</span>
    <span class="n">BOOST_NETWORK_HTTP_BODY_CALLBACK</span><span class="p">(</span><span class="k">operator</span><span class="p">(),</span> <span class="n">range</span><span class="p">,</span> <span class="n">error</span><span class="p">)</span> <span class="p">{</span>
        <span class="c1">// in here, range is the Boost.Range iterator_range, and error is</span>
        <span class="c1">// the Boost.System error code.</span>
        <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">error</span><span class="p">)</span>
            <span class="n">body</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="n">boost</span><span class="o">::</span><span class="n">begin</span><span class="p">(</span><span class="n">range</span><span class="p">),</span> <span class="n">boost</span><span class="o">::</span><span class="n">end</span><span class="p">(</span><span class="n">range</span><span class="p">));</span>
    <span class="p">}</span>
    <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&amp;</span> <span class="n">body</span><span class="p">;</span>
<span class="p">};</span>
<span class="c1">// somewhere else</span>
<span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">some_string</span><span class="p">;</span>
<span class="n">response_</span> <span class="o">=</span> <span class="n">client_</span><span class="p">.</span><span class="n">get</span><span class="p">(</span><span class="n">request</span><span class="p">(</span><span class="s">&quot;http://cpp-netlib.github.com/&quot;</span><span class="p">),</span>
                        <span class="n">body_handler</span><span class="p">(</span><span class="n">some_string</span><span class="p">));</span>
</pre></div>
<p>You can also use if for standalone functions instead if you don&#8217;t want or need
to create a function object.</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">BOOST_NETWORK_HTTP_BODY_CALLBACK</span><span class="p">(</span><span class="n">print_body</span><span class="p">,</span> <span class="n">range</span><span class="p">,</span> <span class="n">error</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">error</span><span class="p">)</span>
        <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o">&lt;&lt;</span> <span class="s">&quot;Received &quot;</span> <span class="o">&lt;&lt;</span> <span class="n">boost</span><span class="o">::</span><span class="n">distance</span><span class="p">(</span><span class="n">range</span><span class="p">)</span> <span class="o">&lt;&lt;</span> <span class="s">&quot;bytes.&quot;</span>
                  <span class="o">&lt;&lt;</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
    <span class="k">else</span>
        <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o">&lt;&lt;</span> <span class="s">&quot;Error: &quot;</span> <span class="o">&lt;&lt;</span> <span class="n">error</span> <span class="o">&lt;&lt;</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="p">}</span>
<span class="c1">// somewhere else</span>
<span class="n">response_</span> <span class="o">=</span> <span class="n">client_</span><span class="p">.</span><span class="n">get</span><span class="p">(</span><span class="n">request</span><span class="p">(</span><span class="s">&quot;http://cpp-netlib.github.com/&quot;</span><span class="p">),</span>
                        <span class="n">print_body</span><span class="p">);</span>
</pre></div>
<p>The <code class="docutils literal"><span class="pre">BOOST_NETWORK_HTTP_BODY_CALLBACK</span></code> macro is defined in
<code class="docutils literal"><span class="pre">boost/network/protocol/http/client/macros.hpp</span></code>.</p>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table Of Contents</a></h3>
<li><a class="reference internal" href="#">HTTP Client API</a><ul>
<li><a class="reference internal" href="#general">General</a></li>
<li><a class="reference internal" href="#features">Features</a></li>
<li><a class="reference internal" href="#client-implementation">Client Implementation</a></li>
<li><a class="reference internal" href="#member-functions">Member Functions</a><ul>
<li><a class="reference internal" href="#constructors">Constructors</a></li>
<li><a class="reference internal" href="#client-options">Client Options</a></li>
<li><a class="reference internal" href="#http-methods">HTTP Methods</a></li>
<li><a class="reference internal" href="#streaming-body-handler">Streaming Body Handler</a></li>
  <h4>Previous topic</h4>
  <p class="topless"><a href="../reference.html"
                        title="previous chapter">Reference Manual</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="http_request.html"
                        title="next chapter">HTTP Request</a></p>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
        <li class="right" style="margin-right: 10px">
          <a href="http_request.html" title="HTTP Request"
             >next</a></li>
        <li class="right" >
          <a href="../reference.html" title="Reference Manual"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../contents.html">cpp-netlib v0.13.0</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../reference.html" >Reference Manual</a> &#187;</li> 
      </ul>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2008-2014, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
      Last updated on Nov 09, 2017.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

http_client.html

Latest commit

History

http_client.html

File metadata and controls
