...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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: |
1 |
partial |
These read functions enable partial message data to be received
into a DynamicBuffer.
They can be configured to perform bounded work: |
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: |
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 |
Some use-cases make it impractical or impossible to buffer the entire message ahead of time:
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; } }