websocket::stream

Provides message-oriented functionality using WebSocket.

Synopsis

Defined in header <boost/beast/websocket/stream.hpp>

template<
    class NextLayer,
    bool deflateSupported>
class stream

Types

Name	Description
executor_type	The type of the executor associated with the object.
is_deflate_supported	Indicates if the permessage-deflate extension is supported.
lowest_layer_type	The type of the lowest layer.
next_layer_type	The type of the next layer.

Member Functions

Name	Description
accept	Read and respond to a WebSocket HTTP Upgrade request. Respond to a WebSocket HTTP Upgrade request.
accept_ex	Read and respond to a WebSocket HTTP Upgrade request.
async_accept	Start reading and responding to a WebSocket HTTP Upgrade request. Start responding to a WebSocket HTTP Upgrade request.
async_accept_ex	Start reading and responding to a WebSocket HTTP Upgrade request.
async_close	Start an asynchronous operation to send a WebSocket close frame.
async_handshake	Start an asynchronous operation to send an upgrade request and receive the response.
async_handshake_ex	Start an asynchronous operation to send an upgrade request and receive the response.
async_ping	Start an asynchronous operation to send a WebSocket ping frame.
async_pong	Start an asynchronous operation to send a WebSocket pong frame.
async_read	Read a message asynchronously.
async_read_some	Read part of a message asynchronously.
async_write	Start an asynchronous operation to write a message to the stream.
async_write_some	Start an asynchronous operation to send a message frame on the stream.
auto_fragment	Set the automatic fragmentation option. Returns true if the automatic fragmentation option is set.
binary	Set the binary message write option. Returns true if the binary message write option is set.
close	Send a WebSocket close frame.
control_callback	Set a callback to be invoked on each incoming control frame. Reset the control frame callback.
get_executor	Get the executor associated with the object.
get_option	Get the permessage-deflate extension options.
got_binary	Returns true if the latest message data indicates binary.
got_text	Returns true if the latest message data indicates text.
handshake	Send an HTTP WebSocket Upgrade request and receive the response.
handshake_ex	Send an HTTP WebSocket Upgrade request and receive the response.
is_message_done	Returns true if the last completed read finished the current message.
is_open	Returns true if the stream is open.
lowest_layer	Get a reference to the lowest layer.
next_layer	Get a reference to the next layer.
operator=	Assignment.
ping	Send a WebSocket ping frame.
pong	Send a WebSocket pong frame.
read	Read a message.
read_message_max	Set the maximum incoming message size option. Returns the maximum incoming message size setting.
read_size_hint	Returns a suggested maximum buffer size for the next call to read.
read_some	Read part of a message.
reason	Returns the close reason received from the peer.
secure_prng	Set whether the PRNG is cryptographically secure.
set_option	Set the permessage-deflate extension options.
stream	Constructor.
text	Set the text message write option. Returns true if the text message write option is set.
write	Write a message to the stream.
write_buffer_size	Set the write buffer size option. Returns the size of the write buffer.
write_some	Write partial message data on the stream.
~stream	Destructor.

Description

The websocket::stream class template provides asynchronous and blocking message-oriented functionality necessary for clients and servers to utilize the WebSocket protocol.

For asynchronous operations, the application must ensure that they are are all performed within the same implicit or explicit strand.

Thread Safety

Distinct objects: Safe.

Shared objects: Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand.

Example

To use the websocket::stream template with an ip::tcp::socket, you would write:

websocket::stream<ip::tcp::socket> ws{io_context};

Alternatively, you can write:

ip::tcp::socket sock{io_context};
websocket::stream<ip::tcp::socket&> ws{sock};

Template Parameters

Type	Description
`NextLayer`	The type representing the next layer, to which data will be read and written during operations. For synchronous operations, the type must support the SyncStream concept. For asynchronous operations, the type must support the AsyncStream concept.
`deflateSupported`	A `bool` indicating whether or not the stream will be capable of negotiating the permessage-deflate websocket extension. Note that even if this is set to `true`, the permessage deflate options (set by the caller at runtime) must still have the feature enabled for a successful negotiation to occur.

Remarks

A stream object must not be moved or destroyed while there are pending asynchronous operations associated with it.

Concepts

AsyncStream, DynamicBuffer, SyncStream

Convenience header <boost/beast/websocket.hpp>