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