298 lines
22 KiB
HTML
298 lines
22 KiB
HTML
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>HTTP</title>
|
||
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
||
<link rel="home" href="../index.html" title="Chapter 1. Boost.Beast">
|
||
<link rel="up" href="../index.html" title="Chapter 1. Boost.Beast">
|
||
<link rel="prev" href="config/configuration_preprocessor_defin.html" title="Configuration Preprocessor Definitions">
|
||
<link rel="next" href="using_http/protocol_primer.html" title="Protocol Primer">
|
||
</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="../../../../../boost.png"></td>
|
||
<td align="center"><a href="../../../../../index.html">Home</a></td>
|
||
<td align="center"><a href="../../../../../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="../../../../../more/index.htm">More</a></td>
|
||
</tr></table>
|
||
<hr>
|
||
<div class="spirit-nav">
|
||
<a accesskey="p" href="config/configuration_preprocessor_defin.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="using_http/protocol_primer.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="beast.using_http"></a><a class="link" href="using_http.html" title="HTTP">HTTP</a>
|
||
</h2></div></div></div>
|
||
<div class="warning"><table border="0" summary="Warning">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
|
||
<th align="left">Warning</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
Higher level functions such as Basic Authentication, mime/multipart encoding,
|
||
cookies, automatic handling of redirects, gzipped transfer encodings, caching,
|
||
or proxying (to name a few) are not directly provided, but nothing stops
|
||
users from creating these features using Beast's HTTP message types.
|
||
</p></td></tr>
|
||
</table></div>
|
||
<p>
|
||
This library offers programmers simple and performant models of HTTP messages
|
||
and their associated operations including synchronous, asynchronous, and buffer-oriented
|
||
parsing and serialization of messages in the HTTP/1 wire format using <a href="../../../../../libs/asio/index.html" target="_top">Boost.Asio</a>. Specifically, the library
|
||
provides:
|
||
</p>
|
||
<div class="variablelist">
|
||
<p class="title"><b></b></p>
|
||
<dl class="variablelist">
|
||
<dt><span class="term">Message Containers</span></dt>
|
||
<dd><p>
|
||
Complete HTTP messages are modeled using the <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a> class, with possible
|
||
user customizations.
|
||
</p></dd>
|
||
<dt><span class="term">Stream Reading</span></dt>
|
||
<dd><p>
|
||
The functions <a class="link" href="ref/boost__beast__http__read.html" title="http::read"><code class="computeroutput"><span class="identifier">read</span></code></a>, <a class="link" href="ref/boost__beast__http__read_header.html" title="http::read_header"><code class="computeroutput"><span class="identifier">read_header</span></code></a>, <a class="link" href="ref/boost__beast__http__read_some.html" title="http::read_some"><code class="computeroutput"><span class="identifier">read_some</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read.html" title="http::async_read"><code class="computeroutput"><span class="identifier">async_read</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read_header.html" title="http::async_read_header"><code class="computeroutput"><span class="identifier">async_read_header</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_read_some.html" title="http::async_read_some"><code class="computeroutput"><span class="identifier">async_read_some</span></code></a> read HTTP/1
|
||
message data from a <a class="link" href="concepts/streams.html" title="Streams">stream</a>.
|
||
</p></dd>
|
||
<dt><span class="term">Stream Writing</span></dt>
|
||
<dd><p>
|
||
The functions <a class="link" href="ref/boost__beast__http__write.html" title="http::write"><code class="computeroutput"><span class="identifier">write</span></code></a>, <a class="link" href="ref/boost__beast__http__write_header.html" title="http::write_header"><code class="computeroutput"><span class="identifier">write_header</span></code></a>, <a class="link" href="ref/boost__beast__http__write_some.html" title="http::write_some"><code class="computeroutput"><span class="identifier">write_some</span></code></a>, <a class="link" href="ref/boost__beast__http__async_write.html" title="http::async_write"><code class="computeroutput"><span class="identifier">async_write</span></code></a>, <a class="link" href="ref/boost__beast__http__async_write_header.html" title="http::async_write_header"><code class="computeroutput"><span class="identifier">async_write_header</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_write_some.html" title="http::async_write_some"><code class="computeroutput"><span class="identifier">async_write_some</span></code></a> write HTTP/1
|
||
message data to a <a class="link" href="concepts/streams.html" title="Streams">stream</a>.
|
||
</p></dd>
|
||
<dt><span class="term">Serialization</span></dt>
|
||
<dd><p>
|
||
The <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> produces a series
|
||
of octet buffers conforming to the <a href="https://tools.ietf.org/html/rfc7230" target="_top">rfc7230</a>
|
||
wire representation of a <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a>.
|
||
</p></dd>
|
||
<dt><span class="term">Parsing</span></dt>
|
||
<dd><p>
|
||
The <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> attempts to convert a
|
||
series of octet buffers into a <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a>.
|
||
</p></dd>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
Interfaces for operating on HTTP messages are structured into several layers.
|
||
The highest level provides ease of use, while lower levels provide progressively
|
||
more control, options, and flexibility. At the lowest level customization points
|
||
are provided, where user defined types can replace parts of the implementation.
|
||
The layers are arranged thusly:
|
||
</p>
|
||
<div class="informaltable"><table class="table">
|
||
<colgroup>
|
||
<col>
|
||
<col>
|
||
<col>
|
||
</colgroup>
|
||
<thead><tr>
|
||
<th>
|
||
<p>
|
||
Level
|
||
</p>
|
||
</th>
|
||
<th>
|
||
<p>
|
||
Read/Write What
|
||
</p>
|
||
</th>
|
||
<th>
|
||
<p>
|
||
Description
|
||
</p>
|
||
</th>
|
||
</tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<span class="bold"><strong>6</strong></span>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
<a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
At the highest level, these free functions send or receive a complete
|
||
HTTP message in one call. They are designed for ease of use: <a class="link" href="ref/boost__beast__http__read/overload4.html" title="http::read (4 of 4 overloads)"><code class="computeroutput"><span class="identifier">read</span></code></a>, <a class="link" href="ref/boost__beast__http__write/overload4.html" title="http::write (4 of 6 overloads)"><code class="computeroutput"><span class="identifier">write</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read/overload2.html" title="http::async_read (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">async_read</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_write/overload2.html" title="http::async_write (2 of 3 overloads)"><code class="computeroutput"><span class="identifier">async_write</span></code></a>.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<span class="bold"><strong>5</strong></span>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
<a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a>, <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
For more control, callers may take responsibility for managing the
|
||
required <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> or <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> transient state
|
||
objects. This allows additional configuration such as limiting the
|
||
number of bytes for message components during parsing, or regulating
|
||
the size of buffers emitted during output. These functions send or
|
||
receive complete messages using a serializer or parser: <a class="link" href="ref/boost__beast__http__read/overload2.html" title="http::read (2 of 4 overloads)"><code class="computeroutput"><span class="identifier">read</span></code></a>, <a class="link" href="ref/boost__beast__http__write/overload2.html" title="http::write (2 of 6 overloads)"><code class="computeroutput"><span class="identifier">write</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read/overload1.html" title="http::async_read (1 of 2 overloads)"><code class="computeroutput"><span class="identifier">async_read</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_write/overload1.html" title="http::async_write (1 of 3 overloads)"><code class="computeroutput"><span class="identifier">async_write</span></code></a>.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<span class="bold"><strong>4</strong></span>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
<a class="link" href="ref/boost__beast__http__header.html" title="http::header"><code class="computeroutput"><span class="identifier">header</span></code></a>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
Sometimes it is necessary to first send or receive the HTTP header.
|
||
For example, to read the header and take action before continuing
|
||
to read the body. These functions use a <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> or <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> to read or write
|
||
the header: <a class="link" href="ref/boost__beast__http__read_header/overload2.html" title="http::read_header (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">read_header</span></code></a>, <a class="link" href="ref/boost__beast__http__write_header/overload2.html" title="http::write_header (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">write_header</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read_header.html" title="http::async_read_header"><code class="computeroutput"><span class="identifier">async_read_header</span></code></a>, and
|
||
<a class="link" href="ref/boost__beast__http__async_write_header.html" title="http::async_write_header"><code class="computeroutput"><span class="identifier">async_write_header</span></code></a>.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<span class="bold"><strong>3</strong></span>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
partial <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
All of the stream operations at higher levels thus far have operated
|
||
on a complete header or message. At this level it is possible to
|
||
send and receive messages incrementally. This allows resource constrained
|
||
implementations to perform work bounded on storage, or allows better
|
||
control when setting timeouts for example. These functions read or
|
||
write bounded amounts of data and return the number of bytes transacted:
|
||
<a class="link" href="ref/boost__beast__http__read_some/overload2.html" title="http::read_some (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">read_some</span></code></a>, <a class="link" href="ref/boost__beast__http__write_some/overload2.html" title="http::write_some (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">write_some</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read_some.html" title="http::async_read_some"><code class="computeroutput"><span class="identifier">async_read_some</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_write_some.html" title="http::async_write_some"><code class="computeroutput"><span class="identifier">async_write_some</span></code></a>.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<span class="bold"><strong>2</strong></span>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
<a href="https://tools.ietf.org/html/rfc7230#section-4.1" target="_top"><span class="emphasis"><em>chunked-body</em></span></a>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
Until now parse and serialize operations apply or remove the chunked
|
||
transfer coding as needed for message payloads whose size is not
|
||
known ahead of time. For some domain specific niches, it is necessary
|
||
to assume direct control over incoming or outgoing chunks in a chunk
|
||
encoded message payload. For parsing this is achieved by setting
|
||
hooks using the functions <a class="link" href="ref/boost__beast__http__parser/on_chunk_header.html" title="http::parser::on_chunk_header"><code class="computeroutput"><span class="identifier">on_chunk_header</span></code></a> and/or
|
||
<a class="link" href="ref/boost__beast__http__parser/on_chunk_body.html" title="http::parser::on_chunk_body"><code class="computeroutput"><span class="identifier">on_chunk_body</span></code></a>. For serializing
|
||
callers may first emit the header, and then use these buffer sequence
|
||
adapters to control the contents of each chunk including <a href="https://tools.ietf.org/html/rfc7230#section-4.1.1" target="_top"><span class="emphasis"><em>chunk
|
||
extensions</em></span></a> and the <a href="https://tools.ietf.org/html/rfc7230#section-4.1.2" target="_top"><span class="emphasis"><em>trailer-part</em></span></a>:
|
||
<a class="link" href="ref/boost__beast__http__chunk_body.html" title="http::chunk_body"><code class="computeroutput"><span class="identifier">chunk_body</span></code></a>, <a class="link" href="ref/boost__beast__http__chunk_crlf.html" title="http::chunk_crlf"><code class="computeroutput"><span class="identifier">chunk_crlf</span></code></a>, <a class="link" href="ref/boost__beast__http__chunk_header.html" title="http::chunk_header"><code class="computeroutput"><span class="identifier">chunk_header</span></code></a>, and <a class="link" href="ref/boost__beast__http__chunk_last.html" title="http::chunk_last"><code class="computeroutput"><span class="identifier">chunk_last</span></code></a>.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<span class="bold"><strong>1</strong></span>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
buffers
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
For ultimate control, the use of library stream algorithms may be
|
||
bypassed entirely and instead work directly with buffers by calling
|
||
members of <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> or <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a>.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<span class="bold"><strong>0</strong></span>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
<span class="emphasis"><em>user-defined</em></span>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
In addition to the typical customization points of <a class="link" href="concepts/streams.html" title="Streams"><span class="emphasis"><em>Stream</em></span></a>
|
||
and <a class="link" href="concepts/DynamicBuffer.html" title="DynamicBuffer"><span class="emphasis"><em>DynamicBuffer</em></span></a>,
|
||
user-defined types may replace parts of the library implementation
|
||
at the lowest level. The customization points include <a class="link" href="concepts/Fields.html" title="Fields"><span class="emphasis"><em>Fields</em></span></a>
|
||
for creating a container to store HTTP fields, <a class="link" href="concepts/Body.html" title="Body"><span class="emphasis"><em>Body</em></span></a>
|
||
for defining containers and algorithms used for HTTP message payloads,
|
||
and user-defined subclasses of <a class="link" href="ref/boost__beast__http__basic_parser.html" title="http::basic_parser"><code class="computeroutput"><span class="identifier">basic_parser</span></code></a> for implementing
|
||
custom message representation strategies.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<div class="note"><table border="0" summary="Note">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
|
||
<th align="left">Note</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top">
|
||
<p>
|
||
This documentation assumes some familiarity with <a href="../../../../../libs/asio/index.html" target="_top">Boost.Asio</a>
|
||
and the HTTP protocol specification described in <a href="https://tools.ietf.org/html/rfc7230" target="_top">rfc7230</a>.
|
||
Sample code and identifiers mentioned in this section is written as if these
|
||
declarations are in effect:
|
||
</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">beast</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="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">::</span><span class="identifier">http</span><span class="special">;</span>
|
||
</pre>
|
||
</td></tr>
|
||
</table></div>
|
||
</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 © 2016-2019 Vinnie
|
||
Falco<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="config/configuration_preprocessor_defin.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="using_http/protocol_primer.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||
</div>
|
||
</body>
|
||
</html>
|