1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>BodyReader</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="../concepts.html" title="Concepts"> 9<link rel="prev" href="Body.html" title="Body"> 10<link rel="next" href="BodyWriter.html" title="BodyWriter"> 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="Body.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.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="BodyWriter.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.concepts.BodyReader"></a><a class="link" href="BodyReader.html" title="BodyReader">BodyReader</a> 28</h3></div></div></div> 29<p> 30 A <span class="bold"><strong>BodyReader</strong></span> provides an online algorithm 31 to transfer a series of zero or more buffers containing parsed body octets 32 into a message container. The <a class="link" href="../ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> creates an instance of this 33 type when needed, and calls into it zero or more times to transfer buffers. 34 The interface of <span class="bold"><strong>BodyReader</strong></span> is intended 35 to allow the conversion of buffers into these scenarios for representation: 36 </p> 37<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 38<li class="listitem"> 39 Storing a body in a dynamic buffer 40 </li> 41<li class="listitem"> 42 Storing a body in a user defined container with a custom allocator 43 </li> 44<li class="listitem"> 45 Transformation of incoming body data before storage, for example to compress 46 it first. 47 </li> 48<li class="listitem"> 49 Saving body data to a file 50 </li> 51</ul></div> 52<h5> 53<a name="beast.concepts.BodyReader.h0"></a> 54 <span class="phrase"><a name="beast.concepts.BodyReader.associated_types"></a></span><a class="link" href="BodyReader.html#beast.concepts.BodyReader.associated_types">Associated 55 Types</a> 56 </h5> 57<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 58<li class="listitem"> 59 <a class="link" href="../ref/boost__beast__http__is_body_reader.html" title="http::is_body_reader"><code class="computeroutput"><span class="identifier">is_body_reader</span></code></a> 60 </li> 61<li class="listitem"> 62 <a class="link" href="Body.html" title="Body"><span class="emphasis"><em>Body</em></span></a> 63 </li> 64</ul></div> 65<h5> 66<a name="beast.concepts.BodyReader.h1"></a> 67 <span class="phrase"><a name="beast.concepts.BodyReader.requirements"></a></span><a class="link" href="BodyReader.html#beast.concepts.BodyReader.requirements">Requirements</a> 68 </h5> 69<div class="warning"><table border="0" summary="Warning"> 70<tr> 71<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td> 72<th align="left">Warning</th> 73</tr> 74<tr><td align="left" valign="top"><p> 75 These requirements may undergo non-backward compatible changes in subsequent 76 versions. 77 </p></td></tr> 78</table></div> 79<p> 80 In this table: 81 </p> 82<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 83<li class="listitem"> 84 <code class="computeroutput"><span class="identifier">R</span></code> denotes a type meeting 85 the requirements of <span class="bold"><strong>BodyReader</strong></span>. 86 </li> 87<li class="listitem"> 88 <code class="computeroutput"><span class="identifier">B</span></code> denotes a <a class="link" href="Body.html" title="Body"><span class="emphasis"><em>Body</em></span></a> 89 where <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">is_same</span><span class="special"><</span><span class="identifier">R</span><span class="special">,</span> <span class="identifier">B</span><span class="special">::</span><span class="identifier">reader</span><span class="special">>::</span><span class="identifier">value</span> <span class="special">==</span> 90 <span class="keyword">true</span></code>. 91 </li> 92<li class="listitem"> 93 <code class="computeroutput"><span class="identifier">a</span></code> denotes a value of 94 type <code class="computeroutput"><span class="identifier">R</span></code>. 95 </li> 96<li class="listitem"> 97 <code class="computeroutput"><span class="identifier">b</span></code> is an object whose 98 type meets the requirements of <a href="../../../../../../doc/html/boost_asio/reference/ConstBufferSequence.html" target="_top"><span class="emphasis"><em>ConstBufferSequence</em></span></a> 99 </li> 100<li class="listitem"> 101 <code class="computeroutput"><span class="identifier">h</span></code> denotes a value of 102 type <code class="computeroutput"><span class="identifier">header</span><span class="special"><</span><span class="identifier">isRequest</span><span class="special">,</span> 103 <span class="identifier">Fields</span><span class="special">>&</span></code>. 104 </li> 105<li class="listitem"> 106 <code class="computeroutput"><span class="identifier">v</span></code> denotes a value of 107 type <code class="computeroutput"><span class="identifier">Body</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">&</span></code>. 108 </li> 109<li class="listitem"> 110 <code class="computeroutput"><span class="identifier">n</span></code> is a value of type 111 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span><span class="special">></span></code>. 112 </li> 113<li class="listitem"> 114 <code class="computeroutput"><span class="identifier">ec</span></code> is a value of type 115 <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>. 116 </li> 117</ul></div> 118<div class="table"> 119<a name="beast.concepts.BodyReader.valid_expressions"></a><p class="title"><b>Table 1.38. Valid expressions</b></p> 120<div class="table-contents"><table class="table" summary="Valid expressions"> 121<colgroup> 122<col> 123<col> 124<col> 125</colgroup> 126<thead><tr> 127<th> 128 <p> 129 Expression 130 </p> 131 </th> 132<th> 133 <p> 134 Type 135 </p> 136 </th> 137<th> 138 <p> 139 Semantics, Pre/Post-conditions 140 </p> 141 </th> 142</tr></thead> 143<tbody> 144<tr> 145<td> 146 <p> 147 <code class="computeroutput"><span class="identifier">R</span><span class="special">{</span><span class="identifier">h</span><span class="special">,</span><span class="identifier">v</span><span class="special">};</span></code> 148 </p> 149 </td> 150<td> 151 </td> 152<td> 153 <p> 154 Constructible from <code class="computeroutput"><span class="identifier">h</span></code> 155 and <code class="computeroutput"><span class="identifier">v</span></code>. The lifetime 156 of <code class="computeroutput"><span class="identifier">h</span></code> and <code class="computeroutput"><span class="identifier">v</span></code> is guaranteed to end no earlier 157 than after the <code class="computeroutput"><span class="identifier">R</span></code> 158 is destroyed. The reader shall not access the contents of <code class="computeroutput"><span class="identifier">h</span></code> or <code class="computeroutput"><span class="identifier">v</span></code> 159 before the first call to <code class="computeroutput"><span class="identifier">init</span></code>, 160 permitting lazy construction of the message. 161 </p> 162 </td> 163</tr> 164<tr> 165<td> 166 <p> 167 <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">init</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span> 168 <span class="identifier">ec</span><span class="special">)</span></code> 169 </p> 170 </td> 171<td> 172 </td> 173<td> 174 <p> 175 Called once to fully initialize the object before any calls to 176 <code class="computeroutput"><span class="identifier">put</span></code>. The message 177 body is valid before entering this function, and remains valid 178 until the reader is destroyed. The value of <code class="computeroutput"><span class="identifier">n</span></code> 179 will be set to the content length of the body if known, otherwise 180 <code class="computeroutput"><span class="identifier">n</span></code> will be equal 181 to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span></code>. Implementations of <span class="bold"><strong>BodyReader</strong></span> may use this information to optimize 182 allocation. 183 </p> 184 <p> 185 The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 186 if there was no error or set to the appropriate error code if there 187 was one. 188 </p> 189 </td> 190</tr> 191<tr> 192<td> 193 <p> 194 <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">put</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span><span class="identifier">ec</span><span class="special">)</span></code> 195 </p> 196 </td> 197<td> 198 <p> 199 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code> 200 </p> 201 </td> 202<td> 203 <p> 204 This function is called to append some or all of the buffers specified 205 by <code class="computeroutput"><span class="identifier">b</span></code> into the body 206 representation. The number of bytes inserted from <code class="computeroutput"><span class="identifier">b</span></code> is returned. If the number 207 of bytes inserted is less than the total input, the remainder of 208 the input will be presented in the next call to <code class="computeroutput"><span class="identifier">put</span></code>. 209 The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 210 if there was no error or set to the appropriate error code if there 211 was one. 212 </p> 213 </td> 214</tr> 215<tr> 216<td> 217 <p> 218 <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">finish</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span></code> 219 </p> 220 </td> 221<td> 222 </td> 223<td> 224 <p> 225 This function is called when no more body octets are remaining. 226 The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 227 if there was no error or set to the appropriate error code if there 228 was one. 229 </p> 230 </td> 231</tr> 232<tr> 233<td> 234 <p> 235 <code class="computeroutput"><span class="identifier">is_body_reader</span><span class="special"><</span><span class="identifier">B</span><span class="special">></span></code> 236 </p> 237 </td> 238<td> 239 <p> 240 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">true_type</span></code> 241 </p> 242 </td> 243<td> 244 <p> 245 An alias for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">true_type</span></code> 246 for <code class="computeroutput"><span class="identifier">B</span></code>, otherwise 247 an alias for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">false_type</span></code>. 248 </p> 249 </td> 250</tr> 251</tbody> 252</table></div> 253</div> 254<br class="table-break"><h5> 255<a name="beast.concepts.BodyReader.h2"></a> 256 <span class="phrase"><a name="beast.concepts.BodyReader.exemplar"></a></span><a class="link" href="BodyReader.html#beast.concepts.BodyReader.exemplar">Exemplar</a> 257 </h5> 258<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">BodyReader</span> 259<span class="special">{</span> 260 <span class="comment">/** Construct the reader. 261 262 @param h The header for the message being parsed 263 264 @param body The body to store the parsed results into 265 */</span> 266 <span class="keyword">template</span><span class="special"><</span><span class="keyword">bool</span> <span class="identifier">isRequest</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Fields</span><span class="special">></span> 267 <span class="identifier">BodyReader</span><span class="special">(</span><span class="identifier">header</span><span class="special"><</span><span class="identifier">isRequest</span><span class="special">,</span> <span class="identifier">Fields</span><span class="special">>&</span> <span class="identifier">h</span><span class="special">,</span> <span class="identifier">value_type</span><span class="special">&</span> <span class="identifier">body</span><span class="special">);</span> 268 269 <span class="comment">/** Initialize the reader. 270 271 This is called after construction and before the first 272 call to `put`. The message is valid and complete upon 273 entry. 274 275 @param ec Set to the error, if any occurred. 276 */</span> 277 <span class="keyword">void</span> 278 <span class="identifier">init</span><span class="special">(</span> 279 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">content_length</span><span class="special">,</span> 280 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> 281 <span class="special">{</span> 282 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ignore_unused</span><span class="special">(</span><span class="identifier">content_length</span><span class="special">);</span> 283 284 <span class="comment">// The specification requires this to indicate "no error"</span> 285 <span class="identifier">ec</span> <span class="special">=</span> <span class="special">{};</span> 286 <span class="special">}</span> 287 288 <span class="comment">/** Store buffers. 289 290 This is called zero or more times with parsed body octets. 291 292 @param buffers The constant buffer sequence to store. 293 294 @param ec Set to the error, if any occurred. 295 296 @return The number of bytes transferred from the input buffers. 297 */</span> 298 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">ConstBufferSequence</span><span class="special">></span> 299 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> 300 <span class="identifier">put</span><span class="special">(</span><span class="identifier">ConstBufferSequence</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">buffers</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> 301 <span class="special">{</span> 302 <span class="comment">// The specification requires this to indicate "no error"</span> 303 <span class="identifier">ec</span> <span class="special">=</span> <span class="special">{};</span> 304 305 <span class="keyword">return</span> <span class="identifier">buffer_bytes</span><span class="special">(</span><span class="identifier">buffers</span><span class="special">);</span> 306 <span class="special">}</span> 307 308 <span class="comment">/** Called when the body is complete. 309 310 @param ec Set to the error, if any occurred. 311 */</span> 312 <span class="keyword">void</span> 313 <span class="identifier">finish</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> 314 <span class="special">{</span> 315 <span class="comment">// The specification requires this to indicate "no error"</span> 316 <span class="identifier">ec</span> <span class="special">=</span> <span class="special">{};</span> 317 <span class="special">}</span> 318<span class="special">};</span> 319</pre> 320<h5> 321<a name="beast.concepts.BodyReader.h3"></a> 322 <span class="phrase"><a name="beast.concepts.BodyReader.models"></a></span><a class="link" href="BodyReader.html#beast.concepts.BodyReader.models">Models</a> 323 </h5> 324<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 325<li class="listitem"> 326 <a class="link" href="../ref/boost__beast__http__basic_dynamic_body/reader.html" title="http::basic_dynamic_body::reader"><code class="computeroutput"><span class="identifier">basic_dynamic_body</span><span class="special">::</span><span class="identifier">reader</span></code></a> 327 </li> 328<li class="listitem"> 329 <a class="link" href="../ref/boost__beast__http__basic_file_body__reader.html" title="http::basic_file_body::reader"><code class="computeroutput"><span class="identifier">basic_file_body</span><span class="special">::</span><span class="identifier">reader</span></code></a> 330 </li> 331<li class="listitem"> 332 <a class="link" href="../ref/boost__beast__http__basic_string_body/reader.html" title="http::basic_string_body::reader"><code class="computeroutput"><span class="identifier">basic_string_body</span><span class="special">::</span><span class="identifier">reader</span></code></a> 333 </li> 334<li class="listitem"> 335 <a class="link" href="../ref/boost__beast__http__buffer_body/reader.html" title="http::buffer_body::reader"><code class="computeroutput"><span class="identifier">buffer_body</span><span class="special">::</span><span class="identifier">reader</span></code></a> 336 </li> 337<li class="listitem"> 338 <a class="link" href="../ref/boost__beast__http__empty_body/reader.html" title="http::empty_body::reader"><code class="computeroutput"><span class="identifier">empty_body</span><span class="special">::</span><span class="identifier">reader</span></code></a> 339 </li> 340<li class="listitem"> 341 <a class="link" href="../ref/boost__beast__http__span_body/reader.html" title="http::span_body::reader"><code class="computeroutput"><span class="identifier">span_body</span><span class="special">::</span><span class="identifier">reader</span></code></a> 342 </li> 343<li class="listitem"> 344 <a class="link" href="../ref/boost__beast__http__vector_body/reader.html" title="http::vector_body::reader"><code class="computeroutput"><span class="identifier">vector_body</span><span class="special">::</span><span class="identifier">reader</span></code></a> 345 </li> 346</ul></div> 347</div> 348<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 349<td align="left"></td> 350<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 351 Falco<p> 352 Distributed under the Boost Software License, Version 1.0. (See accompanying 353 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>) 354 </p> 355</div></td> 356</tr></table> 357<hr> 358<div class="spirit-nav"> 359<a accesskey="p" href="Body.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.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="BodyWriter.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 360</div> 361</body> 362</html> 363
