Boost C++ Libraries

The interface to the WebSocket implementation is a single template class stream which 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 during construction of the stream wrapper are passed to next layer's constructor.

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.