#include <stream.hpp>

Classes
class	accept_op

class	close_op

class	handshake_op

class	ping_op

class	read_op

class	read_some_op

class	response_op

class	write_some_op

Public Types
using	next_layer_type = typename std::remove_reference< NextLayer >::type
	The type of the next layer. More...

using	lowest_layer_type = typename get_lowest_layer< next_layer_type >::type
	The type of the lowest layer. More...

Public Member Functions
	~stream ()=default

	stream (stream &&)=default

stream &	operator= (stream &&)=default

template<class... Args>
	stream (Args &&...args)

boost::asio::io_service &	get_io_service ()

next_layer_type &	next_layer ()

next_layer_type const &	next_layer () const

lowest_layer_type &	lowest_layer ()

lowest_layer_type const &	lowest_layer () const

bool	is_open () const

bool	got_binary () const

bool	got_text () const

bool	is_message_done () const
	Returns `true` if the last completed read finished the current message. More...

close_reason const &	reason () const

std::size_t	read_size_hint (std::size_t initial_size=+tcp_frame_size) const

template<class DynamicBuffer , class = typename std::enable_if< ! std::is_integral<DynamicBuffer>::value>::type>
std::size_t	read_size_hint (DynamicBuffer &buffer) const

void	set_option (permessage_deflate const &o)
	Set the permessage-deflate extension options. More...

void	get_option (permessage_deflate &o)
	Get the permessage-deflate extension options. More...

void	auto_fragment (bool value)

bool	auto_fragment () const
	Returns `true` if the automatic fragmentation option is set. More...

void	binary (bool value)

bool	binary () const
	Returns `true` if the binary message option is set. More...

template<class Callback >
void	control_callback (Callback &cb)

void	control_callback ()

void	read_message_max (std::size_t amount)

std::size_t	read_message_max () const
	Returns the maximum incoming message size setting. More...

void	write_buffer_size (std::size_t amount)

std::size_t	write_buffer_size () const
	Returns the size of the write buffer. More...

void	text (bool value)

bool	text () const
	Returns `true` if the text message option is set. More...

void	handshake (string_view host, string_view target)

void	handshake (response_type &res, string_view host, string_view target)

template<class RequestDecorator >
void	handshake_ex (string_view host, string_view target, RequestDecorator const &decorator)

template<class RequestDecorator >
void	handshake_ex (response_type &res, string_view host, string_view target, RequestDecorator const &decorator)

void	handshake (string_view host, string_view target, error_code &ec)

void	handshake (response_type &res, string_view host, string_view target, error_code &ec)

template<class RequestDecorator >
void	handshake_ex (string_view host, string_view target, RequestDecorator const &decorator, error_code &ec)

template<class RequestDecorator >
void	handshake_ex (response_type &res, string_view host, string_view target, RequestDecorator const &decorator, error_code &ec)

template<class HandshakeHandler >
async_return_type< HandshakeHandler, void(error_code)>	async_handshake (string_view host, string_view target, HandshakeHandler &&handler)

template<class HandshakeHandler >
async_return_type< HandshakeHandler, void(error_code)>	async_handshake (response_type &res, string_view host, string_view target, HandshakeHandler &&handler)

template<class RequestDecorator , class HandshakeHandler >
async_return_type< HandshakeHandler, void(error_code)>	async_handshake_ex (string_view host, string_view target, RequestDecorator const &decorator, HandshakeHandler &&handler)

template<class RequestDecorator , class HandshakeHandler >
async_return_type< HandshakeHandler, void(error_code)>	async_handshake_ex (response_type &res, string_view host, string_view target, RequestDecorator const &decorator, HandshakeHandler &&handler)

void	accept ()

template<class ResponseDecorator >
void	accept_ex (ResponseDecorator const &decorator)

void	accept (error_code &ec)

template<class ResponseDecorator >
void	accept_ex (ResponseDecorator const &decorator, error_code &ec)

template<class ConstBufferSequence >
std::enable_if<!http::detail::is_header< ConstBufferSequence >::value >::type	accept (ConstBufferSequence const &buffers)

template<class ConstBufferSequence , class ResponseDecorator >
std::enable_if<!http::detail::is_header< ConstBufferSequence >::value >::type	accept_ex (ConstBufferSequence const &buffers, ResponseDecorator const &decorator)

template<class ConstBufferSequence >
std::enable_if<!http::detail::is_header< ConstBufferSequence >::value >::type	accept (ConstBufferSequence const &buffers, error_code &ec)

template<class ConstBufferSequence , class ResponseDecorator >
std::enable_if<!http::detail::is_header< ConstBufferSequence >::value >::type	accept_ex (ConstBufferSequence const &buffers, ResponseDecorator const &decorator, error_code &ec)

template<class Body , class Allocator >
void	accept (http::request< Body, http::basic_fields< Allocator >> const &req)

template<class Body , class Allocator , class ResponseDecorator >
void	accept_ex (http::request< Body, http::basic_fields< Allocator >> const &req, ResponseDecorator const &decorator)

template<class Body , class Allocator >
void	accept (http::request< Body, http::basic_fields< Allocator >> const &req, error_code &ec)

template<class Body , class Allocator , class ResponseDecorator >
void	accept_ex (http::request< Body, http::basic_fields< Allocator >> const &req, ResponseDecorator const &decorator, error_code &ec)

template<class AcceptHandler >
async_return_type< AcceptHandler, void(error_code)>	async_accept (AcceptHandler &&handler)

template<class ResponseDecorator , class AcceptHandler >
async_return_type< AcceptHandler, void(error_code)>	async_accept_ex (ResponseDecorator const &decorator, AcceptHandler &&handler)

template<class ConstBufferSequence , class AcceptHandler >
std::enable_if< !http::detail::is_header< ConstBufferSequence >::value, async_return_type< AcceptHandler, void(error_code)> >::type	async_accept (ConstBufferSequence const &buffers, AcceptHandler &&handler)

template<class ConstBufferSequence , class ResponseDecorator , class AcceptHandler >
std::enable_if< !http::detail::is_header< ConstBufferSequence >::value, async_return_type< AcceptHandler, void(error_code)> >::type	async_accept_ex (ConstBufferSequence const &buffers, ResponseDecorator const &decorator, AcceptHandler &&handler)

template<class Body , class Allocator , class AcceptHandler >
async_return_type< AcceptHandler, void(error_code)>	async_accept (http::request< Body, http::basic_fields< Allocator >> const &req, AcceptHandler &&handler)

template<class Body , class Allocator , class ResponseDecorator , class AcceptHandler >
async_return_type< AcceptHandler, void(error_code)>	async_accept_ex (http::request< Body, http::basic_fields< Allocator >> const &req, ResponseDecorator const &decorator, AcceptHandler &&handler)

void	close (close_reason const &cr)

void	close (close_reason const &cr, error_code &ec)

template<class CloseHandler >
async_return_type< CloseHandler, void(error_code)>	async_close (close_reason const &cr, CloseHandler &&handler)

void	ping (ping_data const &payload)

void	ping (ping_data const &payload, error_code &ec)

template<class WriteHandler >
async_return_type< WriteHandler, void(error_code)>	async_ping (ping_data const &payload, WriteHandler &&handler)

void	pong (ping_data const &payload)

void	pong (ping_data const &payload, error_code &ec)

template<class WriteHandler >
async_return_type< WriteHandler, void(error_code)>	async_pong (ping_data const &payload, WriteHandler &&handler)

template<class DynamicBuffer >
std::size_t	read (DynamicBuffer &buffer)

template<class DynamicBuffer >
std::size_t	read (DynamicBuffer &buffer, error_code &ec)

template<class DynamicBuffer , class ReadHandler >
async_return_type< ReadHandler, void(error_code, std::size_t)>	async_read (DynamicBuffer &buffer, ReadHandler &&handler)

template<class DynamicBuffer >
std::size_t	read_some (DynamicBuffer &buffer, std::size_t limit)

template<class DynamicBuffer >
std::size_t	read_some (DynamicBuffer &buffer, std::size_t limit, error_code &ec)

template<class DynamicBuffer , class ReadHandler >
async_return_type< ReadHandler, void(error_code, std::size_t)>	async_read_some (DynamicBuffer &buffer, std::size_t limit, ReadHandler &&handler)

template<class MutableBufferSequence >
std::size_t	read_some (MutableBufferSequence const &buffers)

template<class MutableBufferSequence >
std::size_t	read_some (MutableBufferSequence const &buffers, error_code &ec)

template<class MutableBufferSequence , class ReadHandler >
async_return_type< ReadHandler, void(error_code, std::size_t)>	async_read_some (MutableBufferSequence const &buffers, ReadHandler &&handler)

template<class ConstBufferSequence >
std::size_t	write (ConstBufferSequence const &buffers)

template<class ConstBufferSequence >
std::size_t	write (ConstBufferSequence const &buffers, error_code &ec)

template<class ConstBufferSequence , class WriteHandler >
async_return_type< WriteHandler, void(error_code, std::size_t)>	async_write (ConstBufferSequence const &buffers, WriteHandler &&handler)

template<class ConstBufferSequence >
std::size_t	write_some (bool fin, ConstBufferSequence const &buffers)

template<class ConstBufferSequence >
std::size_t	write_some (bool fin, ConstBufferSequence const &buffers, error_code &ec)

template<class ConstBufferSequence , class WriteHandler >
async_return_type< WriteHandler, void(error_code, std::size_t)>	async_write_some (bool fin, ConstBufferSequence const &buffers, WriteHandler &&handler)

Friends
class	close_test

class	frame_test

class	ping_test

class	read_test

class	stream_test

class	write_test

Detailed Description

template<class NextLayer>
class boost::beast::websocket::stream< NextLayer >

Provides message-oriented functionality using WebSocket.

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: Distinct objects: Safe.
Shared objects: Unsafe.

Example

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

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

Alternatively, you can write:

ip::tcp::socket sock{io_service};

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

Template Parameters

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.

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

Concepts: AsyncStream, DynamicBuffer, SyncStream

Member Typedef Documentation

template<class NextLayer >

using boost::beast::websocket::stream< NextLayer >::lowest_layer_type = typename get_lowest_layer<next_layer_type>::type

The type of the lowest layer.

template<class NextLayer >

using boost::beast::websocket::stream< NextLayer >::next_layer_type = typename std::remove_reference<NextLayer>::type

The type of the next layer.

Constructor & Destructor Documentation

template<class NextLayer >

boost::beast::websocket::stream< NextLayer >::~stream ( )

default

Destructor

Destroys the stream and all associated resources.

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

template<class NextLayer >

boost::beast::websocket::stream< NextLayer >::stream ( stream< NextLayer > && )

default

Constructor

If NextLayer is move constructible, this function will move-construct a new stream from the existing stream.

Note: The behavior of move assignment on or from streams with active or pending operations is undefined.

template<class NextLayer >

template<class... Args>

boost::beast::websocket::stream< NextLayer >::stream ( Args &&... args )

explicit

Constructor

This constructor creates a websocket stream and initializes the next layer object.

Exceptions

Any	exceptions thrown by the NextLayer constructor.

Parameters

args	The arguments to be passed to initialize the next layer object. The arguments are forwarded to the next layer's constructor.

Member Function Documentation

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::accept ( )

Read and respond to a WebSocket HTTP Upgrade request.

This function is used to synchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The call blocks until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Exceptions

system_error Thrown on failure.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::accept ( error_code & ec )

Read and respond to a WebSocket HTTP Upgrade request.

This function is used to synchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The call blocks until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class ConstBufferSequence >

std::enable_if<!http::detail::is_header< ConstBufferSequence >::value >::type boost::beast::websocket::stream< NextLayer >::accept ( ConstBufferSequence const & buffers )

Read and respond to a WebSocket HTTP Upgrade request.

This function is used to synchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The call blocks until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

buffers Caller provided data that has already been received on the stream. The implementation will copy the caller provided data before the function returns.

Exceptions

system_error Thrown on failure.

template<class NextLayer >

template<class ConstBufferSequence >

std::enable_if<!http::detail::is_header< ConstBufferSequence >::value >::type boost::beast::websocket::stream< NextLayer >::accept	(	ConstBufferSequence const &	buffers,
		error_code &	ec
	)

Read and respond to a WebSocket HTTP Upgrade request.

This function is used to synchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The call blocks until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

buffers	Caller provided data that has already been received on the stream. The implementation will copy the caller provided data before the function returns.
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class Body , class Allocator >

void boost::beast::websocket::stream< NextLayer >::accept ( http::request< Body, http::basic_fields< Allocator >> const & req )

Respond to a WebSocket HTTP Upgrade request

This function is used to synchronously send the HTTP response to an HTTP request possibly containing a WebSocket Upgrade. The call blocks until one of the following conditions is true:

The response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

Parameters

req	An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads.

Exceptions

system_error Thrown on failure.

template<class NextLayer >

template<class Body , class Allocator >

void boost::beast::websocket::stream< NextLayer >::accept	(	http::request< Body, http::basic_fields< Allocator >> const &	req,
		error_code &	ec
	)

Respond to a WebSocket HTTP Upgrade request

This function is used to synchronously send the HTTP response to an HTTP request possibly containing a WebSocket Upgrade. The call blocks until one of the following conditions is true:

The response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

Parameters

req	An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads.
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class ResponseDecorator >

void boost::beast::websocket::stream< NextLayer >::accept_ex ( ResponseDecorator const & decorator )

Read and respond to a WebSocket HTTP Upgrade request.

This function is used to synchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The call blocks until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

decorator

A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature:

 void decorator(
    response_type& res
); 

Exceptions

system_error Thrown on failure.

template<class NextLayer >

template<class ResponseDecorator >

void boost::beast::websocket::stream< NextLayer >::accept_ex	(	ResponseDecorator const &	decorator,
		error_code &	ec
	)

Read and respond to a WebSocket HTTP Upgrade request.

This function is used to synchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The call blocks until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

decorator	A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( response_type& res );
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class ConstBufferSequence , class ResponseDecorator >

std::enable_if<!http::detail::is_header< ConstBufferSequence >::value >::type boost::beast::websocket::stream< NextLayer >::accept_ex	(	ConstBufferSequence const &	buffers,
		ResponseDecorator const &	decorator
	)

Read and respond to a WebSocket HTTP Upgrade request.

This function is used to synchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The call blocks until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

buffers	Caller provided data that has already been received on the stream. The implementation will copy the caller provided data before the function returns.
decorator	A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( response_type& res );

Exceptions

system_error Thrown on failure.

template<class NextLayer >

template<class ConstBufferSequence , class ResponseDecorator >

std::enable_if<!http::detail::is_header< ConstBufferSequence >::value >::type boost::beast::websocket::stream< NextLayer >::accept_ex	(	ConstBufferSequence const &	buffers,
		ResponseDecorator const &	decorator,
		error_code &	ec
	)

Read and respond to a WebSocket HTTP Upgrade request.

This function is used to synchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The call blocks until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

buffers	Caller provided data that has already been received on the stream. The implementation will copy the caller provided data before the function returns.
decorator	A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( response_type& res );
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class Body , class Allocator , class ResponseDecorator >

void boost::beast::websocket::stream< NextLayer >::accept_ex	(	http::request< Body, http::basic_fields< Allocator >> const &	req,
		ResponseDecorator const &	decorator
	)

Respond to a WebSocket HTTP Upgrade request

This function is used to synchronously send the HTTP response to an HTTP request possibly containing a WebSocket Upgrade. The call blocks until one of the following conditions is true:

The response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

Parameters

req	An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads.
decorator	A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( response_type& res );

Exceptions

system_error Thrown on failure.

template<class NextLayer >

template<class Body , class Allocator , class ResponseDecorator >

void boost::beast::websocket::stream< NextLayer >::accept_ex	(	http::request< Body, http::basic_fields< Allocator >> const &	req,
		ResponseDecorator const &	decorator,
		error_code &	ec
	)

Respond to a WebSocket HTTP Upgrade request

This function is used to synchronously send the HTTP response to an HTTP request possibly containing a WebSocket Upgrade. The call blocks until one of the following conditions is true:

The response finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When this call returns, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure.

Parameters

req	An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads.
decorator	A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( response_type& res );
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class AcceptHandler >

async_return_type< AcceptHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_accept ( AcceptHandler && handler )

Start reading and responding to a WebSocket HTTP Upgrade request.

This function is used to asynchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other asynchronous operations until this operation completes.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When the completion handler is invoked, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure, and the completion handler will be invoked with a suitable error code set.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

handler

The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:

 void handler(
    error_code const& ec    // Result of operation
); 

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class ConstBufferSequence , class AcceptHandler >

std::enable_if< !http::detail::is_header< ConstBufferSequence >::value, async_return_type< AcceptHandler, void(error_code)> >::type boost::beast::websocket::stream< NextLayer >::async_accept	(	ConstBufferSequence const &	buffers,
		AcceptHandler &&	handler
	)

Start reading and responding to a WebSocket HTTP Upgrade request.

This function is used to asynchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other asynchronous operations until this operation completes.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When the completion handler is invoked, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure, and the completion handler will be invoked with a suitable error code set.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

buffers Caller provided data that has already been received on the stream. This may be used for implementations allowing multiple protocols on the same stream. The buffered data will first be applied to the handshake, and then to received WebSocket frames. The implementation will copy the caller provided data before the function returns.

handler

The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:

 void handler(
    error_code const& ec    // Result of operation
); 

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class Body , class Allocator , class AcceptHandler >

async_return_type< AcceptHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_accept	(	http::request< Body, http::basic_fields< Allocator >> const &	req,
		AcceptHandler &&	handler
	)

Start responding to a WebSocket HTTP Upgrade request.

This function is used to asynchronously send the HTTP response to an HTTP request possibly containing a WebSocket Upgrade request. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The response finishes sending.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other operations until this operation completes.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When the completion handler is invoked, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure, and the completion handler will be invoked with a suitable error code set.

Parameters

req An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads.

handler

The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:

 void handler(
    error_code const& ec    // Result of operation
); 

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class ResponseDecorator , class AcceptHandler >

async_return_type< AcceptHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_accept_ex	(	ResponseDecorator const &	decorator,
		AcceptHandler &&	handler
	)

Start reading and responding to a WebSocket HTTP Upgrade request.

This function is used to asynchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other asynchronous operations until this operation completes.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When the completion handler is invoked, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure, and the completion handler will be invoked with a suitable error code set.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

decorator

A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature:

 void decorator(
    response_type& res
); 

handler

The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:

 void handler(
    error_code const& ec    // Result of operation
); 

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class ConstBufferSequence , class ResponseDecorator , class AcceptHandler >

std::enable_if< !http::detail::is_header< ConstBufferSequence >::value, async_return_type< AcceptHandler, void(error_code)> >::type boost::beast::websocket::stream< NextLayer >::async_accept_ex	(	ConstBufferSequence const &	buffers,
		ResponseDecorator const &	decorator,
		AcceptHandler &&	handler
	)

Start reading and responding to a WebSocket HTTP Upgrade request.

This function is used to asynchronously read an HTTP WebSocket Upgrade request and send the HTTP response. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The request is received and the response finishes sending.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other asynchronous operations until this operation completes.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When the completion handler is invoked, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure, and the completion handler will be invoked with a suitable error code set.

The implementation uses fixed size internal storage to receive the request. If the request is too large, the error error::buffer_overflow will be indicated. Applications that wish to receive larger requests should first read the request using their own buffer and a suitable overload of http::read or http::async_read, then call accept or async_accept with the request.

Parameters

buffers	Caller provided data that has already been received on the stream. This may be used for implementations allowing multiple protocols on the same stream. The buffered data will first be applied to the handshake, and then to received WebSocket frames. The implementation will copy the caller provided data before the function returns.
decorator	A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( response_type& res );
handler	The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( error_code const& ec // Result of operation ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using `boost::asio::io_service::post`.

template<class NextLayer >

template<class Body , class Allocator , class ResponseDecorator , class AcceptHandler >

async_return_type< AcceptHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_accept_ex	(	http::request< Body, http::basic_fields< Allocator >> const &	req,
		ResponseDecorator const &	decorator,
		AcceptHandler &&	handler
	)

Start responding to a WebSocket HTTP Upgrade request.

This function is used to asynchronously send the HTTP response to an HTTP request possibly containing a WebSocket Upgrade request. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The response finishes sending.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other operations until this operation completes.

If the stream receives a valid HTTP WebSocket Upgrade request, an HTTP response is sent back indicating a successful upgrade. When the completion handler is invoked, the stream is then ready to send and receive WebSocket protocol frames and messages. If the HTTP Upgrade request is invalid or cannot be satisfied, an HTTP response is sent indicating the reason and status code (typically 400, "Bad Request"). This counts as a failure, and the completion handler will be invoked with a suitable error code set.

Parameters

req	An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads.
decorator	A function object which will be called to modify the HTTP response object delivered by the implementation. This could be used to set the Server field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( response_type& res );
handler	The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( error_code const& ec // Result of operation ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using `boost::asio::io_service::post`.

template<class NextLayer >

template<class CloseHandler >

async_return_type< CloseHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_close	(	close_reason const &	cr,
		CloseHandler &&	handler
	)

Start an asynchronous operation to send a WebSocket close frame.

This function is used to asynchronously send a close frame on the stream. This function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The close frame finishes sending.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_ping, stream::async_write, stream::async_write_some, or stream::async_close) until this operation completes.

If the close reason specifies a close code other than beast::websocket::close_code::none, the close frame is sent with the close code and optional reason string. Otherwise, the close frame is sent with no payload.

Callers should not attempt to write WebSocket data after initiating the close. Instead, callers should continue reading until an error occurs. A read returning error::closed indicates a successful connection closure.

Parameters

cr The reason for the close.

handler

The handler to be called when the close operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
    error_code const& ec     // Result of operation
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class HandshakeHandler >

async_return_type< HandshakeHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_handshake	(	string_view	host,
		string_view	target,
		HandshakeHandler &&	handler
	)

Start an asynchronous operation to send an upgrade request and receive the response.

This function is used to asynchronously send the HTTP WebSocket upgrade request and receive the HTTP WebSocket Upgrade response. This function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other operations until this operation completes.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

host	The name of the remote host, required by the HTTP protocol. Copies may be made as needed.
target	The Request Target, which may not be empty, required by the HTTP protocol. Copies of this parameter may be made as needed.
handler	The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( error_code const& ec // Result of operation ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using `boost::asio::io_service::post`.

template<class NextLayer >

template<class HandshakeHandler >

async_return_type< HandshakeHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_handshake	(	response_type &	res,
		string_view	host,
		string_view	target,
		HandshakeHandler &&	handler
	)

Start an asynchronous operation to send an upgrade request and receive the response.

This function is used to asynchronously send the HTTP WebSocket upgrade request and receive the HTTP WebSocket Upgrade response. This function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other operations until this operation completes.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

res	The HTTP Upgrade response returned by the remote endpoint. The caller must ensure this object is valid for at least until the completion handler is invoked.
host	The name of the remote host, required by the HTTP protocol. Copies may be made as needed.
target	The Request Target, which may not be empty, required by the HTTP protocol. Copies of this parameter may be made as needed.
handler	The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( error_code const& ec // Result of operation ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using `boost::asio::io_service::post`.

template<class NextLayer >

template<class RequestDecorator , class HandshakeHandler >

async_return_type< HandshakeHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_handshake_ex	(	string_view	host,
		string_view	target,
		RequestDecorator const &	decorator,
		HandshakeHandler &&	handler
	)

Start an asynchronous operation to send an upgrade request and receive the response.

This function is used to asynchronously send the HTTP WebSocket upgrade request and receive the HTTP WebSocket Upgrade response. This function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other operations until this operation completes.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

host	The name of the remote host, required by the HTTP protocol. Copies may be made as needed.
target	The Request Target, which may not be empty, required by the HTTP protocol. Copies of this parameter may be made as needed.
decorator	A function object which will be called to modify the HTTP request object generated by the implementation. This could be used to set the User-Agent field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( request_type& req );
handler	The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( error_code const& ec // Result of operation ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using `boost::asio::io_service::post`.

template<class NextLayer >

template<class RequestDecorator , class HandshakeHandler >

async_return_type< HandshakeHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_handshake_ex	(	response_type &	res,
		string_view	host,
		string_view	target,
		RequestDecorator const &	decorator,
		HandshakeHandler &&	handler
	)

Start an asynchronous operation to send an upgrade request and receive the response.

This function is used to asynchronously send the HTTP WebSocket upgrade request and receive the HTTP WebSocket Upgrade response. This function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other operations until this operation completes.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

res	The HTTP Upgrade response returned by the remote endpoint. The caller must ensure this object is valid for at least until the completion handler is invoked.
host	The name of the remote host, required by the HTTP protocol. Copies may be made as needed.
target	The Request Target, which may not be empty, required by the HTTP protocol. Copies of this parameter may be made as needed.
decorator	A function object which will be called to modify the HTTP request object generated by the implementation. This could be used to set the User-Agent field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( request_type& req );
handler	The handler to be called when the request completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( error_code const& ec // Result of operation ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using `boost::asio::io_service::post`.

template<class NextLayer >

template<class WriteHandler >

async_return_type< WriteHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_ping	(	ping_data const &	payload,
		WriteHandler &&	handler
	)

Start an asynchronous operation to send a WebSocket ping frame.

This function is used to asynchronously send a ping frame to the stream. The function call always returns immediately. The asynchronous operation will continue until one of the following is true:

The entire ping frame is sent.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other writes until this operation completes.

If a close frame is sent or received before the ping frame is sent, the completion handler will be called with the error set to boost::asio::error::operation_aborted.

Parameters

payload The payload of the ping message, which may be empty.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
    error_code const& ec     // Result of operation
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class WriteHandler >

async_return_type< WriteHandler, void(error_code)> boost::beast::websocket::stream< NextLayer >::async_pong	(	ping_data const &	payload,
		WriteHandler &&	handler
	)

Start an asynchronous operation to send a WebSocket pong frame.

This function is used to asynchronously send a pong frame to the stream. The function call always returns immediately. The asynchronous operation will continue until one of the following is true:

The entire pong frame is sent.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other writes until this operation completes.

The WebSocket protocol allows pong frames to be sent from either end at any time. It is not necessary to first receive a ping in order to send a pong. The remote peer may use the receipt of a pong frame as an indication that the connection is not dead.

If a close frame is sent or received before the pong frame is sent, the completion handler will be called with the error set to boost::asio::error::operation_aborted.

Parameters

payload The payload of the pong message, which may be empty.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
    error_code const& ec     // Result of operation
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class DynamicBuffer , class ReadHandler >

async_return_type< ReadHandler, void(error_code, std::size_t)> boost::beast::websocket::stream< NextLayer >::async_read	(	DynamicBuffer &	buffer,
		ReadHandler &&	handler
	)

Read a message asynchronously

This function is used to asynchronously read a complete message from the stream. The function call always returns immediately. The asynchronous operation will continue until one of the following is true:

A complete message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other reads until this operation completes.

Received message data, if any, is appended to the input area of the buffer. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Because of the need to handle control frames, asynchronous read operations can cause writes to take place. These writes are managed transparently; callers can still have one active asynchronous read and asynchronous write operation pending simultaneously (a user initiated call to async_close counts as a write).

Parameters

buffer A dynamic buffer to hold the message data after any masking or decompression has been applied. This object must remain valid until the handler is called.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:

void handler(
    error_code const& ec,       // Result of operation
    std::size_t bytes_written   // Number of bytes appended to buffer
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class DynamicBuffer , class ReadHandler >

async_return_type< ReadHandler, void(error_code, std::size_t)> boost::beast::websocket::stream< NextLayer >::async_read_some	(	DynamicBuffer &	buffer,
		std::size_t	limit,
		ReadHandler &&	handler
	)

Read part of a message asynchronously

This function is used to asynchronously read part of a message from the stream. The function call always returns immediately. The asynchronous operation will continue until one of the following is true:

Some or all of the message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other reads until this operation completes.

Received message data, if any, is appended to the input area of the buffer. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message. The function is_message_done may be called to determine if the message received by the last read operation is complete.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Because of the need to handle control frames, asynchronous read operations can cause writes to take place. These writes are managed transparently; callers can still have one active asynchronous read and asynchronous write operation pending simultaneously (a user initiated call to async_close counts as a write).

Parameters

buffer	A dynamic buffer to hold the message data after any masking or decompression has been applied. This object must remain valid until the handler is called.
limit	An upper limit on the number of bytes this function will append into the buffer. If this value is zero, then a reasonable size will be chosen automatically.
handler	The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( error_code const& ec, // Result of operation std::size_t bytes_written // Number of bytes appended to buffer ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using `boost::asio::io_service::post`.

template<class NextLayer >

template<class MutableBufferSequence , class ReadHandler >

async_return_type< ReadHandler, void(error_code, std::size_t)> boost::beast::websocket::stream< NextLayer >::async_read_some	(	MutableBufferSequence const &	buffers,
		ReadHandler &&	handler
	)

Read part of a message asynchronously

This function is used to asynchronously read part of a message from the stream. The function call always returns immediately. The asynchronous operation will continue until one of the following is true:

Some or all of the message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's async_read_some and async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other reads until this operation completes.

Received message data, if any, is written to the buffer sequence. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message. The function is_message_done may be called to determine if the message received by the last read operation is complete.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Because of the need to handle control frames, asynchronous read operations can cause writes to take place. These writes are managed transparently; callers can still have one active asynchronous read and asynchronous write operation pending simultaneously (a user initiated call to async_close counts as a write).

Parameters

buffers The buffer sequence into which message data will be placed after any masking or decompresison has been applied. The implementation will make copies of this object as needed, but ownership of the underlying memory is not transferred. The caller is responsible for ensuring that the memory locations pointed to by the buffer sequence remains valid until the completion handler is called.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:

void handler(
    error_code const& ec,       // Result of operation
    std::size_t bytes_written   // Number of bytes written to the buffer sequence
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class ConstBufferSequence , class WriteHandler >

async_return_type< WriteHandler, void(error_code, std::size_t)> boost::beast::websocket::stream< NextLayer >::async_write	(	ConstBufferSequence const &	buffers,
		WriteHandler &&	handler
	)

Start an asynchronous operation to write a message to the stream.

This function is used to asynchronously write a message to the stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The entire message is sent.

An error occurs.

This operation is implemented in terms of one or more calls to the next layer's async_write_some functions, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as stream::async_write, stream::async_write_some, or stream::async_close).

The current setting of the binary option controls whether the message opcode is set to text or binary. If the auto_fragment option is set, the message will be split into one or more frames as necessary. The actual payload contents sent may be transformed as per the WebSocket protocol settings.

Parameters

buffers The buffers containing the entire message payload. The implementation will make copies of this object as needed, but ownership of the underlying memory is not transferred. The caller is responsible for ensuring that the memory locations pointed to by buffers remains valid until the completion handler is called.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
    error_code const& ec,           // Result of operation
    std::size_t bytes_transferred   // Number of bytes written from the
                                    // buffers. If an error occurred,
                                    // this will be less than the sum
                                    // of the buffer sizes.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post.

template<class NextLayer >

template<class ConstBufferSequence , class WriteHandler >

async_return_type< WriteHandler, void(error_code, std::size_t)> boost::beast::websocket::stream< NextLayer >::async_write_some	(	bool	fin,
		ConstBufferSequence const &	buffers,
		WriteHandler &&	handler
	)

Start an asynchronous operation to send a message frame on the stream.

This function is used to asynchronously write a message frame on the stream. This function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The entire frame is sent.

An error occurs.

This operation is implemented in terms of one or more calls to the next layer's async_write_some functions, and is known as a composed operation. The actual payload sent may be transformed as per the WebSocket protocol settings. The program must ensure that the stream performs no other write operations (such as stream::async_write, stream::async_write_some, or stream::async_close).

If this is the beginning of a new message, the message opcode will be set to text or binary as per the current setting of the binary option. The actual payload sent may be transformed as per the WebSocket protocol settings.

Parameters

fin	`true` if this is the last part of the message.
buffers	A object meeting the requirements of ConstBufferSequence which holds the payload data before any masking or compression. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler	The handler to be called when the write completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( error_code const& ec, // Result of operation std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. );

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::auto_fragment ( bool value )

inline

Set the automatic fragmentation option.

Determines if outgoing message payloads are broken up into multiple pieces.

When the automatic fragmentation size is turned on, outgoing message payloads are broken up into multiple frames no larger than the write buffer size.

The default setting is to fragment messages.

Parameters

value A bool indicating if auto fragmentation should be on.

Example: Setting the automatic fragmentation option:
ws.auto_fragment(true);

template<class NextLayer >

bool boost::beast::websocket::stream< NextLayer >::auto_fragment ( ) const

inline

Returns true if the automatic fragmentation option is set.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::binary ( bool value )

inline

Set the binary message option.

This controls whether or not outgoing message opcodes are set to binary or text. The setting is only applied at the start when a caller begins a new message. Changing the opcode after a message is started will only take effect after the current message being sent is complete.

The default setting is to send text messages.

Parameters

value true if outgoing messages should indicate binary, or false if they should indicate text.

Example: Setting the message type to binary.
ws.binary(true);

template<class NextLayer >

bool boost::beast::websocket::stream< NextLayer >::binary ( ) const

inline

Returns true if the binary message option is set.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::close ( close_reason const & cr )

Send a WebSocket close frame.

This function is used to synchronously send a close frame on the stream. The call blocks until one of the following is true:

The close frame finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's write_some functions.

If the close reason specifies a close code other than beast::websocket::close_code::none, the close frame is sent with the close code and optional reason string. Otherwise, the close frame is sent with no payload.

Callers should not attempt to write WebSocket data after initiating the close. Instead, callers should continue reading until an error occurs. A read returning error::closed indicates a successful connection closure.

Parameters

cr	The reason for the close.

Exceptions

system_error Thrown on failure.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::close	(	close_reason const &	cr,
		error_code &	ec
	)

Send a WebSocket close frame.

This function is used to synchronously send a close frame on the stream. The call blocks until one of the following is true:

The close frame finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's write_some functions.

If the close reason specifies a close code other than beast::websocket::close_code::none, the close frame is sent with the close code and optional reason string. Otherwise, the close frame is sent with no payload.

Callers should not attempt to write WebSocket data after initiating the close. Instead, callers should continue reading until an error occurs. A read returning error::closed indicates a successful connection closure.

Parameters

cr	The reason for the close.
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class Callback >

void boost::beast::websocket::stream< NextLayer >::control_callback ( Callback & cb )

inline

Set a callback to be invoked on each incoming control frame.

Sets the callback to be invoked whenever a ping, pong, or close control frame is received during a call to one of the following functions:

Unlike completion handlers, the callback will be invoked for each control frame during a call to any synchronous or asynchronous read function. The operation is passive, with no associated error code, and triggered by reads.

For close frames, the close reason code may be obtained by calling the function reason.

Parameters

cb

The function object to call, which must be invocable with this equivalent signature:

void
callback(
    frame_type kind,       // The type of frame
    string_view payload    // The payload in the frame
);

The implementation type-erases the callback without requiring a dynamic allocation. For this reason, the callback object is passed by a non-constant reference. If the read operation which receives the control frame is an asynchronous operation, the callback will be invoked using the same method as that used to invoke the final handler.

Note: It is not necessary to send a close frame upon receipt of a close frame. The implementation does this automatically. Attempting to send a close frame after a close frame is received will result in undefined behavior.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::control_callback ( )

inline

Reset the control frame callback.

This function removes any previously set control frame callback.

template<class NextLayer >

boost::asio::io_service& boost::beast::websocket::stream< NextLayer >::get_io_service ( )

inline

Return the io_service associated with the stream

This function may be used to obtain the io_service object that the stream uses to dispatch handlers for asynchronous operations.

Returns: A reference to the io_service object that the stream will use to dispatch handlers.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::get_option ( permessage_deflate & o )

inline

Get the permessage-deflate extension options.

template<class NextLayer >

bool boost::beast::websocket::stream< NextLayer >::got_binary ( ) const

inline

Returns true if the latest message data indicates binary.

This function informs the caller of whether the last received message frame represents a message with the binary opcode.

If there is no last message frame, the return value is undefined.

template<class NextLayer >

bool boost::beast::websocket::stream< NextLayer >::got_text ( ) const

inline

Returns true if the latest message data indicates text.

This function informs the caller of whether the last received message frame represents a message with the text opcode.

If there is no last message frame, the return value is undefined.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::handshake	(	string_view	host,
		string_view	target
	)

Send an HTTP WebSocket Upgrade request and receive the response.

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

host	The name of the remote host, required by the HTTP protocol.
target	The Request Target, which may not be empty, required by the HTTP protocol.

Exceptions

system_error Thrown on failure.

Example: websocket::stream<ip::tcp::socket> ws{io_service};
...
try
{
ws.handshake("localhost", "/");
}
catch(...)
{
// An error occurred.
}

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::handshake	(	response_type &	res,
		string_view	host,
		string_view	target
	)

Send an HTTP WebSocket Upgrade request and receive the response.

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

res	The HTTP Upgrade response returned by the remote endpoint.
host	The name of the remote host, required by the HTTP protocol.
target	The Request Target, which may not be empty, required by the HTTP protocol.

Exceptions

system_error Thrown on failure.

Example: websocket::stream<ip::tcp::socket> ws{io_service};
...
try
{
response_type res;
ws.handshake(res, "localhost", "/");
}
catch(...)
{
// An error occurred.
}

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::handshake	(	string_view	host,
		string_view	target,
		error_code &	ec
	)

Send an HTTP WebSocket Upgrade request and receive the response.

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

host	The name of the remote host, required by the HTTP protocol.
target	The Request Target, which may not be empty, required by the HTTP protocol.
ec	Set to indicate what error occurred, if any.

Example: websocket::stream<ip::tcp::socket> ws{io_service};
...
error_code ec;
ws.handshake(host, target, ec);
if(ec)
{
// An error occurred.
}

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::handshake	(	response_type &	res,
		string_view	host,
		string_view	target,
		error_code &	ec
	)

Send an HTTP WebSocket Upgrade request and receive the response.

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

res	The HTTP Upgrade response returned by the remote endpoint. If `ec` is set, the returned value is undefined.
host	The name of the remote host, required by the HTTP protocol.
target	The Request Target, which may not be empty, required by the HTTP protocol.
ec	Set to indicate what error occurred, if any.

Example: websocket::stream<ip::tcp::socket> ws{io_service};
...
error_code ec;
response_type res;
ws.handshake(res, host, target, ec);
if(ec)
{
// An error occurred.
}

template<class NextLayer >

template<class RequestDecorator >

void boost::beast::websocket::stream< NextLayer >::handshake_ex	(	string_view	host,
		string_view	target,
		RequestDecorator const &	decorator
	)

Send an HTTP WebSocket Upgrade request and receive the response.

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

host	The name of the remote host, required by the HTTP protocol.
target	The Request Target, which may not be empty, required by the HTTP protocol.
decorator	A function object which will be called to modify the HTTP request object generated by the implementation. This could be used to set the User-Agent field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( request_type& req );

Exceptions

system_error Thrown on failure.

Example: websocket::stream<ip::tcp::socket> ws{io_service};
...
try
{
ws.handshake("localhost", "/",
[](request_type& req)
{
req.set(field::user_agent, "Beast");
});
}
catch(...)
{
// An error occurred.
}

template<class NextLayer >

template<class RequestDecorator >

void boost::beast::websocket::stream< NextLayer >::handshake_ex	(	response_type &	res,
		string_view	host,
		string_view	target,
		RequestDecorator const &	decorator
	)

Send an HTTP WebSocket Upgrade request and receive the response.

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

res	The HTTP Upgrade response returned by the remote endpoint.
host	The name of the remote host, required by the HTTP protocol.
target	The Request Target, which may not be empty, required by the HTTP protocol.
decorator	A function object which will be called to modify the HTTP request object generated by the implementation. This could be used to set the User-Agent field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( request_type& req );

Exceptions

system_error Thrown on failure.

Example: websocket::stream<ip::tcp::socket> ws{io_service};
...
try
{
response_type res;
ws.handshake(res, "localhost", "/",
[](request_type& req)
{
req.set(field::user_agent, "Beast");
});
}
catch(...)
{
// An error occurred.
}

template<class NextLayer >

template<class RequestDecorator >

void boost::beast::websocket::stream< NextLayer >::handshake_ex	(	string_view	host,
		string_view	target,
		RequestDecorator const &	decorator,
		error_code &	ec
	)

Send an HTTP WebSocket Upgrade request and receive the response.

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

host	The name of the remote host, required by the HTTP protocol.
target	The Request Target, which may not be empty, required by the HTTP protocol.
decorator	A function object which will be called to modify the HTTP request object generated by the implementation. This could be used to set the User-Agent field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( request_type& req );
ec	Set to indicate what error occurred, if any.

Example: websocket::stream<ip::tcp::socket> ws{io_service};
...
error_code ec;
ws.handshake("localhost", "/",
[](request_type& req)
{
req.set(field::user_agent, "Beast");
},
ec);
if(ec)
{
// An error occurred.
}

template<class NextLayer >

template<class RequestDecorator >

void boost::beast::websocket::stream< NextLayer >::handshake_ex	(	response_type &	res,
		string_view	host,
		string_view	target,
		RequestDecorator const &	decorator,
		error_code &	ec
	)

Send an HTTP WebSocket Upgrade request and receive the response.

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

The request is sent and the response is received.

An error occurs on the stream

This function is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

res	The HTTP Upgrade response returned by the remote endpoint.
host	The name of the remote host, required by the HTTP protocol.
target	The Request Target, which may not be empty, required by the HTTP protocol.
decorator	A function object which will be called to modify the HTTP request object generated by the implementation. This could be used to set the User-Agent field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature: void decorator( request_type& req );
ec	Set to indicate what error occurred, if any.

Example: websocket::stream<ip::tcp::socket> ws{io_service};
...
error_code ec;
response_type res;
ws.handshake(res, "localhost", "/",
[](request_type& req)
{
req.set(field::user_agent, "Beast");
},
ec);
if(ec)
{
// An error occurred.
}

template<class NextLayer >

bool boost::beast::websocket::stream< NextLayer >::is_message_done ( ) const

inline

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

template<class NextLayer >

bool boost::beast::websocket::stream< NextLayer >::is_open ( ) const

inline

Returns true if the stream is open.

The stream is open after a successful handshake, and when no error has occurred.

template<class NextLayer >

lowest_layer_type& boost::beast::websocket::stream< NextLayer >::lowest_layer ( )

inline

Get a reference to the lowest layer

This function returns a reference to the lowest layer in a stack of stream layers.

Returns: A reference to the lowest layer in the stack of stream layers.

template<class NextLayer >

lowest_layer_type const& boost::beast::websocket::stream< NextLayer >::lowest_layer ( ) const

inline

Get a reference to the lowest layer

This function returns a reference to the lowest layer in a stack of stream layers.

Returns: A reference to the lowest layer in the stack of stream layers. Ownership is not transferred to the caller.

template<class NextLayer >

next_layer_type& boost::beast::websocket::stream< NextLayer >::next_layer ( )

inline

Get a reference to the next layer

This function returns a reference to the next layer in a stack of stream layers.

Returns: A reference to the next layer in the stack of stream layers.

template<class NextLayer >

next_layer_type const& boost::beast::websocket::stream< NextLayer >::next_layer ( ) const

inline

Get a reference to the next layer

This function returns a reference to the next layer in a stack of stream layers.

Returns: A reference to the next layer in the stack of stream layers.

template<class NextLayer >

stream& boost::beast::websocket::stream< NextLayer >::operator= ( stream< NextLayer > && )

default

Assignment

If NextLayer is move assignable, this function will move-assign a new stream from the existing stream.

Note: The behavior of move assignment on or from streams with active or pending operations is undefined.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::ping ( ping_data const & payload )

Send a WebSocket ping frame.

This function is used to synchronously send a ping frame on the stream. The call blocks until one of the following is true:

The ping frame finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's write_some functions.

Parameters

payload The payload of the ping message, which may be empty.

Exceptions

system_error Thrown on failure.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::ping	(	ping_data const &	payload,
		error_code &	ec
	)

Send a WebSocket ping frame.

This function is used to synchronously send a ping frame on the stream. The call blocks until one of the following is true:

The ping frame finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's write_some functions.

Parameters

payload	The payload of the ping message, which may be empty.
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::pong ( ping_data const & payload )

Send a WebSocket pong frame.

This function is used to synchronously send a pong frame on the stream. The call blocks until one of the following is true:

The pong frame finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's write_some functions.

The WebSocket protocol allows pong frames to be sent from either end at any time. It is not necessary to first receive a ping in order to send a pong. The remote peer may use the receipt of a pong frame as an indication that the connection is not dead.

Parameters

payload The payload of the pong message, which may be empty.

Exceptions

system_error Thrown on failure.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::pong	(	ping_data const &	payload,
		error_code &	ec
	)

Send a WebSocket pong frame.

This function is used to synchronously send a pong frame on the stream. The call blocks until one of the following is true:

The pong frame finishes sending.

An error occurs on the stream.

This function is implemented in terms of one or more calls to the next layer's write_some functions.

The WebSocket protocol allows pong frames to be sent from either end at any time. It is not necessary to first receive a ping in order to send a pong. The remote peer may use the receipt of a pong frame as an indication that the connection is not dead.

Parameters

payload	The payload of the pong message, which may be empty.
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class DynamicBuffer >

std::size_t boost::beast::websocket::stream< NextLayer >::read ( DynamicBuffer & buffer )

Read a message

This function is used to synchronously read a complete message from the stream. The call blocks until one of the following is true:

A complete message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

Received message data, if any, is appended to the input area of the buffer. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Returns: The number of message payload bytes appended to the buffer.

Parameters

buffer A dynamic buffer to hold the message data after any masking or decompression has been applied.

Exceptions

system_error Thrown to indicate an error. The corresponding error code may be retrieved from the exception object for inspection.

template<class NextLayer >

template<class DynamicBuffer >

std::size_t boost::beast::websocket::stream< NextLayer >::read	(	DynamicBuffer &	buffer,
		error_code &	ec
	)

Read a message

This function is used to synchronously read a complete message from the stream. The call blocks until one of the following is true:

A complete message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

Received message data, if any, is appended to the input area of the buffer. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Returns: The number of message payload bytes appended to the buffer.

Parameters

buffer	A dynamic buffer to hold the message data after any masking or decompression has been applied.
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::read_message_max ( std::size_t amount )

inline

Set the maximum incoming message size option.

Sets the largest permissible incoming message size. Message frame fields indicating a size that would bring the total message size over this limit will cause a protocol failure.

The default setting is 16 megabytes. A value of zero indicates a limit of the maximum value of a std::uint64_t.

Example: Setting the maximum read message size.
ws.read_message_max(65536);

Parameters

amount The limit on the size of incoming messages.

template<class NextLayer >

std::size_t boost::beast::websocket::stream< NextLayer >::read_message_max ( ) const

inline

Returns the maximum incoming message size setting.

template<class NextLayer >

std::size_t boost::beast::websocket::stream< NextLayer >::read_size_hint ( std::size_t initial_size = +tcp_frame_size ) const

Returns a suggested maximum buffer size for the next call to read.

This function returns a reasonable upper limit on the number of bytes for the size of the buffer passed in the next call to read. The number is determined by the state of the current frame and whether or not the permessage-deflate extension is enabled.

Parameters

initial_size A non-zero size representing the caller's desired buffer size for when there is no information which may be used to calculate a more specific value. For example, when reading the first frame header of a message.

template<class NextLayer >

template<class DynamicBuffer , class >

std::size_t boost::beast::websocket::stream< NextLayer >::read_size_hint ( DynamicBuffer & buffer ) const

Returns a suggested maximum buffer size for the next call to read.

This function returns a reasonable upper limit on the number of bytes for the size of the buffer passed in the next call to read. The number is determined by the state of the current frame and whether or not the permessage-deflate extension is enabled.

Parameters

buffer The buffer which will be used for reading. The implementation will query the buffer to obtain the optimum size of a subsequent call to buffer.prepare based on the state of the current frame, if any.

template<class NextLayer >

template<class DynamicBuffer >

std::size_t boost::beast::websocket::stream< NextLayer >::read_some	(	DynamicBuffer &	buffer,
		std::size_t	limit
	)

Read part of a message

This function is used to synchronously read some message data from the stream. The call blocks until one of the following is true:

Some or all of the message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

Received message data, if any, is appended to the input area of the buffer. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message. The function is_message_done may be called to determine if the message received by the last read operation is complete.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Returns: The number of message payload bytes appended to the buffer.

Parameters

buffer	A dynamic buffer to hold the message data after any masking or decompression has been applied.
limit	An upper limit on the number of bytes this function will append into the buffer. If this value is zero, then a reasonable size will be chosen automatically.

Exceptions

system_error Thrown to indicate an error. The corresponding error code may be retrieved from the exception object for inspection.

template<class NextLayer >

template<class DynamicBuffer >

std::size_t boost::beast::websocket::stream< NextLayer >::read_some	(	DynamicBuffer &	buffer,
		std::size_t	limit,
		error_code &	ec
	)

Read part of a message

This function is used to synchronously read some message data from the stream. The call blocks until one of the following is true:

Some or all of the message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

Received message data, if any, is appended to the input area of the buffer. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message. The function is_message_done may be called to determine if the message received by the last read operation is complete.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Returns: The number of message payload bytes appended to the buffer.

Parameters

buffer	A dynamic buffer to hold the message data after any masking or decompression has been applied.
limit	An upper limit on the number of bytes this function will append into the buffer. If this value is zero, then a reasonable size will be chosen automatically.
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

template<class MutableBufferSequence >

std::size_t boost::beast::websocket::stream< NextLayer >::read_some ( MutableBufferSequence const & buffers )

Read part of a message

This function is used to synchronously read some message data from the stream. The call blocks until one of the following is true:

Some or all of the message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

Received message data, if any, is written to the buffer sequence. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message. The function is_message_done may be called to determine if the message received by the last read operation is complete.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Returns: The number of message payload bytes written to the buffer sequence.

Parameters

buffers A buffer sequence to hold the message data after any masking or decompression has been applied.

Exceptions

system_error Thrown to indicate an error. The corresponding error code may be retrieved from the exception object for inspection.

template<class NextLayer >

template<class MutableBufferSequence >

std::size_t boost::beast::websocket::stream< NextLayer >::read_some	(	MutableBufferSequence const &	buffers,
		error_code &	ec
	)

Read part of a message

This function is used to synchronously read some message data from the stream. The call blocks until one of the following is true:

Some or all of the message is received.

A close frame is received. In this case the error indicated by the function will be error::closed.

An error occurs on the stream.

This operation is implemented in terms of one or more calls to the next layer's read_some and write_some functions.

Received message data, if any, is written to the buffer sequence. The functions got_binary and got_text may be used to query the stream and determine the type of the last received message. The function is_message_done may be called to determine if the message received by the last read operation is complete.

While this operation is active, the implementation will read incoming control frames and handle them automatically as follows:

The control_callback will be invoked for each control frame.

For each received ping frame, a pong frame will be automatically sent.

If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error error::closed will be indicated.

Returns: The number of message payload bytes written to the buffer sequence.

Parameters

buffers	A buffer sequence to hold the message data after any masking or decompression has been applied.
ec	Set to indicate what error occurred, if any.

template<class NextLayer >

close_reason const& boost::beast::websocket::stream< NextLayer >::reason ( ) const

inline

Returns the close reason received from the peer.

This is only valid after a read completes with error::closed.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::set_option ( permessage_deflate const & o )

Set the permessage-deflate extension options.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::text ( bool value )

inline

Set the text message option.

This controls whether or not outgoing message opcodes are set to binary or text. The setting is only applied at the start when a caller begins a new message. Changing the opcode after a message is started will only take effect after the current message being sent is complete.

The default setting is to send text messages.

Parameters

value true if outgoing messages should indicate text, or false if they should indicate binary.

Example: Setting the message type to text.
ws.text(true);

template<class NextLayer >

bool boost::beast::websocket::stream< NextLayer >::text ( ) const

inline

Returns true if the text message option is set.

template<class NextLayer >

template<class ConstBufferSequence >

std::size_t boost::beast::websocket::stream< NextLayer >::write ( ConstBufferSequence const & buffers )

Write a message to the stream.

This function is used to synchronously write a message to the stream. The call blocks until one of the following conditions is met:

The entire message is sent.

An error occurs.

This operation is implemented in terms of one or more calls to the next layer's write_some function.

The current setting of the binary option controls whether the message opcode is set to text or binary. If the auto_fragment option is set, the message will be split into one or more frames as necessary. The actual payload contents sent may be transformed as per the WebSocket protocol settings.

Parameters

buffers The buffers containing the entire message payload. The implementation will make copies of this object as needed, but ownership of the underlying memory is not transferred. The caller is responsible for ensuring that the memory locations pointed to by buffers remains valid until the completion handler is called.

Returns: The number of bytes written from the buffers. If an error occurred, this will be less than the sum of the buffer sizes.

Exceptions

system_error Thrown on failure.

Note: This function always sends an entire message. To send a message in fragments, use write_some.

template<class NextLayer >

template<class ConstBufferSequence >

std::size_t boost::beast::websocket::stream< NextLayer >::write	(	ConstBufferSequence const &	buffers,
		error_code &	ec
	)

Write a message to the stream.

This function is used to synchronously write a message to the stream. The call blocks until one of the following conditions is met:

The entire message is sent.

An error occurs.

This operation is implemented in terms of one or more calls to the next layer's write_some function.

The current setting of the binary option controls whether the message opcode is set to text or binary. If the auto_fragment option is set, the message will be split into one or more frames as necessary. The actual payload contents sent may be transformed as per the WebSocket protocol settings.

Parameters

buffers The buffers containing the entire message payload. The implementation will make copies of this object as needed, but ownership of the underlying memory is not transferred. The caller is responsible for ensuring that the memory locations pointed to by buffers remains valid until the completion handler is called.

Returns: The number of bytes written from the buffers. If an error occurred, this will be less than the sum of the buffer sizes.

Parameters

ec	Set to indicate what error occurred, if any.

Exceptions

system_error Thrown on failure.

Note: This function always sends an entire message. To send a message in fragments, use write_some.

template<class NextLayer >

void boost::beast::websocket::stream< NextLayer >::write_buffer_size ( std::size_t amount )

inline

Set the write buffer size option.

Sets the size of the write buffer used by the implementation to send frames. The write buffer is needed when masking payload data in the client role, compressing frames, or auto-fragmenting message data.

Lowering the size of the buffer can decrease the memory requirements for each connection, while increasing the size of the buffer can reduce the number of calls made to the next layer to write data.

The default setting is 4096. The minimum value is 8.

The write buffer size can only be changed when the stream is not open. Undefined behavior results if the option is modified after a successful WebSocket handshake.

Example: Setting the write buffer size.
ws.write_buffer_size(8192);

Parameters

amount The size of the write buffer in bytes.

template<class NextLayer >

std::size_t boost::beast::websocket::stream< NextLayer >::write_buffer_size ( ) const

inline

Returns the size of the write buffer.

template<class NextLayer >

template<class ConstBufferSequence >

std::size_t boost::beast::websocket::stream< NextLayer >::write_some	(	bool	fin,
		ConstBufferSequence const &	buffers
	)

Write partial message data on the stream.

This function is used to write some or all of a message's payload to the stream. The call will block until one of the following conditions is true:

A frame is sent.

Message data is transferred to the write buffer.

An error occurs.

This operation is implemented in terms of one or more calls to the stream's write_some function.

If this is the beginning of a new message, the message opcode will be set to text or binary as per the current setting of the binary option. The actual payload sent may be transformed as per the WebSocket protocol settings.

Parameters

fin	`true` if this is the last part of the message.
buffers	The input buffer sequence holding the data to write.

Returns: The number of bytes written from the buffers. If an error occurred, this will be less than the sum of the buffer sizes.

Exceptions

system_error Thrown on failure.

template<class NextLayer >

template<class ConstBufferSequence >

std::size_t boost::beast::websocket::stream< NextLayer >::write_some	(	bool	fin,
		ConstBufferSequence const &	buffers,
		error_code &	ec
	)

Write partial message data on the stream.

This function is used to write some or all of a message's payload to the stream. The call will block until one of the following conditions is true:

A frame is sent.

Message data is transferred to the write buffer.

An error occurs.

This operation is implemented in terms of one or more calls to the stream's write_some function.

If this is the beginning of a new message, the message opcode will be set to text or binary as per the current setting of the binary option. The actual payload sent may be transformed as per the WebSocket protocol settings.

Parameters

fin	`true` if this is the last part of the message.

Returns: The number of bytes written from the buffers. If an error occurred, this will be less than the sum of the buffer sizes.

Parameters

ec	Set to indicate what error occurred, if any.

Returns: The number of bytes consumed in the input buffers.

Friends And Related Function Documentation

template<class NextLayer >

friend class close_test

friend

template<class NextLayer >

friend class frame_test

friend

template<class NextLayer >

friend class ping_test

friend

template<class NextLayer >

friend class read_test

friend

template<class NextLayer >

friend class stream_test

friend

template<class NextLayer >

friend class write_test

friend

The documentation for this class was generated from the following files:

3pp/beast/boost/beast/websocket/stream.hpp
3pp/beast/boost/beast/websocket/impl/accept.ipp
3pp/beast/boost/beast/websocket/impl/close.ipp
3pp/beast/boost/beast/websocket/impl/handshake.ipp
3pp/beast/boost/beast/websocket/impl/ping.ipp
3pp/beast/boost/beast/websocket/impl/read.ipp
3pp/beast/boost/beast/websocket/impl/stream.ipp
3pp/beast/boost/beast/websocket/impl/write.ipp

Classes

Public Types

Public Member Functions

Friends

Detailed Description

template<class NextLayer> class boost::beast::websocket::stream< NextLayer >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

template<class NextLayer>
class boost::beast::websocket::stream< NextLayer >