boost_beast/doc/7_1_streams.qbk

[/
    Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section:streams Creating Streams]

The interface to the WebSocket implementation is a single template class
[link beast.ref.websocket__stream `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_service` argument is forwarded to the wrapped
socket's constructor:

[ws_snippet_2]

[heading 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 `io_service`
and `ssl::context` arguments are forwarded to the wrapped stream's constructor:

[wss_snippet_1]
[wss_snippet_2]

[note
    Code which declares stream objects using Asio SSL types
    must include the file `<beast/websocket/ssl.hpp>`.
]

[heading 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:

[ws_snippet_3]

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:

[ws_snippet_4]

Once the WebSocket stream wrapper is created, the wrapped object may be
accessed by calling
[link beast.ref.websocket__stream.next_layer.overload1 `stream::next_layer`]:

[ws_snippet_5]

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

[endsect]