forked from boostorg/beast
79 lines
2.8 KiB
Plaintext
79 lines
2.8 KiB
Plaintext
|
[/
|
||
|
|
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
|
||
|
|
toinclude 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 invoke 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]
|