1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>BodyWriter</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="BodyReader.html" title="BodyReader"> 10<link rel="next" href="BufferSequence.html" title="BufferSequence"> 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="BodyReader.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="BufferSequence.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.BodyWriter"></a><a class="link" href="BodyWriter.html" title="BodyWriter">BodyWriter</a> 28</h3></div></div></div> 29<p> 30 A <span class="bold"><strong>BodyWriter</strong></span> provides an <a href="https://en.wikipedia.org/wiki/Online_algorithm" target="_top">online 31 algorithm</a> to obtain a sequence of zero or more buffers from a body 32 during serialization. The implementation creates an instance of this type 33 when needed, and calls into it one or more times to retrieve buffers holding 34 body octets. The interface of <span class="bold"><strong>BodyWriter</strong></span> 35 is intended to obtain buffers for these scenarios: 36 </p> 37<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 38<li class="listitem"> 39 A body that does not entirely fit in memory. 40 </li> 41<li class="listitem"> 42 A body produced incrementally from coroutine output. 43 </li> 44<li class="listitem"> 45 A body represented by zero or more buffers already in memory. 46 </li> 47<li class="listitem"> 48 A body whose size is not known ahead of time. 49 </li> 50<li class="listitem"> 51 Body data generated dynamically from other threads. 52 </li> 53<li class="listitem"> 54 Body data computed algorithmically. 55 </li> 56</ul></div> 57<h5> 58<a name="beast.concepts.BodyWriter.h0"></a> 59 <span class="phrase"><a name="beast.concepts.BodyWriter.associated_types"></a></span><a class="link" href="BodyWriter.html#beast.concepts.BodyWriter.associated_types">Associated 60 Types</a> 61 </h5> 62<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 63<li class="listitem"> 64 <a class="link" href="../ref/boost__beast__http__is_body_writer.html" title="http::is_body_writer"><code class="computeroutput"><span class="identifier">is_body_writer</span></code></a> 65 </li> 66<li class="listitem"> 67 <a class="link" href="Body.html" title="Body"><span class="emphasis"><em>Body</em></span></a> 68 </li> 69</ul></div> 70<h5> 71<a name="beast.concepts.BodyWriter.h1"></a> 72 <span class="phrase"><a name="beast.concepts.BodyWriter.requirements"></a></span><a class="link" href="BodyWriter.html#beast.concepts.BodyWriter.requirements">Requirements</a> 73 </h5> 74<div class="warning"><table border="0" summary="Warning"> 75<tr> 76<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td> 77<th align="left">Warning</th> 78</tr> 79<tr><td align="left" valign="top"><p> 80 These requirements may undergo non-backward compatible changes in subsequent 81 versions. 82 </p></td></tr> 83</table></div> 84<p> 85 In this table: 86 </p> 87<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 88<li class="listitem"> 89 <code class="computeroutput"><span class="identifier">W</span></code> denotes a type meeting 90 the requirements of <span class="bold"><strong>BodyWriter</strong></span>. 91 </li> 92<li class="listitem"> 93 <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> 94 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">W</span><span class="special">,</span> <span class="identifier">B</span><span class="special">::</span><span class="identifier">writer</span><span class="special">>::</span><span class="identifier">value</span> <span class="special">==</span> 95 <span class="keyword">true</span></code>. 96 </li> 97<li class="listitem"> 98 <code class="computeroutput"><span class="identifier">a</span></code> denotes a value of 99 type <code class="computeroutput"><span class="identifier">W</span></code>. 100 </li> 101<li class="listitem"> 102 <code class="computeroutput"><span class="identifier">h</span></code> denotes a const value 103 of type <code class="computeroutput"><span class="identifier">header</span><span class="special"><</span><span class="identifier">isRequest</span><span class="special">,</span> 104 <span class="identifier">Fields</span><span class="special">></span> 105 <span class="keyword">const</span><span class="special">&</span></code>. 106 </li> 107<li class="listitem"> 108 <code class="computeroutput"><span class="identifier">v</span></code> denotes a possibly 109 const value of type <code class="computeroutput"><span class="identifier">Body</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">&</span></code>. 110 </li> 111<li class="listitem"> 112 <code class="computeroutput"><span class="identifier">ec</span></code> is a value of type 113 <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>. 114 </li> 115<li class="listitem"> 116 <code class="computeroutput"><span class="identifier">W</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> 117 is the type <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">pair</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">>></span></code>. 118 </li> 119</ul></div> 120<div class="table"> 121<a name="beast.concepts.BodyWriter.valid_expressions"></a><p class="title"><b>Table 1.39. Valid expressions</b></p> 122<div class="table-contents"><table class="table" summary="Valid expressions"> 123<colgroup> 124<col> 125<col> 126<col> 127</colgroup> 128<thead><tr> 129<th> 130 <p> 131 Expression 132 </p> 133 </th> 134<th> 135 <p> 136 Type 137 </p> 138 </th> 139<th> 140 <p> 141 Semantics, Pre/Post-conditions 142 </p> 143 </th> 144</tr></thead> 145<tbody> 146<tr> 147<td> 148 <p> 149 <code class="computeroutput"><span class="identifier">W</span><span class="special">::</span><span class="identifier">const_buffers_type</span></code> 150 </p> 151 </td> 152<td> 153 </td> 154<td> 155 <p> 156 A type which meets the requirements of <a href="../../../../../../doc/html/boost_asio/reference/ConstBufferSequence.html" target="_top"><span class="emphasis"><em>ConstBufferSequence</em></span></a>. 157 This is the type of buffer returned by <code class="computeroutput"><span class="identifier">W</span><span class="special">::</span><span class="identifier">get</span></code>. 158 </p> 159 </td> 160</tr> 161<tr> 162<td> 163 <p> 164 <code class="computeroutput"><span class="identifier">W</span><span class="special">{</span><span class="identifier">h</span><span class="special">,</span><span class="identifier">v</span><span class="special">};</span></code> 165 </p> 166 </td> 167<td> 168 </td> 169<td> 170 <p> 171 Constructible from <code class="computeroutput"><span class="identifier">h</span></code> 172 and <code class="computeroutput"><span class="identifier">v</span></code>. The lifetime 173 of <code class="computeroutput"><span class="identifier">h</span></code> and <code class="computeroutput"><span class="identifier">v</span></code> are guaranteed to end no earlier 174 than after the <code class="computeroutput"><span class="identifier">W</span></code> 175 is destroyed. The writer 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> 176 before the first call to <code class="computeroutput"><span class="identifier">init</span></code>, 177 permitting lazy construction of the message. 178 </p> 179 <p> 180 The constructor may optionally require that <code class="computeroutput"><span class="identifier">h</span></code> 181 and <code class="computeroutput"><span class="identifier">v</span></code> are <code class="computeroutput"><span class="keyword">const</span></code> references, with these consequences: 182 </p> 183 <p> 184 * If <code class="computeroutput"><span class="identifier">W</span></code> requires 185 that <code class="computeroutput"><span class="identifier">h</span></code> and <code class="computeroutput"><span class="identifier">v</span></code> are const references, then 186 the corresponding serializer constructors for messages with this 187 body type will will accept a const reference to a message, otherwise: 188 </p> 189 <p> 190 * If <code class="computeroutput"><span class="identifier">W</span></code> requires 191 that <code class="computeroutput"><span class="identifier">h</span></code> and <code class="computeroutput"><span class="identifier">v</span></code> are non-const references, then 192 the corresponding serializer constructors for messages with this 193 body type will require a non-const reference to a message. 194 </p> 195 </td> 196</tr> 197<tr> 198<td> 199 <p> 200 <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">init</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span></code> 201 </p> 202 </td> 203<td> 204 </td> 205<td> 206 <p> 207 Called once to fully initialize the object before any calls to 208 <code class="computeroutput"><span class="identifier">get</span></code>. The message 209 body becomes valid before entering this function, and remains valid 210 until the writer is destroyed. The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> 211 is <code class="computeroutput"><span class="keyword">true</span></code> if there was 212 no error or set to the appropriate error code if there was one. 213 </p> 214 </td> 215</tr> 216<tr> 217<td> 218 <p> 219 <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">get</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span></code> 220 </p> 221 </td> 222<td> 223 <p> 224 <code class="computeroutput"><span class="identifier">W</span><span class="special"><</span><span class="identifier">W</span><span class="special">::</span><span class="identifier">const_buffers_type</span><span class="special">></span></code> 225 </p> 226 </td> 227<td> 228 <p> 229 Called one or more times after <code class="computeroutput"><span class="identifier">init</span></code> 230 succeeds. This function returns <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span></code> 231 if all buffers representing the body have been returned in previous 232 calls or if it sets <code class="computeroutput"><span class="identifier">ec</span></code> 233 to indicate an error. Otherwise, if there are buffers remaining 234 the function should return a pair with the first element containing 235 a non-zero length buffer sequence representing the next set of 236 octets in the body, while the second element is a <code class="computeroutput"><span class="keyword">bool</span></code> meaning <code class="computeroutput"><span class="keyword">true</span></code> 237 if there may be additional buffers returned on a subsequent call, 238 or <code class="computeroutput"><span class="keyword">false</span></code> if the buffer 239 returned on this call is the last buffer representing the body. 240 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> 241 if there was no error or set to the appropriate error code if there 242 was one. 243 </p> 244 </td> 245</tr> 246</tbody> 247</table></div> 248</div> 249<br class="table-break"><h5> 250<a name="beast.concepts.BodyWriter.h2"></a> 251 <span class="phrase"><a name="beast.concepts.BodyWriter.exemplar"></a></span><a class="link" href="BodyWriter.html#beast.concepts.BodyWriter.exemplar">Exemplar</a> 252 </h5> 253<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">BodyWriter</span> 254<span class="special">{</span> 255<span class="keyword">public</span><span class="special">:</span> 256 <span class="comment">/// The type of buffer returned by `get`.</span> 257 <span class="keyword">using</span> <span class="identifier">const_buffers_type</span> <span class="special">=</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">const_buffer</span><span class="special">;</span> 258 259 <span class="comment">/** Construct the writer. 260 261 @param h The header for the message being serialized 262 263 @param body The body being serialized 264 */</span> 265 <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> 266 <span class="identifier">BodyWriter</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="keyword">const</span><span class="special">&</span> <span class="identifier">h</span><span class="special">,</span> <span class="identifier">value_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">body</span><span class="special">);</span> 267 268 <span class="comment">/** Initialize the writer. 269 270 This is called after construction and before the first 271 call to `get`. The message is valid and complete upon 272 entry. 273 274 @param ec Set to the error, if any occurred. 275 */</span> 276 <span class="keyword">void</span> 277 <span class="identifier">init</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> 278 <span class="special">{</span> 279 <span class="comment">// The specification requires this to indicate "no error"</span> 280 <span class="identifier">ec</span> <span class="special">=</span> <span class="special">{};</span> 281 <span class="special">}</span> 282 283 <span class="comment">/** Returns the next buffer in the body. 284 285 @li If the return value is `boost::none` (unseated optional) and 286 `ec` does not contain an error, this indicates the end of the 287 body, no more buffers are present. 288 289 @li If the optional contains a value, the first element of the 290 pair represents a <em>ConstBufferSequence</em> containing one or 291 more octets of the body data. The second element indicates 292 whether or not there are additional octets of body data. 293 A value of `true` means there is more data, and that the 294 implementation will perform a subsequent call to `get`. 295 A value of `false` means there is no more body data. 296 297 @li If `ec` contains an error code, the return value is ignored. 298 299 @param ec Set to the error, if any occurred. 300 */</span> 301 <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">pair</span><span class="special"><</span><span class="identifier">const_buffers_type</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">>></span> 302 <span class="identifier">get</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> 303 <span class="special">{</span> 304 <span class="comment">// The specification requires this to indicate "no error"</span> 305 <span class="identifier">ec</span> <span class="special">=</span> <span class="special">{};</span> 306 307 <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span><span class="special">;</span> <span class="comment">// for exposition only</span> 308 <span class="special">}</span> 309<span class="special">};</span> 310</pre> 311<h5> 312<a name="beast.concepts.BodyWriter.h3"></a> 313 <span class="phrase"><a name="beast.concepts.BodyWriter.models"></a></span><a class="link" href="BodyWriter.html#beast.concepts.BodyWriter.models">Models</a> 314 </h5> 315<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 316<li class="listitem"> 317 <a class="link" href="../ref/boost__beast__http__basic_dynamic_body/writer.html" title="http::basic_dynamic_body::writer"><code class="computeroutput"><span class="identifier">basic_dynamic_body</span><span class="special">::</span><span class="identifier">writer</span></code></a> 318 </li> 319<li class="listitem"> 320 <a class="link" href="../ref/boost__beast__http__basic_file_body__writer.html" title="http::basic_file_body::writer"><code class="computeroutput"><span class="identifier">basic_file_body</span><span class="special">::</span><span class="identifier">writer</span></code></a> 321 </li> 322<li class="listitem"> 323 <a class="link" href="../ref/boost__beast__http__basic_string_body/writer.html" title="http::basic_string_body::writer"><code class="computeroutput"><span class="identifier">basic_string_body</span><span class="special">::</span><span class="identifier">writer</span></code></a> 324 </li> 325<li class="listitem"> 326 <a class="link" href="../ref/boost__beast__http__buffer_body/writer.html" title="http::buffer_body::writer"><code class="computeroutput"><span class="identifier">buffer_body</span><span class="special">::</span><span class="identifier">writer</span></code></a> 327 </li> 328<li class="listitem"> 329 <a class="link" href="../ref/boost__beast__http__empty_body/writer.html" title="http::empty_body::writer"><code class="computeroutput"><span class="identifier">empty_body</span><span class="special">::</span><span class="identifier">writer</span></code></a> 330 </li> 331<li class="listitem"> 332 <a class="link" href="../ref/boost__beast__http__span_body/writer.html" title="http::span_body::writer"><code class="computeroutput"><span class="identifier">span_body</span><span class="special">::</span><span class="identifier">writer</span></code></a> 333 </li> 334<li class="listitem"> 335 <a class="link" href="../ref/boost__beast__http__vector_body/writer.html" title="http::vector_body::writer"><code class="computeroutput"><span class="identifier">vector_body</span><span class="special">::</span><span class="identifier">writer</span></code></a> 336 </li> 337</ul></div> 338</div> 339<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 340<td align="left"></td> 341<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 342 Falco<p> 343 Distributed under the Boost Software License, Version 1.0. (See accompanying 344 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>) 345 </p> 346</div></td> 347</tr></table> 348<hr> 349<div class="spirit-nav"> 350<a accesskey="p" href="BodyReader.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="BufferSequence.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 351</div> 352</body> 353</html> 354
