1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[/-----------------------------------------------------------------------------] 11 12[section:messages Messages] 13 14Once a websocket session is established, messages can be sent unsolicited by 15either peer at any time. A message is made up of one or more ['messages frames]. 16Each frame is prefixed with the size of the payload in bytes, followed by the 17data. A frame also contains a flag (called 'fin') indicating whether or not it 18is the last frame of the message. When a message is made up from only one frame, 19it is possible to know immediately what the size of the message will be. 20Otherwise, the total size of the message can only be determined once 21the last frame is received. 22 23The boundaries between frames of a multi-frame message are not not considered 24part of the message. Intermediaries such as proxies which forward the websocket 25traffic are free to "reframe" (split frames and combine them) the message in 26arbitrary ways. These intermediaries include Beast, which can reframe messages 27automatically in some cases depending on the options set on the stream. 28 29[caution 30 An algorithm should never depend on the way that incoming or outgoing 31 messages are split up into frames. 32] 33 34Messages can be either text or binary. A message sent as text must contain 35consist of valid utf8, while a message sent as binary may contain arbitrary 36data. In addition to message frames, websocket provides ['control frames] 37in the form of ping, pong, and close messages which have a small upper limit 38on their payload size. Depending on how a message is framed, control frames 39may have more opportunities to be sent in-between. 40 41[heading Sending] 42 43These stream members are used to write websocket messages: 44 45[table WebSocket Stream Write Operations 46[[Function][Description]] 47[ 48 [ 49 [link beast.ref.boost__beast__websocket__stream.write.overload2 `write`], 50 [link beast.ref.boost__beast__websocket__stream.async_write `async_write`] 51 ][ 52 Send a buffer sequence as a complete message. 53 ] 54][ 55 [ 56 [link beast.ref.boost__beast__websocket__stream.write_some.overload2 `write_some`], 57 [link beast.ref.boost__beast__websocket__stream.async_write_some `async_write_some`] 58 ][ 59 Send a buffer sequence as part of a message. 60 ] 61]] 62 63This example shows how to send a buffer sequence as a complete message. 64 65[code_websocket_4_1] 66 67The same message could be sent in two or more frames thusly. 68 69[heading Receiving] 70 71[table WebSocket Stream Read Operations 72[[Function][Description]] 73[ 74 [ 75 [link beast.ref.boost__beast__websocket__stream.read.overload2 `read`], 76 [link beast.ref.boost__beast__websocket__stream.async_read `async_read`] 77 ][ 78 Read a complete message into a __DynamicBuffer__. 79 ] 80][ 81 [ 82 [link beast.ref.boost__beast__websocket__stream.read_some.overload2 `read_some`], 83 [link beast.ref.boost__beast__websocket__stream.async_read_some.overload1 `async_read_some`] 84 ][ 85 Read part of a message into a __DynamicBuffer__. 86 ] 87][ 88 [ 89 [link beast.ref.boost__beast__websocket__stream.read_some.overload4 `read_some`], 90 [link beast.ref.boost__beast__websocket__stream.async_read_some.overload2 `async_read_some`] 91 ][ 92 Read part of a message into a __MutableBufferSequence__. 93 ] 94]] 95 96After the WebSocket handshake is accomplished, callers may send and receive 97messages using the message oriented interface. This interface requires that 98all of the buffers representing the message are known ahead of time: 99 100[code_websocket_4_2] 101 102[important 103 [link beast.ref.boost__beast__websocket__stream `websocket::stream`] 104 is not thread-safe. Calls to stream member functions must 105 all be made from the same implicit or explicit strand. 106] 107 108[heading Frames] 109 110Some use-cases make it impractical or impossible to buffer the entire 111message ahead of time: 112 113* Streaming multimedia to an endpoint. 114* Sending a message that does not fit in memory at once. 115* Providing incremental results as they become available. 116 117For these cases, the partial data oriented interface may be used. This 118example reads and echoes a complete message using this interface: 119 120[code_websocket_4_3] 121 122[endsect] 123