1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>WebSocket</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="../index.html" title="Chapter 1. Boost.Beast"> 9<link rel="prev" href="more_examples/send_child_process_output.html" title="Send Child Process Output ��"> 10<link rel="next" href="using_websocket/establishing_connections.html" title="Connecting"> 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="more_examples/send_child_process_output.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="using_websocket/establishing_connections.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="beast.using_websocket"></a><a class="link" href="using_websocket.html" title="WebSocket">WebSocket</a> 28</h2></div></div></div> 29<p> 30 The WebSocket Protocol enables two-way communication between a client running 31 untrusted code in a controlled environment to a remote host that has opted-in 32 to communications from that code. The protocol consists of an opening handshake 33 followed by basic message framing, layered over TCP. The goal of this technology 34 is to provide a mechanism for browser-based applications needing two-way communication 35 with servers without relying on opening multiple HTTP connections. 36 </p> 37<p> 38 Beast provides developers with a robust WebSocket implementation built on Boost.Asio 39 with a consistent asynchronous model using a modern C++ approach. 40 </p> 41<div class="note"><table border="0" summary="Note"> 42<tr> 43<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 44<th align="left">Note</th> 45</tr> 46<tr><td align="left" valign="top"> 47<p> 48 This documentation assumes familiarity with <a href="../../../../../libs/asio/index.html" target="_top">Boost.Asio</a> 49 and the protocol specification described in <a href="https://tools.ietf.org/html/rfc6455" target="_top">rfc6455</a>. 50 Sample code and identifiers appearing in this section is written as if these 51 declarations are in effect: 52 </p> 53<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">beast</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 54<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">beast</span><span class="special">/</span><span class="identifier">ssl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 55<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 56<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">/</span><span class="identifier">ssl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 57</pre> 58<p> 59 60 </p> 61<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">net</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">;</span> 62<span class="keyword">namespace</span> <span class="identifier">beast</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">;</span> 63<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">;</span> 64<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">::</span><span class="identifier">websocket</span><span class="special">;</span> 65 66<span class="identifier">net</span><span class="special">::</span><span class="identifier">io_context</span> <span class="identifier">ioc</span><span class="special">;</span> 67<span class="identifier">tcp_stream</span> <span class="identifier">sock</span><span class="special">(</span><span class="identifier">ioc</span><span class="special">);</span> 68<span class="identifier">net</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span> <span class="identifier">ctx</span><span class="special">(</span><span class="identifier">net</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">tlsv12</span><span class="special">);</span> 69</pre> 70</td></tr> 71</table></div> 72<h4> 73<a name="beast.using_websocket.h0"></a> 74 <span class="phrase"><a name="beast.using_websocket.construction"></a></span><a class="link" href="using_websocket.html#beast.using_websocket.construction">Construction</a> 75 </h4> 76<p> 77 A WebSocket connection requires a stateful object, represented in Beast by 78 a single class template <a class="link" href="ref/boost__beast__websocket__stream.html" title="websocket::stream"><code class="computeroutput"><span class="identifier">websocket</span><span class="special">::</span><span class="identifier">stream</span></code></a>. The interface uses the layered 79 stream model. A websocket stream object contains another stream object, called 80 the "next layer", which it uses to perform I/O. Descriptions of each 81 template parameter follow: 82 </p> 83<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 84<span class="keyword">namespace</span> <span class="identifier">beast</span> <span class="special">{</span> 85<span class="keyword">namespace</span> <span class="identifier">websocket</span> <span class="special">{</span> 86 87<span class="keyword">template</span><span class="special"><</span> 88 <span class="keyword">class</span> <span class="identifier">NextLayer</span><span class="special">,</span> 89 <span class="keyword">bool</span> <span class="identifier">deflateSupported</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">></span> 90<span class="keyword">class</span> <span class="identifier">stream</span><span class="special">;</span> 91 92<span class="special">}</span> <span class="comment">// websocket</span> 93<span class="special">}</span> <span class="comment">// beast</span> 94<span class="special">}</span> <span class="comment">// boost</span> 95</pre> 96<div class="table"> 97<a name="beast.using_websocket.websocket_stream_template_parame"></a><p class="title"><b>Table 1.29. WebSocket Stream Template Parameters</b></p> 98<div class="table-contents"><table class="table" summary="WebSocket Stream Template Parameters"> 99<colgroup> 100<col> 101<col> 102</colgroup> 103<thead><tr> 104<th> 105 <p> 106 Name 107 </p> 108 </th> 109<th> 110 <p> 111 Description 112 </p> 113 </th> 114</tr></thead> 115<tbody> 116<tr> 117<td> 118 <p> 119 <code class="computeroutput"><span class="identifier">NextLayer</span></code> 120 </p> 121 </td> 122<td> 123 <p> 124 The type of the next layer. An object of this type will be constructed 125 and maintained for the lifetime of the stream. All reads and writes 126 will go through the next layer. This type must meet the requirements 127 of either <a class="link" href="concepts/streams.html#beast.concepts.streams.SyncStream"><span class="emphasis"><em>SyncStream</em></span></a>, 128 <a class="link" href="concepts/streams.html#beast.concepts.streams.AsyncStream"><span class="emphasis"><em>AsyncStream</em></span></a>, 129 or both, depending on the style of I/O that is to be performed. 130 </p> 131 </td> 132</tr> 133<tr> 134<td> 135 <p> 136 <code class="computeroutput"><span class="identifier">deflateSupported</span></code> 137 </p> 138 </td> 139<td> 140 <p> 141 When this value is <code class="computeroutput"><span class="keyword">true</span></code>, 142 the stream will support (but not require) the <a href="https://tools.ietf.org/html/rfc7692" target="_top">permessage-deflate 143 extension</a>. Whether or not the stream actually requests or 144 accepts the extension during a handshake depends on a separate configurable 145 option. 146 </p> 147 <p> 148 When the value is <code class="computeroutput"><span class="keyword">false</span></code> 149 the extension is disabled. Streams will never request the extension 150 in the client role or accept a request for the extension in the server 151 role. An additional benefit of disabling the extension is that compilation 152 will be faster, and the resulting program executable will contain 153 less code. 154 </p> 155 </td> 156</tr> 157</tbody> 158</table></div> 159</div> 160<br class="table-break"><p> 161 When a stream is constructed, any arguments provided to the constructor are 162 forwarded to the next layer object's constructor. This declares a stream over 163 a plain TCP/IP socket using an I/O context: 164 </p> 165<pre class="programlisting"><span class="comment">// This newly constructed WebSocket stream will use the specified</span> 166<span class="comment">// I/O context and have support for the permessage-deflate extension.</span> 167 168<span class="identifier">stream</span><span class="special"><</span><span class="identifier">tcp_stream</span><span class="special">></span> <span class="identifier">ws</span><span class="special">(</span><span class="identifier">ioc</span><span class="special">);</span> 169</pre> 170<div class="tip"><table border="0" summary="Tip"> 171<tr> 172<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../doc/src/images/tip.png"></td> 173<th align="left">Tip</th> 174</tr> 175<tr><td align="left" valign="top"><p> 176 Websocket streams use their own protocol-specific timeout feature. When using 177 a websocket stream with the <a class="link" href="ref/boost__beast__tcp_stream.html" title="tcp_stream"><code class="computeroutput"><span class="identifier">tcp_stream</span></code></a> or <a class="link" href="ref/boost__beast__basic_stream.html" title="basic_stream"><code class="computeroutput"><span class="identifier">basic_stream</span></code></a> class template, timeouts 178 should be disabled on the TCP or basic stream after the connection is established, 179 otherwise the behavior of the stream is undefined. 180 </p></td></tr> 181</table></div> 182<p> 183 As with most I/O objects, a websocket stream is <span class="bold"><strong>not thread-safe</strong></span>. 184 Undefined behavior results if two different threads access the object concurrently. 185 For multi-threaded programs, the <code class="computeroutput"><span class="identifier">tcp_stream</span></code> 186 can be constructed from an executor, in this case a strand. The stream declared 187 below will use a strand to invoke all completion handlers: 188 </p> 189<pre class="programlisting"><span class="comment">// The `tcp_stream` will be constructed with a new</span> 190<span class="comment">// strand which uses the specified I/O context.</span> 191 192<span class="identifier">stream</span><span class="special"><</span><span class="identifier">tcp_stream</span><span class="special">></span> <span class="identifier">ws</span><span class="special">(</span><span class="identifier">net</span><span class="special">::</span><span class="identifier">make_strand</span><span class="special">(</span><span class="identifier">ioc</span><span class="special">));</span> 193</pre> 194<p> 195 If the next layer supports move-construction, then the websocket stream can 196 be constructed from a moved-from object. 197 </p> 198<pre class="programlisting"><span class="comment">// Ownership of the `tcp_stream` is transferred to the websocket stream</span> 199 200<span class="identifier">stream</span><span class="special"><</span><span class="identifier">tcp_stream</span><span class="special">></span> <span class="identifier">ws</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">sock</span><span class="special">));</span> 201</pre> 202<p> 203 The next layer may be accessed by calling <a class="link" href="ref/boost__beast__websocket__stream/next_layer/overload1.html" title="websocket::stream::next_layer (1 of 2 overloads)"><code class="computeroutput"><span class="identifier">stream</span><span class="special">::</span><span class="identifier">next_layer</span></code></a>. 204 </p> 205<pre class="programlisting"><span class="comment">// Calls `close` on the underlying `beast::tcp_stream`</span> 206<span class="identifier">ws</span><span class="special">.</span><span class="identifier">next_layer</span><span class="special">().</span><span class="identifier">close</span><span class="special">();</span> 207</pre> 208<h4> 209<a name="beast.using_websocket.h1"></a> 210 <span class="phrase"><a name="beast.using_websocket.using_ssl"></a></span><a class="link" href="using_websocket.html#beast.using_websocket.using_ssl">Using 211 SSL</a> 212 </h4> 213<p> 214 To use WebSockets over SSL, use an instance of the <a href="../../../../../doc/html/boost_asio/reference/ssl__stream.html" target="_top"><code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code></a> 215 class template as the template type for the stream. The required <a href="../../../../../doc/html/boost_asio/reference/io_context.html" target="_top"><code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">io_context</span></code></a> 216 and <a href="../../../../../doc/html/boost_asio/reference/ssl__context.html" target="_top"><code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span></code></a> 217 arguments are forwarded to the wrapped stream's constructor: 218 </p> 219<pre class="programlisting"><span class="comment">// The WebSocket stream will use SSL and a new strand</span> 220<span class="identifier">stream</span><span class="special"><</span><span class="identifier">ssl_stream</span><span class="special"><</span><span class="identifier">tcp_stream</span><span class="special">>></span> <span class="identifier">wss</span><span class="special">(</span><span class="identifier">net</span><span class="special">::</span><span class="identifier">make_strand</span><span class="special">(</span><span class="identifier">ioc</span><span class="special">),</span> <span class="identifier">ctx</span><span class="special">);</span> 221</pre> 222<div class="important"><table border="0" summary="Important"> 223<tr> 224<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td> 225<th align="left">Important</th> 226</tr> 227<tr><td align="left" valign="top"><p> 228 Code which declares websocket stream objects using Asio SSL types must include 229 the file <code class="literal"><<a href="../../../../../boost/beast/websocket/ssl.hpp" target="_top">boost/beast/websocket/ssl.hpp</a>></code>. 230 </p></td></tr> 231</table></div> 232<p> 233 As before, the underlying SSL stream may be accessed by calling <code class="computeroutput"><span class="identifier">next_layer</span></code>. 234 </p> 235<pre class="programlisting"><span class="comment">// Perform the SSL handshake in the client role</span> 236<span class="identifier">wss</span><span class="special">.</span><span class="identifier">next_layer</span><span class="special">().</span><span class="identifier">handshake</span><span class="special">(</span><span class="identifier">net</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">client</span><span class="special">);</span> 237</pre> 238<p> 239 With multi-layered streams such as the one declared above, accessing an individual 240 layer can be cumbersome when using chained calls to <code class="computeroutput"><span class="identifier">next_layer</span></code>. 241 The function <a class="link" href="ref/boost__beast__get_lowest_layer.html" title="get_lowest_layer"><code class="computeroutput"><span class="identifier">get_lowest_layer</span></code></a> returns the last 242 stream in a stack of layers in a layered stream. Here we access the lowest 243 layer to cancel all outstanding I/O. 244 </p> 245<pre class="programlisting"><span class="comment">// Cancel all pending I/O on the underlying `tcp_stream`</span> 246<span class="identifier">get_lowest_layer</span><span class="special">(</span><span class="identifier">wss</span><span class="special">).</span><span class="identifier">cancel</span><span class="special">();</span> 247</pre> 248<h4> 249<a name="beast.using_websocket.h2"></a> 250 <span class="phrase"><a name="beast.using_websocket.non_blocking_mode"></a></span><a class="link" href="using_websocket.html#beast.using_websocket.non_blocking_mode">Non-Blocking 251 Mode</a> 252 </h4> 253<p> 254 Please note that websocket streams do not support non-blocking modes. 255 </p> 256</div> 257<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 258<td align="left"></td> 259<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 260 Falco<p> 261 Distributed under the Boost Software License, Version 1.0. (See accompanying 262 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>) 263 </p> 264</div></td> 265</tr></table> 266<hr> 267<div class="spirit-nav"> 268<a accesskey="p" href="more_examples/send_child_process_output.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="using_websocket/establishing_connections.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 269</div> 270</body> 271</html> 272
