1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Message Stream Operations</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast"> 8<link rel="up" href="../using_http.html" title="HTTP"> 9<link rel="prev" href="message_containers.html" title="Message Containers"> 10<link rel="next" href="serializer_stream_operations.html" title="Serializer Stream Operations"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="message_containers.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_http.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="serializer_stream_operations.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="beast.using_http.message_stream_operations"></a><a class="link" href="message_stream_operations.html" title="Message Stream Operations">Message Stream 28 Operations</a> 29</h3></div></div></div> 30<p> 31 Beast provides synchronous and asynchronous algorithms to parse and serialize 32 HTTP/1 wire format messages on streams. These functions form the message-oriented 33 stream interface: 34 </p> 35<div class="table"> 36<a name="beast.using_http.message_stream_operations.message_stream_operations"></a><p class="title"><b>Table 1.19. Message Stream Operations</b></p> 37<div class="table-contents"><table class="table" summary="Message Stream Operations"> 38<colgroup> 39<col> 40<col> 41</colgroup> 42<thead><tr> 43<th> 44 <p> 45 Name 46 </p> 47 </th> 48<th> 49 <p> 50 Description 51 </p> 52 </th> 53</tr></thead> 54<tbody> 55<tr> 56<td> 57 <p> 58 <a class="link" href="../ref/boost__beast__http__read/overload3.html" title="http::read (3 of 4 overloads)"><span class="bold"><strong>read</strong></span></a> 59 </p> 60 </td> 61<td> 62 <p> 63 Read a <a class="link" href="../ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a> from a <a href="../../../../../../doc/html/boost_asio/reference/SyncReadStream.html" target="_top"><span class="emphasis"><em>SyncReadStream</em></span></a>. 64 </p> 65 </td> 66</tr> 67<tr> 68<td> 69 <p> 70 <a class="link" href="../ref/boost__beast__http__async_read/overload2.html" title="http::async_read (2 of 2 overloads)"><span class="bold"><strong>async_read</strong></span></a> 71 </p> 72 </td> 73<td> 74 <p> 75 Read a <a class="link" href="../ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a> from an <a href="../../../../../../doc/html/boost_asio/reference/AsyncReadStream.html" target="_top"><span class="emphasis"><em>AsyncReadStream</em></span></a>. 76 </p> 77 </td> 78</tr> 79<tr> 80<td> 81 <p> 82 <a class="link" href="../ref/boost__beast__http__write/overload1.html" title="http::write (1 of 6 overloads)"><span class="bold"><strong>write</strong></span></a> 83 </p> 84 </td> 85<td> 86 <p> 87 Write a <a class="link" href="../ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a> to a <a href="../../../../../../doc/html/boost_asio/reference/SyncWriteStream.html" target="_top"><span class="emphasis"><em>SyncWriteStream</em></span></a>. 88 </p> 89 </td> 90</tr> 91<tr> 92<td> 93 <p> 94 <a class="link" href="../ref/boost__beast__http__async_write.html" title="http::async_write"><span class="bold"><strong>async_write</strong></span></a> 95 </p> 96 </td> 97<td> 98 <p> 99 Write a <a class="link" href="../ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a> to an <a href="../../../../../../doc/html/boost_asio/reference/AsyncWriteStream.html" target="_top"><span class="emphasis"><em>AsyncWriteStream</em></span></a>. 100 </p> 101 </td> 102</tr> 103</tbody> 104</table></div> 105</div> 106<br class="table-break"><p> 107 All synchronous stream operations come in two varieties. One which throws 108 an exception upon error, and another which accepts as the last parameter 109 an argument of type <a class="link" href="../ref/boost__beast__error_code.html" title="error_code"><code class="computeroutput"><span class="identifier">error_code</span><span class="special">&</span></code></a>. 110 If an error occurs this argument will be set to contain the error code. 111 </p> 112<h5> 113<a name="beast.using_http.message_stream_operations.h0"></a> 114 <span class="phrase"><a name="beast.using_http.message_stream_operations.reading"></a></span><a class="link" href="message_stream_operations.html#beast.using_http.message_stream_operations.reading">Reading</a> 115 </h5> 116<p> 117 Because a serialized header is not length-prefixed, algorithms which parse 118 messages from a stream may read past the end of a message for efficiency. 119 To hold this surplus data, all stream read operations use a passed-in <a class="link" href="../concepts/DynamicBuffer.html" title="DynamicBuffer"><span class="emphasis"><em>DynamicBuffer</em></span></a> 120 which must be persisted between calls until the end of stream is reached 121 or the stream object is destroyed. Each read operation may consume bytes 122 remaining in the buffer, and leave behind new bytes. In this example we declare 123 the buffer and a message variable, then read a complete HTTP request synchronously: 124 </p> 125<pre class="programlisting"><span class="identifier">flat_buffer</span> <span class="identifier">buffer</span><span class="special">;</span> <span class="comment">// (The parser is optimized for flat buffers)</span> 126<span class="identifier">request</span><span class="special"><</span><span class="identifier">string_body</span><span class="special">></span> <span class="identifier">req</span><span class="special">;</span> 127<span class="identifier">read</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">req</span><span class="special">);</span> 128</pre> 129<p> 130 This example uses <a class="link" href="../ref/boost__beast__flat_buffer.html" title="flat_buffer"><code class="computeroutput"><span class="identifier">flat_buffer</span></code></a>. Beast's <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> is optimized for structured 131 HTTP data located in a single contiguous (<span class="emphasis"><em>flat</em></span>) memory 132 buffer. When not using a flat buffer the implementation may perform an additional 133 memory allocations to restructure the input into a single buffer for parsing. 134 </p> 135<div class="tip"><table border="0" summary="Tip"> 136<tr> 137<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> 138<th align="left">Tip</th> 139</tr> 140<tr><td align="left" valign="top"><p> 141 Other Implementations of <a class="link" href="../concepts/DynamicBuffer.html" title="DynamicBuffer"><span class="emphasis"><em>DynamicBuffer</em></span></a> 142 may avoid parser memory allocation by always returning buffer sequences 143 of length one. 144 </p></td></tr> 145</table></div> 146<p> 147 Messages may also be read asynchronously. When performing asynchronous stream 148 read operations the stream, buffer, and message variables must remain valid 149 until the operation has completed. Beast asynchronous initiation functions 150 use Asio's completion handler model. This call reads a message asynchronously 151 and reports the error code upon completion. The handler is called with the 152 error, set to any that occurs, and the number of bytes parsed. This number 153 may be used to measure the relative amount of work performed, or it may be 154 ignored as this example shows. 155 </p> 156<pre class="programlisting"><span class="identifier">flat_buffer</span> <span class="identifier">buffer</span><span class="special">;</span> 157<span class="identifier">response</span><span class="special"><</span><span class="identifier">string_body</span><span class="special">></span> <span class="identifier">res</span><span class="special">;</span> 158<span class="identifier">async_read</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">res</span><span class="special">,</span> 159 <span class="special">[&](</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">bytes_transferred</span><span class="special">)</span> 160 <span class="special">{</span> 161 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ignore_unused</span><span class="special">(</span><span class="identifier">bytes_transferred</span><span class="special">);</span> 162 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="identifier">ec</span><span class="special">.</span><span class="identifier">message</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> 163 <span class="special">});</span> 164</pre> 165<p> 166 If a read stream algorithm cannot complete its operation without exceeding 167 the maximum specified size of the dynamic buffer provided, the error <a class="link" href="../ref/boost__beast__http__error.html" title="http::error"><code class="computeroutput"><span class="identifier">buffer_overflow</span></code></a> 168 is returned. This is one technique which may be used to impose a limit on 169 the maximum size of an HTTP message header for protection from buffer overflow 170 attacks. The following code will print the error message: 171 </p> 172<pre class="programlisting"><span class="comment">// This buffer's max size is too small for much of anything</span> 173<span class="identifier">flat_buffer</span> <span class="identifier">buffer</span><span class="special">{</span><span class="number">10</span><span class="special">};</span> 174 175<span class="comment">// Try to read a request</span> 176<span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span> 177<span class="identifier">request</span><span class="special"><</span><span class="identifier">string_body</span><span class="special">></span> <span class="identifier">req</span><span class="special">;</span> 178<span class="identifier">read</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">req</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span> 179<span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span> <span class="special">==</span> <span class="identifier">http</span><span class="special">::</span><span class="identifier">error</span><span class="special">::</span><span class="identifier">buffer_overflow</span><span class="special">)</span> 180 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="string">"Buffer limit exceeded!"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 181</pre> 182<h5> 183<a name="beast.using_http.message_stream_operations.h1"></a> 184 <span class="phrase"><a name="beast.using_http.message_stream_operations.writing"></a></span><a class="link" href="message_stream_operations.html#beast.using_http.message_stream_operations.writing">Writing</a> 185 </h5> 186<p> 187 A set of free functions allow serialization of an entire HTTP message to 188 a stream. This example constructs and sends an HTTP response: 189 </p> 190<pre class="programlisting"><span class="identifier">response</span><span class="special"><</span><span class="identifier">string_body</span><span class="special">></span> <span class="identifier">res</span><span class="special">;</span> 191<span class="identifier">res</span><span class="special">.</span><span class="identifier">version</span><span class="special">(</span><span class="number">11</span><span class="special">);</span> 192<span class="identifier">res</span><span class="special">.</span><span class="identifier">result</span><span class="special">(</span><span class="identifier">status</span><span class="special">::</span><span class="identifier">ok</span><span class="special">);</span> 193<span class="identifier">res</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="identifier">field</span><span class="special">::</span><span class="identifier">server</span><span class="special">,</span> <span class="string">"Beast"</span><span class="special">);</span> 194<span class="identifier">res</span><span class="special">.</span><span class="identifier">body</span><span class="special">()</span> <span class="special">=</span> <span class="string">"Hello, world!"</span><span class="special">;</span> 195<span class="identifier">res</span><span class="special">.</span><span class="identifier">prepare_payload</span><span class="special">();</span> 196 197<span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span> 198<span class="identifier">write</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">res</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span> 199</pre> 200<p> 201 The asynchronous version could be used instead: 202 </p> 203<pre class="programlisting"><span class="identifier">async_write</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">res</span><span class="special">,</span> 204 <span class="special">[&](</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">bytes_transferred</span><span class="special">)</span> 205 <span class="special">{</span> 206 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ignore_unused</span><span class="special">(</span><span class="identifier">bytes_transferred</span><span class="special">);</span> 207 <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span> 208 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="identifier">ec</span><span class="special">.</span><span class="identifier">message</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> 209 <span class="special">});</span> 210</pre> 211<p> 212 The completion handler is called with the number of bytes written to the 213 stream, which includes protocol specific data such as the delimiters in the 214 header and line endings. The number may be used to measure the amount of 215 data transferred, or it may be ignored as in the example. 216 </p> 217</div> 218<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 219<td align="left"></td> 220<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 221 Falco<p> 222 Distributed under the Boost Software License, Version 1.0. (See accompanying 223 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>) 224 </p> 225</div></td> 226</tr></table> 227<hr> 228<div class="spirit-nav"> 229<a accesskey="p" href="message_containers.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_http.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="serializer_stream_operations.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 230</div> 231</body> 232</html> 233
