120 lines
5.1 KiB
Plaintext
120 lines
5.1 KiB
Plaintext
[/
|
|
Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
|
|
Official repository: https://github.com/boostorg/beast
|
|
]
|
|
|
|
[section Control Frames]
|
|
|
|
Control frames are small (less than 128 bytes) messages entirely contained
|
|
in an individual WebSocket frame. They may be sent at any time by either
|
|
peer on an established connection, and can appear in between continuation
|
|
frames for a message. There are three types of control frames: ping, pong,
|
|
and close.
|
|
|
|
A sent ping indicates a request that the sender wants to receive a pong. A
|
|
pong is a response to a ping. Pongs may be sent unsolicited, at any time.
|
|
One use for an unsolicited pong is to inform the remote peer that the
|
|
session is still active after a long period of inactivity. A close frame
|
|
indicates that the remote peer wishes to close the WebSocket connection.
|
|
The connection is considered gracefully closed when each side has sent
|
|
and received a close frame.
|
|
|
|
During read operations, Beast automatically reads and processes control
|
|
frames. If a control callback is registered, the callback is notified of
|
|
the incoming control frame. The implementation will respond to pings
|
|
automatically. The receipt of a close frame initiates the WebSocket
|
|
close procedure, eventually resulting in the error code
|
|
[link beast.ref.boost__beast__websocket__error `error::closed`]
|
|
being delivered to the caller in a subsequent read operation, assuming
|
|
no other error takes place.
|
|
|
|
A consequence of this automatic behavior is that caller-initiated read
|
|
operations can cause socket writes. However, these writes will not
|
|
compete with caller-initiated write operations. For the purposes of
|
|
correctness with respect to the stream invariants, caller-initiated
|
|
read operations still only count as a read. This means that callers can
|
|
have a simultaneously active read, write, and ping/pong operation in
|
|
progress, while the implementation also automatically handles control
|
|
frames.
|
|
|
|
[heading Control Callback]
|
|
|
|
Ping, pong, and close messages are control frames which may be sent at
|
|
any time by either peer on an established WebSocket connection. They
|
|
are sent using the functions
|
|
[link beast.ref.boost__beast__websocket__stream.ping `ping`],
|
|
[link beast.ref.boost__beast__websocket__stream.pong `pong`].
|
|
and
|
|
[link beast.ref.boost__beast__websocket__stream.close `close`].
|
|
To be notified of control frames, callers may register a
|
|
['control callback] using
|
|
[link beast.ref.boost__beast__websocket__stream.control_callback `control_callback`].
|
|
The object provided with this option should be callable with the following
|
|
signature:
|
|
|
|
[code_websocket_5_1]
|
|
|
|
When a control callback is registered, it will be invoked for all pings,
|
|
pongs, and close frames received through either synchronous read functions
|
|
or asynchronous read functions. The type of frame and payload text are
|
|
passed as parameters to the control callback. If the frame is a close
|
|
frame, the close reason may be obtained by calling
|
|
[link beast.ref.boost__beast__websocket__stream.reason `reason`].
|
|
|
|
Unlike regular completion handlers used in calls to asynchronous initiation
|
|
functions, the control callback only needs to be set once. The callback is
|
|
not reset after being called. The same callback is used for both synchronous
|
|
and asynchronous reads. The callback is passive; in order to be called,
|
|
a stream read operation must be active.
|
|
|
|
[note
|
|
When an asynchronous read function receives a control frame, the
|
|
control callback is invoked in the same manner as that used to
|
|
invoke the final completion handler of the corresponding read
|
|
function.
|
|
]
|
|
|
|
[heading Close Frames]
|
|
|
|
The WebSocket protocol defines a procedure and control message for
|
|
initiating a close of the session. In this procedure, a host requests
|
|
the close by sending a
|
|
[@https://tools.ietf.org/html/rfc6455#section-5.5.1 ['close frame]].
|
|
To request a close use a close function such as
|
|
[link beast.ref.boost__beast__websocket__stream.close.overload2 `close`] or
|
|
[link beast.ref.boost__beast__websocket__stream.async_close `async_close`]:
|
|
|
|
[code_websocket_5_2]
|
|
|
|
The close function will send a close frame, read and discard incoming
|
|
message data until receiving a close frame, and then shut down the
|
|
underlying connection before returning.
|
|
|
|
When a close frame is received by during a read operation, the implementation
|
|
will automatically respond with a close frame and then shut down the
|
|
underlying connection before returning. In this case, the read operation
|
|
will complete with the code
|
|
[link beast.ref.boost__beast__websocket__error `error::closed`].
|
|
This indicates to the caller that the connection has been closed cleanly.
|
|
|
|
[important
|
|
To receive the
|
|
[link beast.ref.boost__beast__websocket__error `error::closed`]
|
|
error, a read operation is required.
|
|
]
|
|
|
|
[heading Auto-fragment]
|
|
|
|
To ensure timely delivery of control frames, large outgoing messages can
|
|
be broken up into smaller sized frames. The automatic fragment option
|
|
turns on this feature, and the write buffer size option determines the
|
|
maximum size of the fragments:
|
|
|
|
[code_websocket_5_3]
|
|
|
|
[endsect]
|