[/
    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 `websocket::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:
```
    boost::asio::io_service ios;
    beast::websocket::stream<boost::asio::ip::tcp::socket> ws{ios};
```

[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:
```
    #include <beast/websocket/ssl.hpp>
    #include <boost/asio/ssl.hpp>

    boost::asio::io_service ios;
    boost::asio::ssl::context ctx{boost::asio::ssl::context::sslv23};
    beast::websocket::stream<boost::asio::ssl::stream<boost::asio::ip::tcp::socket> ws{ios, ctx};
```

[note
    Code which declares stream objects using Asio SSL types must
    to 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:
```
    ...
    beast::websocket::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:
```
    ...
    beast::websocket::stream<boost::asio::ip::tcp::socket&> ws{sock};
```

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`]:
```
    boost::asio::ssl::context ctx{boost::asio::ssl::context::sslv23};
    beast::websocket::stream<boost::asio::ssl::stream<boost::asio::ip::tcp::socket>> ws{ios, ctx};
    ...
    ws.next_layer().shutdown(); // ssl::stream shutdown
```

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

[endsect]