Boost C++ Libraries

The interface to the WebSocket implementation is a single template class stream:

// A WebSocket stream
template<
    class NextLayer,
    bool deflateSupported = true>
class stream;

An instance of the stream wraps an existing network transport object or other type of octet oriented stream. The wrapped object is called the "next layer" and must meet the requirements of SyncStream if synchronous operations are performed, AsyncStream if asynchronous operations are performed, or both. Any arguments supplied to the constructor of the stream wrapper are forwarded to next layer's constructor.

The value of deflateSupported determines if the stream will support (but not require) the permessage-deflate extension (rfc7692) negotiation during handshaking. This extension allows messages to be optionally automatically compressed using the deflate algorithm prior to transmission. When this boolean value is false, the extension is disabled. Applications which do not intend to use the permessage-deflate extension may set the value to false to enjoy a reduction in the size of the compiled output, as the necessary compression code (included with Beast) will not be compiled in.

Here we declare a websocket stream over a TCP/IP socket with ownership of the socket. The io_context argument is forwarded to the wrapped socket's constructor:

stream<boost::asio::ip::tcp::socket> ws{ioc};

Using SSL

To use WebSockets over SSL, use an instance of the boost::asio::ssl::stream class template as the template type for the stream. The required boost::asio::io_context and boost::asio::ssl::context arguments are forwarded to the wrapped stream's constructor:

#include <boost/beast/websocket/ssl.hpp>
#include <boost/asio/ssl.hpp>

boost::asio::ssl::context ctx{boost::asio::ssl::context::sslv23};
stream<boost::asio::ssl::stream<boost::asio::ip::tcp::socket>> wss{ioc, ctx};

	Important
	Code which declares websocket stream objects using Asio SSL types must include the file <boost/beast/websocket/ssl.hpp>.

Non-owning References

If a socket type supports move construction, a websocket stream may be constructed around the already existing socket by invoking the move constructor signature:

stream<boost::asio::ip::tcp::socket> ws{std::move(sock)};

Or, the wrapper can be constructed with a non-owning reference. In this case, the caller is responsible for managing the lifetime of the underlying socket being wrapped:

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

Once the WebSocket stream wrapper is created, the wrapped object may be accessed by calling stream::next_layer:

ws.next_layer().shutdown(boost::asio::ip::tcp::socket::shutdown_send);

	Warning
	Initiating operations on the next layer while websocket operations are being performed may result in undefined behavior.

Non-Blocking Mode

Please note that websocket streams do not support non-blocking modes.