Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.

Send and Receive Messages

Interfaces for transacting messages are structured into layers. The highest layer provides ease of use, while lower layers provide additional control and flexibility. The layers are arranged thusly:

Level	Read/Write What	Description
2	message	At the top layer, these functions allow for an entire message to be sent or received. They are designed for ease of use: `read`, `write`, `async_read`, and `async_write`.
1	partial	These read functions enable partial message data to be received into a DynamicBuffer. They can be configured to perform bounded work: `read_some`, and `async_read_some`.
0	partial	At the lowest level these read and write functions enable partial message data to be transacted using a constant or mutable buffer sequence: `read_some`, `write_some`, `async_read_some`, and `async_write_some`.

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:

multi_buffer buffer;
ws.read(buffer);

ws.text(ws.got_text());
ws.write(buffer.data());
buffer.consume(buffer.size());

	Important
	Calls to `set_option` must be made from the same implicit or explicit strand as that used to perform other operations.

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:

multi_buffer buffer;
for(;;)
    if(ws.read_some(buffer, 0))
        break;
ws.binary(ws.got_binary());
buffers_suffix<multi_buffer::const_buffers_type> cb{buffer.data()};
for(;;)
{
    using boost::asio::buffer_size;
    if(buffer_size(cb) > 512)
    {
        ws.write_some(false, buffers_prefix(512, cb));
        cb.consume(512);
    }
    else
    {
        ws.write_some(true, cb);
        break;
    }
}