ws::WebSocketFramer

WebSocketFramer

#include <icy/http/websocket.h>

WebSocket frame encoder/decoder and handshake validator for RFC 6455.

Public Methods

WebSocketFramer

WebSocketFramer(ws::Mode mode)

Creates a WebSocketFramer operating in the given endpoint mode. Client-side framers mask outgoing payloads; server-side framers do not.

Parameters

• mode ServerSide or ClientSide.

writeFrame

virtual

virtual size_t writeFrame(const char * data, size_t len, int flags, BitWriter & frame)

Encodes data into a WebSocket frame and writes it to frame.

Parameters

• data Pointer to the payload data.

• len Payload length in bytes.

• flags Frame flags: ws::SendFlags::Text, ws::SendFlags::Binary, or a control frame opcode combined with FrameFlags::Fin.

• frame BitWriter to write the encoded frame into.

Returns

Total number of bytes written to the frame buffer (header + payload).

readFrame

virtual

virtual uint64_t readFrame(BitReader & frame, char *& payload)

Decodes a single WebSocket frame from frame.

The payload is unmasked in-place in the source buffer; no copy is made. payload is set to point at the start of the payload within frame's buffer.

Parameters

• frame BitReader positioned at the start of a frame.

• payload Set to point at the start of the decoded payload. Not null-terminated.

Returns

Payload length in bytes.

Exceptions

• std::runtime_error on protocol violations or if the buffer is too small.

handshakeComplete

const

bool handshakeComplete() const

Returns true if the WebSocket handshake has completed successfully.

acceptServerRequest

void acceptServerRequest(http::Request & request, http::Response & response)

Server side.

Validates the client upgrade request and writes a 101 Switching Protocols response. Sets the internal state to mark the handshake as complete.

Parameters

• request Incoming HTTP upgrade request.

• response HTTP response to populate with the handshake reply.

Exceptions

• std::runtime_error if the request is not a valid WebSocket upgrade.

createClientHandshakeRequest

void createClientHandshakeRequest(http::Request & request)

Client side.

Populates request with the WebSocket upgrade headers (Connection, Upgrade, Sec-WebSocket-Key, Sec-WebSocket-Version) to initiate the handshake.

Parameters

• request HTTP request to add upgrade headers to.

checkClientHandshakeResponse

bool checkClientHandshakeResponse(http::Response & response)

Validates the server's 101 Switching Protocols response.

Parameters

• response The HTTP response received from the server.

Returns

true if the handshake succeeded and data can flow.

Exceptions

• std::runtime_error if the server rejected or mishandled the upgrade.

completeClientHandshake

void completeClientHandshake(http::Response & response)

Completes the client-side handshake by verifying Connection, Upgrade and Sec-WebSocket-Accept headers. Advances internal state to "complete".

Parameters

• response The 101 Switching Protocols response from the server.

Exceptions

• std::runtime_error if any required header is missing or incorrect.

Protected Methods

frameFlags

const

int frameFlags() const

Returns the frame flags of the most recently received frame. Set by readFrame()

mustMaskPayload

const

bool mustMaskPayload() const

Returns true if the payload must be masked. Used by writeFrame()

mode

const

ws::Mode mode() const

Private Attributes

_mode

ws::Mode _mode

_frameFlags

int _frameFlags

_headerState

int _headerState

_maskPayload

bool _maskPayload

_rnd

Random _rnd

_key

std::string _key

_fragmented

bool _fragmented {false}

Currently receiving a fragmented message.

_fragmentOpcode

int _fragmentOpcode {0}

Opcode of the first frame in the fragment sequence.

_fragmentBuffer

Buffer _fragmentBuffer

Accumulated payload from continuation frames.

_incompleteFrame

Buffer _incompleteFrame

Buffer for incomplete frame data across TCP segments.