158 lines
5.6 KiB
Plaintext
158 lines
5.6 KiB
Plaintext
[/
|
|
Copyright (c) 2016-2019 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)
|
|
|
|
Official repository: https://github.com/boostorg/beast
|
|
]
|
|
|
|
[section:using_websocket WebSocket]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
The WebSocket Protocol enables two-way communication between a client running
|
|
untrusted code in a controlled environment to a remote host that has opted-in
|
|
to communications from that code. The protocol consists of an opening handshake
|
|
followed by basic message framing, layered over TCP. The goal of this
|
|
technology is to provide a mechanism for browser-based applications needing
|
|
two-way communication with servers without relying on opening multiple HTTP
|
|
connections.
|
|
|
|
Beast provides developers with a robust WebSocket implementation
|
|
built on Boost.Asio with a consistent asynchronous model using a modern C++
|
|
approach.
|
|
|
|
[note
|
|
This documentation assumes familiarity with __Asio__ and
|
|
the protocol specification described in __rfc6455__.
|
|
Sample code and identifiers appearing in this section is written
|
|
as if these declarations are in effect:
|
|
|
|
[code_websocket_1a]
|
|
'''<?linebreak?>'''
|
|
[code_websocket_1b]
|
|
]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[heading Construction]
|
|
|
|
A WebSocket connection requires a stateful object, represented in Beast by a
|
|
single class template
|
|
[link beast.ref.boost__beast__websocket__stream `websocket::stream`].
|
|
The interface uses the layered stream model. A websocket stream object contains
|
|
another stream object, called the "next layer", which it uses to perform I/O.
|
|
Descriptions of each template parameter follow:
|
|
|
|
[code_websocket_1h]
|
|
|
|
[table WebSocket Stream Template Parameters
|
|
[[Name][Description]]
|
|
[
|
|
[`NextLayer`]
|
|
[
|
|
The type of the next layer. An object of this type will be constructed
|
|
and maintained for the lifetime of the stream. All reads and writes
|
|
will go through the next layer. This type must meet the requirements
|
|
of either __SyncStream__, __AsyncStream__, or both, depending on the
|
|
style of I/O that is to be performed.
|
|
]
|
|
][
|
|
[`deflateSupported`]
|
|
[
|
|
When this value is `true`, the stream will support (but not require)
|
|
the [@https://tools.ietf.org/html/rfc7692 permessage-deflate extension].
|
|
Whether or not the stream actually requests or accepts the extension
|
|
during a handshake depends on a separate configurable option.
|
|
|
|
When the value is `false` the extension is disabled. Streams will
|
|
never request the extension in the client role or accept a request
|
|
for the extension in the server role. An additional benefit of
|
|
disabling the extension is that compilation will be faster, and
|
|
the resulting program executable will contain less code.
|
|
]
|
|
]]
|
|
|
|
When a stream is constructed, any arguments provided to the constructor are
|
|
forwarded to the next layer object's constructor. This declares a stream
|
|
over a plain TCP/IP socket using an I/O context:
|
|
|
|
[code_websocket_1f]
|
|
|
|
[tip
|
|
Websocket streams use their own protocol-specific timeout feature. When
|
|
using a websocket stream with the
|
|
[link beast.ref.boost__beast__tcp_stream `tcp_stream`] or
|
|
[link beast.ref.boost__beast__basic_stream `basic_stream`]
|
|
class template, timeouts should be disabled on the TCP or basic stream
|
|
after the connection is established, otherwise the behavior of the
|
|
stream is undefined.
|
|
]
|
|
|
|
As with most I/O objects, a websocket stream is [*not thread-safe]. Undefined
|
|
behavior results if two different threads access the object concurrently.
|
|
For multi-threaded programs, the `tcp_stream` can be constructed from an
|
|
executor, in this case a strand. The stream declared below will use a
|
|
strand to invoke all completion handlers:
|
|
|
|
[code_websocket_2f]
|
|
|
|
If the next layer supports move-construction, then the websocket stream can be
|
|
constructed from a moved-from object.
|
|
|
|
[code_websocket_3f]
|
|
|
|
The next layer may be accessed by calling
|
|
[link beast.ref.boost__beast__websocket__stream.next_layer.overload1 `stream::next_layer`].
|
|
|
|
[code_websocket_4f]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[heading Using SSL]
|
|
|
|
To use WebSockets over SSL, use an instance of the __ssl_stream__
|
|
class template as the template type for the stream. The required
|
|
__io_context__ and __ssl_context__ arguments are forwarded to the
|
|
wrapped stream's constructor:
|
|
|
|
[code_websocket_5f]
|
|
|
|
[important
|
|
Code which declares websocket stream objects using Asio SSL types
|
|
must include the file [include_file boost/beast/websocket/ssl.hpp].
|
|
]
|
|
|
|
As before, the underlying SSL stream may be accessed by calling `next_layer`.
|
|
|
|
[code_websocket_6f]
|
|
|
|
With multi-layered streams such as the one declared above, accessing an
|
|
individual layer can be cumbersome when using chained calls to `next_layer`.
|
|
The function
|
|
[link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`]
|
|
returns the last stream in a stack of layers in a layered stream. Here we
|
|
access the lowest layer to cancel all outstanding I/O.
|
|
|
|
[code_websocket_7f]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[heading Non-Blocking Mode]
|
|
|
|
Please note that websocket streams do not support non-blocking modes.
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[include 01_connecting.qbk]
|
|
[include 02_handshaking.qbk]
|
|
[include 03_decorator.qbk]
|
|
[include 04_messages.qbk]
|
|
[include 05_control_frames.qbk]
|
|
[include 06_timeouts.qbk]
|
|
[include 07_teardown.qbk]
|
|
[include 08_notes.qbk]
|
|
|
|
[endsect]
|