[/
    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:messages Messages]

Once a websocket session is established, messages can be sent unsolicited by
either peer at any time. A message is made up of one or more ['messages frames].
Each frame is prefixed with the size of the payload in bytes, followed by the
data. A frame also contains a flag (called 'fin') indicating whether or not it
is the last frame of the message. When a message is made up from only one frame,
it is possible to know immediately what the size of the message will be.
Otherwise, the total size of the message can only be determined once
the last frame is received.

The boundaries between frames of a multi-frame message are not not considered
part of the message. Intermediaries such as proxies which forward the websocket
traffic are free to "reframe" (split frames and combine them) the message in
arbitrary ways. These intermediaries include Beast, which can reframe messages
automatically in some cases depending on the options set on the stream.

[caution
    An algorithm should never depend on the way that incoming or outgoing
    messages are split up into frames.
]

Messages can be either text or binary. A message sent as text must contain
consist of valid utf8, while a message sent as binary may contain arbitrary
data. In addition to message frames, websocket provides ['control frames]
in the form of ping, pong, and close messages which have a small upper limit
on their payload size. Depending on how a message is framed, control frames
may have more opportunities to be sent in-between.

[heading Sending]

These stream members are used to write websocket messages:

[table WebSocket Stream Write Operations
[[Function][Description]]
[
    [
        [link beast.ref.boost__beast__websocket__stream.write.overload2 `write`],
        [link beast.ref.boost__beast__websocket__stream.async_write `async_write`]
    ][
        Send a buffer sequence as a complete message.
    ]
][
    [
        [link beast.ref.boost__beast__websocket__stream.write_some.overload2 `write_some`],
        [link beast.ref.boost__beast__websocket__stream.async_write_some `async_write_some`]
    ][
        Send a buffer sequence as part of a message.
    ]
]]

This example shows how to send a buffer sequence as a complete message.

[code_websocket_4_1]

The same message could be sent in two or more frames thusly.

[heading Receiving]

[table WebSocket Stream Read Operations
[[Function][Description]]
[
    [
        [link beast.ref.boost__beast__websocket__stream.read.overload2 `read`],
        [link beast.ref.boost__beast__websocket__stream.async_read `async_read`]
    ][
        Read a complete message into a __DynamicBuffer__.
    ]
][
    [
        [link beast.ref.boost__beast__websocket__stream.read_some.overload2 `read_some`],
        [link beast.ref.boost__beast__websocket__stream.async_read_some.overload1 `async_read_some`]
    ][
        Read part of a message into a __DynamicBuffer__.
    ]
][
    [
        [link beast.ref.boost__beast__websocket__stream.read_some.overload4 `read_some`],
        [link beast.ref.boost__beast__websocket__stream.async_read_some.overload2 `async_read_some`]
    ][
        Read part of a message into a __MutableBufferSequence__.
    ]
]]

After the WebSocket handshake is accomplished, callers may send and receive
messages using the message oriented interface. This interface requires that
all of the buffers representing the message are known ahead of time:

[code_websocket_4_2]

[important
    [link beast.ref.boost__beast__websocket__stream `websocket::stream`]
    is not thread-safe. Calls to stream member functions must
    all be made from the same implicit or explicit strand.
]

[heading Frames]

Some use-cases make it impractical or impossible to buffer the entire
message ahead of time:

* Streaming multimedia to an endpoint.
* Sending a message that does not fit in memory at once.
* Providing incremental results as they become available.

For these cases, the partial data oriented interface may be used. This
example reads and echoes a complete message using this interface:

[code_websocket_4_3]

[endsect]