<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>HTTP</title>
<link rel="stylesheet" href="../../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="../../index.html" title="C++ Network Library 0.4">
<link rel="up" href="../protocol.html" title="Application Layer Protocols">
<link rel="prev" href="../protocol.html" title="Application Layer Protocols">
<link rel="next" href="../examples.html" title="Examples">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="http://www.boost.org/boost.png"></td>
<td align="center"><a href="http://www.boost.org/index.html">Home</a></td>
<td align="center"><a href="http://www.boost.org/libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="http://www.boost.org/more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../protocol.html"><img src="http://www.boost.org/doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../protocol.html"><img src="http://www.boost.org/doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="http://www.boost.org/doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../examples.html"><img src="http://www.boost.org/doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" title="HTTP">
<div class="titlepage"><div><div><h3 class="title">
<a name="c___network_library.protocol.http"></a><a class="link" href="http.html" title="HTTP"> HTTP</a>
</h3></div></div></div>
<p>
The C++ Network Library provides direct support for HTTP. As a motivating
example, here is the code again from the quick start.
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">network</span><span class="special">/</span><span class="identifier">protocol</span><span class="special">/</span><span class="identifier">http</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
<span class="keyword">int</span>
<span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span> <span class="special">*</span><span class="identifier">argv</span><span class="special">[])</span> <span class="special">{</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">network</span><span class="special">;</span>
<span class="identifier">http</span><span class="special">::</span><span class="identifier">request</span> <span class="identifier">request</span><span class="special">(</span><span class="string">"http://www.boost.org/"</span><span class="special">);</span>
<span class="identifier">http</span><span class="special">::</span><span class="identifier">client</span> <span class="identifier">client</span><span class="special">;</span>
<span class="identifier">http</span><span class="special">::</span><span class="identifier">response</span> <span class="identifier">response</span> <span class="special">=</span> <span class="identifier">client</span><span class="special">.</span><span class="identifier">get</span><span class="special">(</span><span class="identifier">request</span><span class="special">);</span>
<span class="comment">// print response headers
</span> <span class="identifier">headers_range</span><span class="special"><</span><span class="identifier">http</span><span class="special">::</span><span class="identifier">response</span><span class="special">>::</span><span class="identifier">type</span> <span class="identifier">hdrs</span> <span class="special">=</span> <span class="identifier">headers</span><span class="special">(</span><span class="identifier">response</span><span class="special">);</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special"><</span><span class="identifier">headers_range</span><span class="special"><</span><span class="identifier">http</span><span class="special">::</span><span class="identifier">response</span><span class="special">>::</span><span class="identifier">type</span><span class="special">>::</span><span class="identifier">type</span>
<span class="identifier">it</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span><span class="identifier">hdrs</span><span class="special">),</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">end</span><span class="special">(</span><span class="identifier">hdrs</span><span class="special">);</span>
<span class="keyword">for</span> <span class="special">(;</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">end</span><span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</span> <span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">it</span><span class="special">-></span><span class="identifier">first</span> <span class="special"><<</span> <span class="string">": "</span> <span class="special"><<</span> <span class="identifier">it</span><span class="special">-></span><span class="identifier">second</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">// print response body
</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">body</span><span class="special">(</span><span class="identifier">response</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
Before walking through exactly what is happening in this example, the principle
components are described below:
</p>
<a name="c___network_library.protocol.http.http_request"></a><h5>
<a name="id2760216"></a>
<a class="link" href="http.html#c___network_library.protocol.http.http_request">HTTP Request</a>
</h5>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">network</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">http</span> <span class="special">{</span>
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Tag</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">basic_request</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">basic_request</span><span class="special"><</span><span class="identifier">tags</span><span class="special">::</span><span class="identifier">default_</span><span class="special">></span> <span class="identifier">request</span><span class="special">;</span>
<span class="special">}}}</span>
</pre>
<p>
The <code class="literal">request</code> encapsulates information about the request
and the resource.
</p>
<a name="c___network_library.protocol.http.http_client"></a><h5>
<a name="id2760380"></a>
<a class="link" href="http.html#c___network_library.protocol.http.http_client">HTTP Client</a>
</h5>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">network</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">http</span> <span class="special">{</span>
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Tag</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">basic_client</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">basic_client</span><span class="special"><</span><span class="identifier">tags</span><span class="special">::</span><span class="identifier">default_</span><span class="special">></span> <span class="identifier">client</span><span class="special">;</span>
<span class="special">}}}</span>
</pre>
<p>
The <code class="literal">client</code> encapsulates the connection-mapping logic between
the domain and the underlying socket. Access to a resource is managed through
the <code class="literal">client</code> object.
</p>
<a name="c___network_library.protocol.http.http_response"></a><h5>
<a name="id2760550"></a>
<a class="link" href="http.html#c___network_library.protocol.http.http_response">HTTP Response</a>
</h5>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">network</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">http</span> <span class="special">{</span>
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Tag</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">basic_response</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">basic_response</span><span class="special"><</span><span class="identifier">tags</span><span class="special">::</span><span class="identifier">default_</span><span class="special">></span> <span class="identifier">response</span><span class="special">;</span>
<span class="special">}}}</span>
</pre>
<p>
The <code class="literal">response</code> encapsulates the data received from the server.
</p>
<a name="c___network_library.protocol.http.walkthrough"></a><h5>
<a name="id2760713"></a>
<a class="link" href="http.html#c___network_library.protocol.http.walkthrough">Walkthrough</a>
</h5>
<pre class="programlisting"><span class="identifier">http</span><span class="special">::</span><span class="identifier">request</span> <span class="identifier">request</span><span class="special">(</span><span class="string">"http://www.boost.org/"</span><span class="special">);</span>
</pre>
<p>
This line frames the request for the resource <a href="http://www.boost.org/" target="_top">http://www.boost.org/</a>.
</p>
<pre class="programlisting"><span class="identifier">http</span><span class="special">::</span><span class="identifier">client</span> <span class="identifier">client</span><span class="special">;</span>
</pre>
<p>
Then a client object is created that handles all HTTP requests and responses.
</p>
<pre class="programlisting"><span class="identifier">http</span><span class="special">::</span><span class="identifier">response</span> <span class="identifier">response</span> <span class="special">=</span> <span class="identifier">client</span><span class="special">.</span><span class="identifier">get</span><span class="special">(</span><span class="identifier">request</span><span class="special">);</span>
</pre>
<p>
The client simply performs the requests. The interface is trivially easy.
All HTTP methods are supported (HEAD, GET, POST, PUT, DELETE).
</p>
<p>
There are several advantages to this design:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
A <code class="literal">client</code> object manages the connection, unencumbering
the developer with this task;
</li>
<li class="listitem">
A <code class="literal">request</code> can be used with any instance of the <code class="literal">client</code>
without binding the <code class="literal">client</code> to any destination;
</li>
<li class="listitem">
By decoupling the method from the <code class="literal">request</code> object it
allows developers to create requests that may be re-used (e.g. perform
a HEAD first; if the the headers don't fulfil a certain criteria, perform
a GET using the same resource).
</li>
</ol></div>
<pre class="programlisting"><span class="comment">// print response headers
</span><span class="identifier">headers_range</span><span class="special"><</span><span class="identifier">http</span><span class="special">::</span><span class="identifier">response</span><span class="special">>::</span><span class="identifier">type</span> <span class="identifier">hdrs</span> <span class="special">=</span> <span class="identifier">headers</span><span class="special">(</span><span class="identifier">response</span><span class="special">);</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special"><</span><span class="identifier">headers_range</span><span class="special"><</span><span class="identifier">http</span><span class="special">::</span><span class="identifier">response</span><span class="special">>::</span><span class="identifier">type</span><span class="special">>::</span><span class="identifier">type</span>
<span class="identifier">it</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span><span class="identifier">hdrs</span><span class="special">),</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">end</span><span class="special">(</span><span class="identifier">hdrs</span><span class="special">);</span>
<span class="keyword">for</span> <span class="special">(;</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">end</span><span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">it</span><span class="special">-></span><span class="identifier">first</span> <span class="special"><<</span> <span class="string">": "</span> <span class="special"><<</span> <span class="identifier">it</span><span class="special">-></span><span class="identifier">second</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">// print response body
</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">body</span><span class="special">(</span><span class="identifier">response</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
Once the request has been made, and the <code class="literal">client</code> returns
a <code class="literal">response</code> object, the rest is simple. This example outputs
all the response headers and body, in this case just the Boost homepage.
</p>
<a name="c___network_library.protocol.http.using__literal_http__client__literal_"></a><h5>
<a name="id2761333"></a>
<a class="link" href="http.html#c___network_library.protocol.http.using__literal_http__client__literal_">Using
<code class="literal">http::client</code></a>
</h5>
<p>
The <code class="literal">http::client</code> supports the following operations:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><code class="literal">http::client::head</code></li>
<li class="listitem"><code class="literal">http::client::get</code></li>
<li class="listitem"><code class="literal">http::client::post</code></li>
<li class="listitem"><code class="literal">http::client::put</code></li>
<li class="listitem"><code class="literal">http::client::delete_</code></li>
</ul></div>
<p>
HTTP features can be enabled by using constructor arguments:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><code class="literal">http::client(http::client::cache_resolved)</code></li>
<li class="listitem"><code class="literal">http::client(http::client::follow_redirect)</code></li>
</ul></div>
<a name="c___network_library.protocol.http._literal_http__client__cache_resolved__literal_"></a><h6>
<a name="id2761438"></a>
<a class="link" href="http.html#c___network_library.protocol.http._literal_http__client__cache_resolved__literal_"><code class="literal">http::client::cache_resolved</code></a>
</h6>
<p>
This argument enables the caching of resolved endpoints and prevents the
client from resolving IP addresses of previously resolved hostnames.
</p>
<a name="c___network_library.protocol.http._literal_http__client__follow_redirect_s___literal_"></a><h6>
<a name="id2761470"></a>
<a class="link" href="http.html#c___network_library.protocol.http._literal_http__client__follow_redirect_s___literal_"><code class="literal">http::client::follow_redirect(s)</code></a>
</h6>
<p>
<code class="literal">http::client::follow_redirects</code> / <code class="literal">http::client::follow_redirect</code>
follow HTTP redirect(s) (300..307) by looking at the "Location"
header provided by the response(s); headers present in the original request
are preserved in the subsequent request(s).
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2008 , 2009 Glyn Matthews Dean Michael Berris<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../protocol.html"><img src="http://www.boost.org/doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../protocol.html"><img src="http://www.boost.org/doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="http://www.boost.org/doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../examples.html"><img src="http://www.boost.org/doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
