<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>HTTP</title>
<link rel="stylesheet" href="../../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
<link rel="start" href="../../index.html" title="C++ Network Library">
<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" lang="en">
<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>
C++ Network Library provides direct support for HTTP. A motivating example
will show how it's intended to work:
</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="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="id2604060"></a>
<a class="link" href="http.html#c___network_library.protocol.http.http_request">HTTP Request</a>
</h5>
<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">request</span><span class="special">.</span><span class="identifier">hpp</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="id2604153"></a>
<a class="link" href="http.html#c___network_library.protocol.http.http_client">HTTP Client</a>
</h5>
<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">client</span><span class="special">.</span><span class="identifier">hpp</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="id2604253"></a>
<a class="link" href="http.html#c___network_library.protocol.http.http_response">HTTP Response</a>
</h5>
<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">response</span><span class="special">.</span><span class="identifier">hpp</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="id2604345"></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>.
This is slightly different to what one would normally expect from a request
type, but there are good reasons for this. Its useful to consider a <code class="literal">request</code>
object as the base unit of data used to instruct the client what to do.
</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 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 performs the requests on the developer's behalf. This might initially
appear counter-intuitive, since the methods GET, POST, PUT and DELETE are
associated with a request to an HTTP server.
</p>
<p>
There are several advantages to this design:
</p>
<div class="orderedlist"><ol type="1">
<li>
A <code class="literal">client</code> object manages the connection, unencumbering
the developer with this task, allowing them to better craft requests;
</li>
<li>
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>
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>
</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 Glyn Matthews<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>
