[/
    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]