boost::beast::websocket Namespace Reference

Namespaces
	detail

Classes
struct	close_reason
struct	permessage_deflate
class	stream

Typedefs
using	reason_string = static_string< 123, char >
	The type representing the reason string in a close frame. More...
using	ping_data = static_string< 125, char >
	The type representing the payload of ping and pong messages. More...
using	request_type = http::request< http::empty_body >
	The type of object holding HTTP Upgrade requests. More...
using	response_type = http::response< http::string_body >
	The type of object holding HTTP Upgrade responses. More...

Enumerations
enum	error { error::closed = 1, error::failed, error::handshake_failed, error::buffer_overflow }
	Error codes returned from beast::websocket::stream operations. More...
enum	close_code : std::uint16_t {   normal = 1000, going_away = 1001, protocol_error = 1002, unknown_data = 1003,   bad_payload = 1007, policy_error = 1008, too_big = 1009, needs_extension = 1010,   internal_error = 1011, service_restart = 1012, try_again_later = 1013, none = 0,   reserved1 = 1004, no_status = 1005, abnormal = 1006, reserved2 = 1014,   reserved3 = 1015 }
enum	role_type { role_type::client, role_type::server }
enum	frame_type { frame_type::close, frame_type::ping, frame_type::pong }

Functions
error_code	make_error_code (error e)
template<class Allocator >
bool	is_upgrade (http::header< true, http::basic_fields< Allocator >> const &req)
template<class AsyncStream >
void	teardown (role_type, boost::asio::ssl::stream< AsyncStream > &stream, error_code &ec)
template<class AsyncStream , class TeardownHandler >
void	async_teardown (role_type, boost::asio::ssl::stream< AsyncStream > &stream, TeardownHandler &&handler)
void	teardown (role_type role, boost::asio::ip::tcp::socket &socket, error_code &ec)
template<class TeardownHandler >
void	async_teardown (role_type role, boost::asio::ip::tcp::socket &socket, TeardownHandler &&handler)
template<class SyncStream >
void	teardown (role_type role, boost::asio::ssl::stream< SyncStream > &stream, error_code &ec)
template<class Socket >
void	teardown (role_type role, Socket &socket, error_code &ec)
template<class Socket , class TeardownHandler >
void	async_teardown (role_type role, Socket &socket, TeardownHandler &&handler)

Typedef Documentation

using boost::beast::websocket::ping_data = typedef static_string<125, char>

The type representing the payload of ping and pong messages.

using boost::beast::websocket::reason_string = typedef static_string<123, char>

The type representing the reason string in a close frame.

using boost::beast::websocket::request_type = typedef http::request<http::empty_body>

The type of object holding HTTP Upgrade requests.

using boost::beast::websocket::response_type = typedef http::response<http::string_body>

The type of object holding HTTP Upgrade responses.

Enumeration Type Documentation

enum boost::beast::websocket::close_code : std::uint16_t

Close status codes.

These codes accompany close frames.

See also

RFC 6455 7.4.1 Defined Status Codes

Enumerator
normal	Normal closure; the connection successfully completed whatever purpose for which it was created.
going_away	The endpoint is going away, either because of a server failure or because the browser is navigating away from the page that opened the connection.
protocol_error	The endpoint is terminating the connection due to a protocol error.
unknown_data	The connection is being terminated because the endpoint received data of a type it cannot accept (for example, a text-only endpoint received binary data).
bad_payload	The endpoint is terminating the connection because a message was received that contained inconsistent data (e.g., non-UTF-8 data within a text message).
policy_error	The endpoint is terminating the connection because it received a message that violates its policy. This is a generic status code, used when codes 1003 and 1009 are not suitable.
too_big	The endpoint is terminating the connection because a data frame was received that is too large.
needs_extension	The client is terminating the connection because it expected the server to negotiate one or more extension, but the server didn't.
internal_error	The server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.
service_restart	The server is terminating the connection because it is restarting.
try_again_later	The server is terminating the connection due to a temporary condition, e.g. it is overloaded and is casting off some of its clients.
none	Used internally to mean "no error" This code is reserved and may not be sent.
reserved1	Reserved for future use by the WebSocket standard. This code is reserved and may not be sent.
no_status	No status code was provided even though one was expected. This code is reserved and may not be sent.
abnormal	Connection was closed without receiving a close frame This code is reserved and may not be sent.
reserved2	Reserved for future use by the WebSocket standard. This code is reserved and may not be sent.
reserved3	Reserved for future use by the WebSocket standard. This code is reserved and may not be sent.

enum boost::beast::websocket::error

strong

Error codes returned from beast::websocket::stream operations.

Enumerator
closed	Both sides performed a WebSocket close.
failed	WebSocket connection failed, protocol violation.
handshake_failed	Upgrade handshake failed.
buffer_overflow	buffer overflow

enum boost::beast::websocket::frame_type

strong

The type of received control frame.

Values of this type are passed to the control frame callback set using stream::control_callback.

Enumerator
close	A close frame was received.
ping	A ping frame was received.
pong	A pong frame was received.

enum boost::beast::websocket::role_type

strong

The role of the websocket stream endpoint.

Whether the endpoint is a client or server affects the behavior of the Close the WebSocket Connection operation described in rfc6455 section 7.1.1. The shutdown behavior depends on the type of the next layer template parameter used to construct the stream. Other next layer types including user-defined types may implement different role-based behavior when performing the close operation.

The default implementation for stream when the next layer type is a boost::asio::ip::tcp::socket behaves as follows:

• In the client role, a TCP/IP shutdown is sent after reading all remaining data on the connection.

• In the server role, a TCP/IP shutdown is sent before reading all remaining data on the connection.

When the next layer type is a boost::asio::ssl::stream, the connection is closed by performing the SSL closing handshake corresponding to the role type, client or server.

See also

https://tools.ietf.org/html/rfc6455#section-7.1.1

Enumerator
client	The stream is operating as a client.
server	The stream is operating as a server.

Function Documentation

template<class AsyncStream , class TeardownHandler >

void boost::beast::websocket::async_teardown ( role_type  role, boost::asio::ssl::stream< AsyncStream > &  stream, TeardownHandler &&  handler  )

inline

Start tearing down a boost::asio::ssl::stream.

This begins tearing down a connection asynchronously. The implementation will call the overload of this function based on the Stream parameter used to consruct the socket. When Stream is a user defined type, and not a boost::asio::ip::tcp::socket or any boost::asio::ssl::stream, callers are responsible for providing a suitable overload of this function.

Parameters

role	The role of the local endpoint
stream	The stream to tear down.
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& error // 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 Socket , class TeardownHandler >

void boost::beast::websocket::async_teardown	(	role_type	role,
		Socket &	socket,
		TeardownHandler &&	handler
	)

Start tearing down a connection.

This begins tearing down a connection asynchronously. The implementation will call the overload of this function based on the Socket parameter used to consruct the socket. When Stream is a user defined type, and not a boost::asio::ip::tcp::socket or any boost::asio::ssl::stream, callers are responsible for providing a suitable overload of this function.

Parameters

role	The role of the local endpoint
socket	The socket to tear down.
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& error // 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 TeardownHandler >

void boost::beast::websocket::async_teardown ( role_type  role, boost::asio::ip::tcp::socket &  socket, TeardownHandler &&  handler  )

inline

Start tearing down a boost::asio::ip::tcp::socket.

This begins tearing down a connection asynchronously. The implementation will call the overload of this function based on the Stream parameter used to consruct the socket. When Stream is a user defined type, and not a boost::asio::ip::tcp::socket or any boost::asio::ssl::stream, callers are responsible for providing a suitable overload of this function.

Parameters

role	The role of the local endpoint
socket	The socket to tear down.
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& error // 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 Allocator >

bool boost::beast::websocket::is_upgrade

(

beast::http::header< true, http::basic_fields< Allocator >> const &

req

)

Returns true if the specified HTTP request is a WebSocket Upgrade.

This function returns true when the passed HTTP Request indicates a WebSocket Upgrade. It does not validate the contents of the fields: it just trivially accepts requests which could only possibly be a valid or invalid WebSocket Upgrade message.

Callers who wish to manually read HTTP requests in their server implementation can use this function to determine if the request should be routed to an instance of websocket::stream.

Example

void handle_connection(boost::asio::ip::tcp::socket& sock)
{
    boost::beast::flat_buffer buffer;
    boost::beast::http::request<boost::beast::http::string_body> req;
    boost::beast::http::read(sock, buffer, req);
    if(boost::beast::websocket::is_upgrade(req))
    {
        boost::beast::websocket::stream<decltype(sock)> ws{std::move(sock)};
        ws.accept(req);
    }
}

Parameters

req	The HTTP Request object to check.

Returns

true if the request is a WebSocket Upgrade.

error_code boost::beast::websocket::make_error_code ( error  e )

inline

template<class AsyncStream >

void boost::beast::websocket::teardown	(	role_type	,
		boost::asio::ssl::stream< AsyncStream > &	stream,
		error_code &	ec
	)

template<class SyncStream >

void boost::beast::websocket::teardown	(	role_type	role,
		boost::asio::ssl::stream< SyncStream > &	stream,
		error_code &	ec
	)

Tear down a boost::asio::ssl::stream.

This tears down a connection. The implementation will call the overload of this function based on the Stream parameter used to consruct the socket. When Stream is a user defined type, and not a boost::asio::ip::tcp::socket or any boost::asio::ssl::stream, callers are responsible for providing a suitable overload of this function.

Parameters

role	The role of the local endpoint
stream	The stream to tear down.
ec	Set to the error if any occurred.

template<class Socket >

void boost::beast::websocket::teardown	(	role_type	role,
		Socket &	socket,
		error_code &	ec
	)

Tear down a connection.

This tears down a connection. The implementation will call the overload of this function based on the Socket parameter used to consruct the socket. When Socket is a user defined type, and not a boost::asio::ip::tcp::socket or any boost::asio::ssl::stream, callers are responsible for providing a suitable overload of this function.

Parameters

role	The role of the local endpoint
socket	The socket to tear down.
ec	Set to the error if any occurred.

void boost::beast::websocket::teardown ( role_type  role, boost::asio::ip::tcp::socket &  socket, error_code &  ec  )

inline

Tear down a boost::asio::ip::tcp::socket.

This tears down a connection. The implementation will call the overload of this function based on the Stream parameter used to consruct the socket. When Stream is a user defined type, and not a boost::asio::ip::tcp::socket or any boost::asio::ssl::stream, callers are responsible for providing a suitable overload of this function.

Parameters

role	The role of the local endpoint
socket	The socket to tear down.
ec	Set to the error if any occurred.