Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 3af5ca4713.
PrevUpHomeNext

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.

next_layer_type

The type of the next layer.

Member Functions

Name

Description

accept

Perform the WebSocket handshake in the server role.

Read and respond to a WebSocket HTTP Upgrade request.

Respond to a WebSocket HTTP Upgrade request.

async_accept

Perform the WebSocket handshake asynchronously in the server role.

async_close

Send a websocket close control frame asynchronously.

async_handshake

Perform the WebSocket handshake asynchronously in the client role.

async_ping

Send a websocket ping control frame asynchronously.

async_pong

Send a websocket pong control frame asynchronously.

async_read

Read a complete message asynchronously.

async_read_some

Read some message data asynchronously.

async_write

Write a complete message asynchronously.

async_write_some

Write some message data asynchronously.

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 control 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

Perform the WebSocket handshake in the client role.

is_message_done

Returns true if the last completed read finished the current message.

is_open

Returns true if the stream is open.

next_layer

Get a reference to the next layer.

operator=

Move assignment (deleted)

ping

Send a websocket ping control frame.

pong

Send a websocket pong control frame.

read

Read a complete 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 some message data.

reason

Returns the close reason received from the remote 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 complete message.

write_buffer_bytes

Set the write buffer size option.

Returns the size of the write buffer.

write_some

Write some message data.

~stream

Destructor.

Description

The 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

Distinctobjects:Safe.

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

Example

To declare the stream object with a tcp_stream in a multi-threaded asynchronous program using a strand, you may write:

websocket::stream<tcp_stream> ws{net::make_strand(ioc)};

Alternatively, for a single-threaded or synchronous application you may write:

websocket::stream<tcp_stream> ws(ioc);
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.

See Also

PrevUpHomeNext