1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Custom Parsers</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="custom_body_types.html" title="Custom Body Types"> 10<link rel="next" href="../more_examples.html" title="HTTP Examples"> 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="custom_body_types.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="../more_examples.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.custom_parsers"></a><a class="link" href="custom_parsers.html" title="Custom Parsers">Custom Parsers</a> 28</h3></div></div></div> 29<p> 30 While the parsers included in the library will handle a broad number of use-cases, 31 the <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> interface can be subclassed 32 to implement custom strategies for storing parsed results: the basic parser 33 processes input buffers into elements according to the HTTP/1 protocol specification, 34 while the derived class decides what to do with those elements. Custom parsers 35 will work with all of the HTTP stream read algorithms, as those algorithms 36 use only the basic parser interface. Some use cases for implementing custom 37 parsers are: 38 </p> 39<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 40<li class="listitem"> 41 Inspect incoming header fields and keep or discard them. 42 </li> 43<li class="listitem"> 44 Use a container provided by an external interface. 45 </li> 46</ul></div> 47<p> 48 The basic parser uses virtual functions. To declare your user-defined parser, 49 derive from <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> and implement all the 50 required virtual functions. A declaration for the derived class may look 51 like this: 52 </p> 53<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">bool</span> <span class="identifier">isRequest</span><span class="special">></span> 54<span class="keyword">class</span> <span class="identifier">custom_parser</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">basic_parser</span><span class="special"><</span><span class="identifier">isRequest</span><span class="special">></span> 55<span class="special">{</span> 56<span class="keyword">private</span><span class="special">:</span> 57 <span class="comment">/** Called after receiving the request-line. 58 59 This virtual function is invoked after receiving a request-line 60 when parsing HTTP requests. 61 It can only be called when `isRequest == true`. 62 63 @param method The verb enumeration. If the method string is not 64 one of the predefined strings, this value will be @ref verb::unknown. 65 66 @param method_str The unmodified string representing the verb. 67 68 @param target The request-target. 69 70 @param version The HTTP-version. This will be 10 for HTTP/1.0, 71 and 11 for HTTP/1.1. 72 73 @param ec An output parameter which the function may set to indicate 74 an error. The error will be clear before this function is invoked. 75 */</span> 76 <span class="keyword">void</span> 77 <span class="identifier">on_request_impl</span><span class="special">(</span> 78 <span class="identifier">verb</span> <span class="identifier">method</span><span class="special">,</span> <span class="comment">// The method verb, verb::unknown if no match</span> 79 <span class="identifier">string_view</span> <span class="identifier">method_str</span><span class="special">,</span> <span class="comment">// The method as a string</span> 80 <span class="identifier">string_view</span> <span class="identifier">target</span><span class="special">,</span> <span class="comment">// The request-target</span> 81 <span class="keyword">int</span> <span class="identifier">version</span><span class="special">,</span> <span class="comment">// The HTTP-version</span> 82 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 83 84 <span class="comment">/** Called after receiving the status-line. 85 86 This virtual function is invoked after receiving a status-line 87 when parsing HTTP responses. 88 It can only be called when `isRequest == false`. 89 90 @param code The numeric status code. 91 92 @param reason The reason-phrase. Note that this value is 93 now obsolete, and only provided for historical or diagnostic 94 purposes. 95 96 @param version The HTTP-version. This will be 10 for HTTP/1.0, 97 and 11 for HTTP/1.1. 98 99 @param ec An output parameter which the function may set to indicate 100 an error. The error will be clear before this function is invoked. 101 */</span> 102 <span class="keyword">void</span> 103 <span class="identifier">on_response_impl</span><span class="special">(</span> 104 <span class="keyword">int</span> <span class="identifier">code</span><span class="special">,</span> <span class="comment">// The status-code</span> 105 <span class="identifier">string_view</span> <span class="identifier">reason</span><span class="special">,</span> <span class="comment">// The obsolete reason-phrase</span> 106 <span class="keyword">int</span> <span class="identifier">version</span><span class="special">,</span> <span class="comment">// The HTTP-version</span> 107 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 108 109 <span class="comment">/** Called once for each complete field in the HTTP header. 110 111 This virtual function is invoked for each field that is received 112 while parsing an HTTP message. 113 114 @param name The known field enum value. If the name of the field 115 is not recognized, this value will be @ref field::unknown. 116 117 @param name_string The exact name of the field as received from 118 the input, represented as a string. 119 120 @param value A string holding the value of the field. 121 122 @param ec An output parameter which the function may set to indicate 123 an error. The error will be clear before this function is invoked. 124 */</span> 125 <span class="keyword">void</span> 126 <span class="identifier">on_field_impl</span><span class="special">(</span> 127 <span class="identifier">field</span> <span class="identifier">f</span><span class="special">,</span> <span class="comment">// The known-field enumeration constant</span> 128 <span class="identifier">string_view</span> <span class="identifier">name</span><span class="special">,</span> <span class="comment">// The field name string.</span> 129 <span class="identifier">string_view</span> <span class="identifier">value</span><span class="special">,</span> <span class="comment">// The field value</span> 130 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 131 132 <span class="comment">/** Called once after the complete HTTP header is received. 133 134 This virtual function is invoked once, after the complete HTTP 135 header is received while parsing a message. 136 137 @param ec An output parameter which the function may set to indicate 138 an error. The error will be clear before this function is invoked. 139 */</span> 140 <span class="keyword">void</span> 141 <span class="identifier">on_header_impl</span><span class="special">(</span> 142 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 143 144 <span class="comment">/** Called once before the body is processed. 145 146 This virtual function is invoked once, before the content body is 147 processed (but after the complete header is received). 148 149 @param content_length A value representing the content length in 150 bytes if the length is known (this can include a zero length). 151 Otherwise, the value will be `boost::none`. 152 153 @param ec An output parameter which the function may set to indicate 154 an error. The error will be clear before this function is invoked. 155 */</span> 156 <span class="keyword">void</span> 157 <span class="identifier">on_body_init_impl</span><span class="special">(</span> 158 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span> 159 <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> 160 <span class="identifier">content_length</span><span class="special">,</span> <span class="comment">// Content length if known, else `boost::none`</span> 161 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 162 163 <span class="comment">/** Called each time additional data is received representing the content body. 164 165 This virtual function is invoked for each piece of the body which is 166 received while parsing of a message. This function is only used when 167 no chunked transfer encoding is present. 168 169 @param body A string holding the additional body contents. This may 170 contain nulls or unprintable characters. 171 172 @param ec An output parameter which the function may set to indicate 173 an error. The error will be clear before this function is invoked. 174 175 @see on_chunk_body_impl 176 */</span> 177 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> 178 <span class="identifier">on_body_impl</span><span class="special">(</span> 179 <span class="identifier">string_view</span> <span class="identifier">s</span><span class="special">,</span> <span class="comment">// A portion of the body</span> 180 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 181 182 <span class="comment">/** Called each time a new chunk header of a chunk encoded body is received. 183 184 This function is invoked each time a new chunk header is received. 185 The function is only used when the chunked transfer encoding is present. 186 187 @param size The size of this chunk, in bytes. 188 189 @param extensions A string containing the entire chunk extensions. 190 This may be empty, indicating no extensions are present. 191 192 @param ec An output parameter which the function may set to indicate 193 an error. The error will be clear before this function is invoked. 194 */</span> 195 <span class="keyword">void</span> 196 <span class="identifier">on_chunk_header_impl</span><span class="special">(</span> 197 <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span> <span class="identifier">size</span><span class="special">,</span> <span class="comment">// The size of the upcoming chunk,</span> 198 <span class="comment">// or zero for the last chunk</span> 199 <span class="identifier">string_view</span> <span class="identifier">extension</span><span class="special">,</span> <span class="comment">// The chunk extensions (may be empty)</span> 200 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 201 202 <span class="comment">/** Called each time additional data is received representing part of a body chunk. 203 204 This virtual function is invoked for each piece of the body which is 205 received while parsing of a message. This function is only used when 206 no chunked transfer encoding is present. 207 208 @param remain The number of bytes remaining in this chunk. This includes 209 the contents of passed `body`. If this value is zero, then this represents 210 the final chunk. 211 212 @param body A string holding the additional body contents. This may 213 contain nulls or unprintable characters. 214 215 @param ec An output parameter which the function may set to indicate 216 an error. The error will be clear before this function is invoked. 217 218 @return This function should return the number of bytes actually consumed 219 from the `body` value. Any bytes that are not consumed on this call 220 will be presented in a subsequent call. 221 222 @see on_body_impl 223 */</span> 224 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> 225 <span class="identifier">on_chunk_body_impl</span><span class="special">(</span> 226 <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span> <span class="identifier">remain</span><span class="special">,</span> <span class="comment">// The number of bytes remaining in the chunk,</span> 227 <span class="comment">// including what is being passed here.</span> 228 <span class="comment">// or zero for the last chunk</span> 229 <span class="identifier">string_view</span> <span class="identifier">body</span><span class="special">,</span> <span class="comment">// The next piece of the chunk body</span> 230 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 231 232 <span class="comment">/** Called once when the complete message is received. 233 234 This virtual function is invoked once, after successfully parsing 235 a complete HTTP message. 236 237 @param ec An output parameter which the function may set to indicate 238 an error. The error will be clear before this function is invoked. 239 */</span> 240 <span class="keyword">void</span> 241 <span class="identifier">on_finish_impl</span><span class="special">(</span> 242 <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span> <span class="comment">// The error returned to the caller, if any</span> 243 244<span class="keyword">public</span><span class="special">:</span> 245 <span class="identifier">custom_parser</span><span class="special">()</span> <span class="special">=</span> <span class="keyword">default</span><span class="special">;</span> 246<span class="special">};</span> 247</pre> 248</div> 249<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 250<td align="left"></td> 251<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 252 Falco<p> 253 Distributed under the Boost Software License, Version 1.0. (See accompanying 254 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>) 255 </p> 256</div></td> 257</tr></table> 258<hr> 259<div class="spirit-nav"> 260<a accesskey="p" href="custom_body_types.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="../more_examples.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 261</div> 262</body> 263</html> 264
