123 lines
4.4 KiB
Plaintext
123 lines
4.4 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: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]
|