1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[section Control Frames] 11 12Control frames are small (less than 128 bytes) messages entirely contained 13in an individual WebSocket frame. They may be sent at any time by either 14peer on an established connection, and can appear in between continuation 15frames for a message. There are three types of control frames: ping, pong, 16and close. 17 18A sent ping indicates a request that the sender wants to receive a pong. A 19pong is a response to a ping. Pongs may be sent unsolicited, at any time. 20One use for an unsolicited pong is to inform the remote peer that the 21session is still active after a long period of inactivity. A close frame 22indicates that the remote peer wishes to close the WebSocket connection. 23The connection is considered gracefully closed when each side has sent 24and received a close frame. 25 26During read operations, Beast automatically reads and processes control 27frames. If a control callback is registered, the callback is notified of 28the incoming control frame. The implementation will respond to pings 29automatically. The receipt of a close frame initiates the WebSocket 30close procedure, eventually resulting in the error code 31[link beast.ref.boost__beast__websocket__error `error::closed`] 32being delivered to the caller in a subsequent read operation, assuming 33no other error takes place. 34 35A consequence of this automatic behavior is that caller-initiated read 36operations can cause socket writes. However, these writes will not 37compete with caller-initiated write operations. For the purposes of 38correctness with respect to the stream invariants, caller-initiated 39read operations still only count as a read. This means that callers can 40have a simultaneously active read, write, and ping/pong operation in 41progress, while the implementation also automatically handles control 42frames. 43 44[heading Control Callback] 45 46Ping, pong, and close messages are control frames which may be sent at 47any time by either peer on an established WebSocket connection. They 48are sent using the functions 49[link beast.ref.boost__beast__websocket__stream.ping `ping`], 50[link beast.ref.boost__beast__websocket__stream.pong `pong`]. 51and 52[link beast.ref.boost__beast__websocket__stream.close `close`]. 53To be notified of control frames, callers may register a 54['control callback] using 55[link beast.ref.boost__beast__websocket__stream.control_callback `control_callback`]. 56The object provided with this option should be callable with the following 57signature: 58 59[code_websocket_5_1] 60 61When a control callback is registered, it will be invoked for all pings, 62pongs, and close frames received through either synchronous read functions 63or asynchronous read functions. The type of frame and payload text are 64passed as parameters to the control callback. If the frame is a close 65frame, the close reason may be obtained by calling 66[link beast.ref.boost__beast__websocket__stream.reason `reason`]. 67 68Unlike regular completion handlers used in calls to asynchronous initiation 69functions, the control callback only needs to be set once. The callback is 70not reset after being called. The same callback is used for both synchronous 71and asynchronous reads. The callback is passive; in order to be called, 72a stream read operation must be active. 73 74[note 75 When an asynchronous read function receives a control frame, the 76 control callback is invoked in the same manner as that used to 77 invoke the final completion handler of the corresponding read 78 function. 79] 80 81[heading Close Frames] 82 83The WebSocket protocol defines a procedure and control message for 84initiating a close of the session. In this procedure, a host requests 85the close by sending a 86[@https://tools.ietf.org/html/rfc6455#section-5.5.1 ['close frame]]. 87To request a close use a close function such as 88[link beast.ref.boost__beast__websocket__stream.close.overload2 `close`] or 89[link beast.ref.boost__beast__websocket__stream.async_close `async_close`]: 90 91[code_websocket_5_2] 92 93The close function will send a close frame, read and discard incoming 94message data until receiving a close frame, and then shut down the 95underlying connection before returning. 96 97When a close frame is received by during a read operation, the implementation 98will automatically respond with a close frame and then shut down the 99underlying connection before returning. In this case, the read operation 100will complete with the code 101[link beast.ref.boost__beast__websocket__error `error::closed`]. 102This indicates to the caller that the connection has been closed cleanly. 103 104[important 105 To receive the 106 [link beast.ref.boost__beast__websocket__error `error::closed`] 107 error, a read operation is required. 108] 109 110[heading Auto-fragment] 111 112To ensure timely delivery of control frames, large outgoing messages can 113be broken up into smaller sized frames. The automatic fragment option 114turns on this feature, and the write buffer size option determines the 115maximum size of the fragments: 116 117[code_websocket_5_3] 118 119[endsect] 120