1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Protocol Primer</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="../using_http.html" title="HTTP"> 10<link rel="next" href="message_containers.html" title="Message Containers"> 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="../using_http.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="message_containers.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.protocol_primer"></a><a class="link" href="protocol_primer.html" title="Protocol Primer">Protocol Primer</a> 28</h3></div></div></div> 29<p> 30 The HTTP protocol defines the <a href="https://tools.ietf.org/html/rfc7230#section-2.1" target="_top">client 31 and server roles</a>: clients send requests and servers send back responses. 32 When a client and server have established a connection, the client sends 33 a series of requests while the server sends back at least one response for 34 each received request in the order those requests were received. 35 </p> 36<p> 37 A request or response is an <a href="https://tools.ietf.org/html/rfc7230#section-3" target="_top">HTTP 38 message</a> (referred to hereafter as "message") having two 39 parts: a header with structured metadata and an optional variable-length 40 body holding arbitrary data. A serialized header is one or more text lines 41 where each line ends in a carriage return followed by linefeed (<code class="computeroutput"><span class="string">"\r\n"</span></code>). An empty line marks the 42 end of the header. The first line in the header is called the <span class="emphasis"><em>start-line</em></span>. 43 The contents of the start line contents are different for requests and responses. 44 </p> 45<p> 46 Every message contains a set of zero or more field name/value pairs, collectively 47 called "fields". The names and values are represented using text 48 strings with various requirements. A serialized field contains the field 49 name, then a colon followed by a space (<code class="computeroutput"><span class="string">": 50 "</span></code>), and finally the field value with a trailing CRLF. 51 </p> 52<h5> 53<a name="beast.using_http.protocol_primer.h0"></a> 54 <span class="phrase"><a name="beast.using_http.protocol_primer.requests"></a></span><a class="link" href="protocol_primer.html#beast.using_http.protocol_primer.requests">Requests</a> 55 </h5> 56<p> 57 Clients send requests, which contain a <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1" target="_top">method</a> 58 and <a href="https://tools.ietf.org/html/rfc7230#section-5.3" target="_top">request-target</a>, 59 and <a href="https://tools.ietf.org/html/rfc7230#section-2.6" target="_top">HTTP-version</a>. 60 The method identifies the operation to be performed while the target identifies 61 the object on the server to which the operation applies. The version is almost 62 always 1.1, but older programs sometimes use 1.0. 63 </p> 64<div class="informaltable"><table class="table"> 65<colgroup> 66<col> 67<col> 68</colgroup> 69<thead><tr> 70<th> 71 <p> 72 Serialized Request 73 </p> 74 </th> 75<th> 76 <p> 77 Description 78 </p> 79 </th> 80</tr></thead> 81<tbody><tr> 82<td> 83<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">GET</span> <span class="special">/</span> <span class="identifier">HTTP</span><span class="special">/</span><span class="number">1.1</span><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span> 84<span class="identifier">User</span><span class="special">-</span><span class="identifier">Agent</span><span class="special">:</span> <span class="identifier">Beast</span><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span> 85<span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span> 86</pre> 87 </td> 88<td> 89 <p> 90 This request has a method of "GET", a target of "/", 91 and indicates HTTP version 1.1. It contains a single field called 92 "User-Agent" whose value is "Beast". There 93 is no message body. 94 </p> 95 </td> 96</tr></tbody> 97</table></div> 98<h5> 99<a name="beast.using_http.protocol_primer.h1"></a> 100 <span class="phrase"><a name="beast.using_http.protocol_primer.responses"></a></span><a class="link" href="protocol_primer.html#beast.using_http.protocol_primer.responses">Responses</a> 101 </h5> 102<p> 103 Servers send responses, which contain a <a href="https://tools.ietf.org/html/rfc7231#section-6" target="_top">status-code</a>, 104 <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2" target="_top">reason-phrase</a>, 105 and <a href="https://tools.ietf.org/html/rfc7230#section-2.6" target="_top">HTTP-version</a>. 106 The reason phrase is <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2" target="_top">obsolete</a>: 107 clients SHOULD ignore the reason-phrase content. Here is a response which 108 includes a body. The special <a href="https://tools.ietf.org/html/rfc7230#section-3.3.2" target="_top">Content-Length</a> 109 field informs the remote host of the size of the body which follows. 110 </p> 111<div class="informaltable"><table class="table"> 112<colgroup> 113<col> 114<col> 115</colgroup> 116<thead><tr> 117<th> 118 <p> 119 Serialized Response 120 </p> 121 </th> 122<th> 123 <p> 124 Description 125 </p> 126 </th> 127</tr></thead> 128<tbody><tr> 129<td> 130<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">HTTP</span><span class="special">/</span><span class="number">1.1</span> <span class="number">200</span> <span class="identifier">OK</span><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span> 131<span class="identifier">Server</span><span class="special">:</span> <span class="identifier">Beast</span><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span> 132<span class="identifier">Content</span><span class="special">-</span><span class="identifier">Length</span><span class="special">:</span> <span class="number">13</span><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span> 133<span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span> 134<span class="identifier">Hello</span><span class="special">,</span> <span class="identifier">world</span><span class="special">!</span> 135</pre> 136 </td> 137<td> 138 <p> 139 This response has a <a href="https://tools.ietf.org/html/rfc7231#section-6" target="_top">200 140 status code</a> meaning the operation requested completed successfully. 141 The obsolete reason phrase is "OK". It specifies HTTP 142 version 1.1, and contains a body 13 octets in size with the text 143 "Hello, world!". 144 </p> 145 </td> 146</tr></tbody> 147</table></div> 148<h5> 149<a name="beast.using_http.protocol_primer.h2"></a> 150 <span class="phrase"><a name="beast.using_http.protocol_primer.body"></a></span><a class="link" href="protocol_primer.html#beast.using_http.protocol_primer.body">Body</a> 151 </h5> 152<p> 153 Messages may optionally carry a body. The size of the message body is determined 154 by the semantics of the message and the special fields Content-Length and 155 Transfer-Encoding. <a href="https://tools.ietf.org/html/rfc7230#section-3.3" target="_top">rfc7230 156 section 3.3</a> provides a comprehensive description for how the body 157 length is determined. 158 </p> 159<h5> 160<a name="beast.using_http.protocol_primer.h3"></a> 161 <span class="phrase"><a name="beast.using_http.protocol_primer.special_fields"></a></span><a class="link" href="protocol_primer.html#beast.using_http.protocol_primer.special_fields">Special 162 Fields</a> 163 </h5> 164<p> 165 Certain fields appearing in messages are special. The library understands 166 these fields when performing serialization and parsing, taking automatic 167 action as needed when the fields are parsed in a message and also setting 168 the fields if the caller requests it. 169 </p> 170<div class="table"> 171<a name="beast.using_http.protocol_primer.special_fields0"></a><p class="title"><b>Table 1.14. Special Fields</b></p> 172<div class="table-contents"><table class="table" summary="Special Fields"> 173<colgroup> 174<col> 175<col> 176</colgroup> 177<thead><tr> 178<th> 179 <p> 180 Field 181 </p> 182 </th> 183<th> 184 <p> 185 Description 186 </p> 187 </th> 188</tr></thead> 189<tbody> 190<tr> 191<td> 192 <p> 193 <a href="https://tools.ietf.org/html/rfc7230#section-6.1" target="_top"><span class="bold"><strong><code class="computeroutput"><span class="identifier">Connection</span></code></strong></span></a> 194 </p> 195 <p> 196 <a href="https://tools.ietf.org/html/rfc7230#appendix-A.1.2" target="_top"><span class="bold"><strong><code class="computeroutput"><span class="identifier">Proxy</span><span class="special">-</span><span class="identifier">Connection</span></code></strong></span></a> 197 </p> 198 </td> 199<td> 200 <p> 201 This field allows the sender to indicate desired control options 202 for the current connection. Common values include "close", 203 "keep-alive", and "upgrade". 204 </p> 205 </td> 206</tr> 207<tr> 208<td> 209 <p> 210 <a href="https://tools.ietf.org/html/rfc7230#section-3.3.2" target="_top"><span class="bold"><strong><code class="computeroutput"><span class="identifier">Content</span><span class="special">-</span><span class="identifier">Length</span></code></strong></span></a> 211 </p> 212 </td> 213<td> 214 <p> 215 When present, this field informs the recipient about the exact 216 size in bytes of the body which follows the message header. 217 </p> 218 </td> 219</tr> 220<tr> 221<td> 222 <p> 223 <a href="https://tools.ietf.org/html/rfc7230#section-3.3.1" target="_top"><span class="bold"><strong><code class="computeroutput"><span class="identifier">Transfer</span><span class="special">-</span><span class="identifier">Encoding</span></code></strong></span></a> 224 </p> 225 </td> 226<td> 227 <p> 228 This optional field lists the names of the sequence of transfer 229 codings that have been (or will be) applied to the content payload 230 to form the message body. 231 </p> 232 <p> 233 Beast understands the "chunked" coding scheme when it 234 is the last (outermost) applied coding. The library will automatically 235 apply chunked encoding when the content length is not known ahead 236 of time during serialization, and the library will automatically 237 remove chunked encoding from parsed messages when present. 238 </p> 239 </td> 240</tr> 241<tr> 242<td> 243 <p> 244 <a href="https://tools.ietf.org/html/rfc7230#section-6.7" target="_top"><span class="bold"><strong><code class="computeroutput"><span class="identifier">Upgrade</span></code></strong></span></a> 245 </p> 246 </td> 247<td> 248 <p> 249 The Upgrade header field provides a mechanism to transition from 250 HTTP/1.1 to another protocol on the same connection. For example, 251 it is the mechanism used by WebSocket's initial HTTP handshake 252 to establish a WebSocket connection. 253 </p> 254 </td> 255</tr> 256</tbody> 257</table></div> 258</div> 259<br class="table-break"> 260</div> 261<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 262<td align="left"></td> 263<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 264 Falco<p> 265 Distributed under the Boost Software License, Version 1.0. (See accompanying 266 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>) 267 </p> 268</div></td> 269</tr></table> 270<hr> 271<div class="spirit-nav"> 272<a accesskey="p" href="../using_http.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="message_containers.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 273</div> 274</body> 275</html> 276
