1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Control Frames</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_websocket.html" title="WebSocket"> 9<link rel="prev" href="messages.html" title="Messages"> 10<link rel="next" href="timeouts.html" title="Timeouts"> 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="messages.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.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="timeouts.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_websocket.control_frames"></a><a class="link" href="control_frames.html" title="Control Frames">Control Frames</a> 28</h3></div></div></div> 29<p> 30 Control frames are small (less than 128 bytes) messages entirely contained 31 in an individual WebSocket frame. They may be sent at any time by either 32 peer on an established connection, and can appear in between continuation 33 frames for a message. There are three types of control frames: ping, pong, 34 and close. 35 </p> 36<p> 37 A sent ping indicates a request that the sender wants to receive a pong. 38 A pong is a response to a ping. Pongs may be sent unsolicited, at any time. 39 One use for an unsolicited pong is to inform the remote peer that the session 40 is still active after a long period of inactivity. A close frame indicates 41 that the remote peer wishes to close the WebSocket connection. The connection 42 is considered gracefully closed when each side has sent and received a close 43 frame. 44 </p> 45<p> 46 During read operations, Beast automatically reads and processes control frames. 47 If a control callback is registered, the callback is notified of the incoming 48 control frame. The implementation will respond to pings automatically. The 49 receipt of a close frame initiates the WebSocket close procedure, eventually 50 resulting in the error code <a class="link" href="../ref/boost__beast__websocket__error.html" title="websocket::error"><code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">closed</span></code></a> being delivered to the caller 51 in a subsequent read operation, assuming no other error takes place. 52 </p> 53<p> 54 A consequence of this automatic behavior is that caller-initiated read operations 55 can cause socket writes. However, these writes will not compete with caller-initiated 56 write operations. For the purposes of correctness with respect to the stream 57 invariants, caller-initiated read operations still only count as a read. 58 This means that callers can have a simultaneously active read, write, and 59 ping/pong operation in progress, while the implementation also automatically 60 handles control frames. 61 </p> 62<h5> 63<a name="beast.using_websocket.control_frames.h0"></a> 64 <span class="phrase"><a name="beast.using_websocket.control_frames.control_callback"></a></span><a class="link" href="control_frames.html#beast.using_websocket.control_frames.control_callback">Control Callback</a> 65 </h5> 66<p> 67 Ping, pong, and close messages are control frames which may be sent at any 68 time by either peer on an established WebSocket connection. They are sent 69 using the functions <a class="link" href="../ref/boost__beast__websocket__stream/ping.html" title="websocket::stream::ping"><code class="computeroutput"><span class="identifier">ping</span></code></a>, <a class="link" href="../ref/boost__beast__websocket__stream/pong.html" title="websocket::stream::pong"><code class="computeroutput"><span class="identifier">pong</span></code></a>. and <a class="link" href="../ref/boost__beast__websocket__stream/close.html" title="websocket::stream::close"><code class="computeroutput"><span class="identifier">close</span></code></a>. To be notified of control 70 frames, callers may register a <span class="emphasis"><em>control callback</em></span> using 71 <a class="link" href="../ref/boost__beast__websocket__stream/control_callback.html" title="websocket::stream::control_callback"><code class="computeroutput"><span class="identifier">control_callback</span></code></a>. The object provided 72 with this option should be callable with the following signature: 73 </p> 74<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">control_callback</span><span class="special">(</span> 75 <span class="special">[](</span><span class="identifier">frame_type</span> <span class="identifier">kind</span><span class="special">,</span> <span class="identifier">string_view</span> <span class="identifier">payload</span><span class="special">)</span> 76 <span class="special">{</span> 77 <span class="comment">// Do something with the payload</span> 78 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ignore_unused</span><span class="special">(</span><span class="identifier">kind</span><span class="special">,</span> <span class="identifier">payload</span><span class="special">);</span> 79 <span class="special">});</span> 80</pre> 81<p> 82 When a control callback is registered, it will be invoked for all pings, 83 pongs, and close frames received through either synchronous read functions 84 or asynchronous read functions. The type of frame and payload text are passed 85 as parameters to the control callback. If the frame is a close frame, the 86 close reason may be obtained by calling <a class="link" href="../ref/boost__beast__websocket__stream/reason.html" title="websocket::stream::reason"><code class="computeroutput"><span class="identifier">reason</span></code></a>. 87 </p> 88<p> 89 Unlike regular completion handlers used in calls to asynchronous initiation 90 functions, the control callback only needs to be set once. The callback is 91 not reset after being called. The same callback is used for both synchronous 92 and asynchronous reads. The callback is passive; in order to be called, a 93 stream read operation must be active. 94 </p> 95<div class="note"><table border="0" summary="Note"> 96<tr> 97<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 98<th align="left">Note</th> 99</tr> 100<tr><td align="left" valign="top"><p> 101 When an asynchronous read function receives a control frame, the control 102 callback is invoked in the same manner as that used to invoke the final 103 completion handler of the corresponding read function. 104 </p></td></tr> 105</table></div> 106<h5> 107<a name="beast.using_websocket.control_frames.h1"></a> 108 <span class="phrase"><a name="beast.using_websocket.control_frames.close_frames"></a></span><a class="link" href="control_frames.html#beast.using_websocket.control_frames.close_frames">Close 109 Frames</a> 110 </h5> 111<p> 112 The WebSocket protocol defines a procedure and control message for initiating 113 a close of the session. In this procedure, a host requests the close by sending 114 a <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1" target="_top"><span class="emphasis"><em>close 115 frame</em></span></a>. To request a close use a close function such as 116 <a class="link" href="../ref/boost__beast__websocket__stream/close/overload2.html" title="websocket::stream::close (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">close</span></code></a> or <a class="link" href="../ref/boost__beast__websocket__stream/async_close.html" title="websocket::stream::async_close"><code class="computeroutput"><span class="identifier">async_close</span></code></a>: 117 </p> 118<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">close</span><span class="special">(</span><span class="identifier">close_code</span><span class="special">::</span><span class="identifier">normal</span><span class="special">);</span> 119</pre> 120<p> 121 The close function will send a close frame, read and discard incoming message 122 data until receiving a close frame, and then shut down the underlying connection 123 before returning. 124 </p> 125<p> 126 When a close frame is received by during a read operation, the implementation 127 will automatically respond with a close frame and then shut down the underlying 128 connection before returning. In this case, the read operation will complete 129 with the code <a class="link" href="../ref/boost__beast__websocket__error.html" title="websocket::error"><code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">closed</span></code></a>. This indicates to the caller 130 that the connection has been closed cleanly. 131 </p> 132<div class="important"><table border="0" summary="Important"> 133<tr> 134<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td> 135<th align="left">Important</th> 136</tr> 137<tr><td align="left" valign="top"><p> 138 To receive the <a class="link" href="../ref/boost__beast__websocket__error.html" title="websocket::error"><code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">closed</span></code></a> error, a read operation 139 is required. 140 </p></td></tr> 141</table></div> 142<h5> 143<a name="beast.using_websocket.control_frames.h2"></a> 144 <span class="phrase"><a name="beast.using_websocket.control_frames.auto_fragment"></a></span><a class="link" href="control_frames.html#beast.using_websocket.control_frames.auto_fragment">Auto-fragment</a> 145 </h5> 146<p> 147 To ensure timely delivery of control frames, large outgoing messages can 148 be broken up into smaller sized frames. The automatic fragment option turns 149 on this feature, and the write buffer size option determines the maximum 150 size of the fragments: 151 </p> 152<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">auto_fragment</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span> 153<span class="identifier">ws</span><span class="special">.</span><span class="identifier">write_buffer_bytes</span><span class="special">(</span><span class="number">16384</span><span class="special">);</span> 154</pre> 155</div> 156<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 157<td align="left"></td> 158<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 159 Falco<p> 160 Distributed under the Boost Software License, Version 1.0. (See accompanying 161 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>) 162 </p> 163</div></td> 164</tr></table> 165<hr> 166<div class="spirit-nav"> 167<a accesskey="p" href="messages.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.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="timeouts.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 168</div> 169</body> 170</html> 171
