# ws::WebSocketFramer

<a id="websocketframer"></a>

# WebSocketFramer

```cpp
#include <websocket.h>

class WebSocketFramer
```

Defined in src/http/include/icy/http/websocket.h:156

[WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#websocket) frame encoder/decoder and handshake validator for RFC 6455.

## Friends

| Name | Description |
|------|-------------|
| [`WebSocketAdapter`](#websocketadapter)  |  |
| [`wsFramerTestAccess`](#wsframertestaccess)  |  |
| [`wsFramerGetFlags`](#wsframergetflags)  |  |

---

<a id="websocketadapter"></a>

### WebSocketAdapter

```cpp
friend class WebSocketAdapter
```

Defined in src/http/include/icy/http/websocket.h:253

---

<a id="wsframertestaccess"></a>

### wsFramerTestAccess

```cpp
friend void wsFramerTestAccess(WebSocketFramer & f, int state)
```

Defined in src/http/include/icy/http/websocket.h:256

---

<a id="wsframergetflags"></a>

### wsFramerGetFlags

```cpp
friend int wsFramerGetFlags(const WebSocketFramer & f)
```

Defined in src/http/include/icy/http/websocket.h:257

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`WebSocketFramer`](#websocketframer-1)  | Creates a [WebSocketFramer](#websocketframer) operating in the given endpoint mode. Client-side framers mask outgoing payloads; server-side framers do not. |
|  | [`~WebSocketFramer`](#websocketframer-2) `virtual` |  |
| `size_t` | [`writeFrame`](#writeframe) `virtual` | Encodes `data` into a [WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#websocket) frame and writes it to `frame`. |
| `uint64_t` | [`readFrame`](#readframe) `virtual` | Decodes a single [WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#websocket) frame from `frame`. |
| `bool` | [`handshakeComplete`](#handshakecomplete) `const` `nodiscard` | Returns true if the [WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#websocket) handshake has completed successfully. |
| `void` | [`acceptServerRequest`](#acceptserverrequest)  | Server side. |
| `void` | [`createClientHandshakeRequest`](#createclienthandshakerequest)  | Client side. |
| `bool` | [`checkClientHandshakeResponse`](#checkclienthandshakeresponse)  | Validates the server's 101 Switching Protocols response. |
| `void` | [`completeClientHandshake`](#completeclienthandshake)  | Completes the client-side handshake by verifying Connection, Upgrade and Sec-WebSocket-Accept headers. Advances internal state to "complete". |

---

<a id="websocketframer-1"></a>

### WebSocketFramer

```cpp
WebSocketFramer(ws::Mode mode)
```

Defined in src/http/include/icy/http/websocket.h:162

Creates a [WebSocketFramer](#websocketframer) operating in the given endpoint mode. Client-side framers mask outgoing payloads; server-side framers do not.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `mode` | [`ws::Mode`](api_Mode.md#namespaceicy_1_1http_1_1ws_1aaa1718b12afc4665a0b4a088bdfe6db5) | ServerSide or ClientSide. |

---

<a id="websocketframer-2"></a>

### ~WebSocketFramer

`virtual`

```cpp
virtual ~WebSocketFramer()
```

Defined in src/http/include/icy/http/websocket.h:164

---

<a id="writeframe"></a>

### writeFrame

`virtual`

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

Defined in src/http/include/icy/http/websocket.h:173

Encodes `data` into a [WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#websocket) frame and writes it to `frame`. 
#### Returns
Total number of bytes written to the frame buffer (header + payload).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `const char *` | Pointer to the payload data. |
| `len` | `size_t` | Payload length in bytes. |
| `flags` | `int` | Frame flags: [ws::SendFlags::Text](api_icy-http-ws.md#namespaceicy_1_1http_1_1ws_1a366b9e6ee51be48df27ea06f8d20e7a2afdf2a2c6b74320a613fe71490a96e2ae), [ws::SendFlags::Binary](api_icy-http-ws.md#namespaceicy_1_1http_1_1ws_1a366b9e6ee51be48df27ea06f8d20e7a2a0ca55f2c2a2e576e0aa1c08a4e845ed7), or a control frame opcode combined with [FrameFlags::Fin](api_icy-http-ws.md#namespaceicy_1_1http_1_1ws_1a4317f7f44088d3ab553950bab6b16ab8a0475def81fbd4e70bf7cd07ee307793a). |
| `frame` | [`BitWriter`](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-BitWriter.md#bitwriter) & | [BitWriter](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-BitWriter.md#bitwriter) to write the encoded frame into. |

---

<a id="readframe"></a>

### readFrame

`virtual`

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

Defined in src/http/include/icy/http/websocket.h:184

Decodes a single [WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#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.

#### Returns
Payload length in bytes.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `frame` | [`BitReader`](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-BitReader.md#bitreader) & | [BitReader](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-BitReader.md#bitreader) positioned at the start of a frame. |
| `payload` | `char *&` | Set to point at the start of the decoded payload. Not null-terminated. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | on protocol violations or if the buffer is too small. |

---

<a id="handshakecomplete"></a>

### handshakeComplete

`const` `nodiscard`

```cpp
[[nodiscard]] bool handshakeComplete() const
```

Defined in src/http/include/icy/http/websocket.h:187

Returns true if the [WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#websocket) handshake has completed successfully.

---

<a id="acceptserverrequest"></a>

### acceptServerRequest

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

Defined in src/http/include/icy/http/websocket.h:197

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `request` | `http::Request &` | Incoming HTTP upgrade request. |
| `response` | `http::Response &` | HTTP response to populate with the handshake reply. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the request is not a valid [WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#websocket) upgrade. |

---

<a id="createclienthandshakerequest"></a>

### createClientHandshakeRequest

```cpp
void createClientHandshakeRequest(http::Request & request)
```

Defined in src/http/include/icy/http/websocket.h:205

Client side.

Populates `request` with the [WebSocket](https://sourcey.com/examples/docs-showcase/reference/cpp/icy-http-ws-WebSocket.md#websocket) upgrade headers (Connection, Upgrade, Sec-WebSocket-Key, Sec-WebSocket-Version) to initiate the handshake.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `request` | `http::Request &` | HTTP request to add upgrade headers to. |

---

<a id="checkclienthandshakeresponse"></a>

### checkClientHandshakeResponse

```cpp
bool checkClientHandshakeResponse(http::Response & response)
```

Defined in src/http/include/icy/http/websocket.h:211

Validates the server's 101 Switching Protocols response. 
#### Returns
true if the handshake succeeded and data can flow.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `response` | `http::Response &` | The HTTP response received from the server. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the server rejected or mishandled the upgrade. |

---

<a id="completeclienthandshake"></a>

### completeClientHandshake

```cpp
void completeClientHandshake(http::Response & response)
```

Defined in src/http/include/icy/http/websocket.h:217

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

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `response` | `http::Response &` | The 101 Switching Protocols response from the server. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if any required header is missing or incorrect. |

## Protected Methods

| Return | Name | Description |
|--------|------|-------------|
| `int` | [`frameFlags`](#frameflags) `const` `nodiscard` | Returns the frame flags of the most recently received frame. Set by [readFrame()](#readframe) |
| `bool` | [`mustMaskPayload`](#mustmaskpayload) `const` `nodiscard` | Returns true if the payload must be masked. Used by [writeFrame()](#writeframe) |
| [`ws::Mode`](api_Mode.md#namespaceicy_1_1http_1_1ws_1aaa1718b12afc4665a0b4a088bdfe6db5) | [`mode`](#mode) `const` `nodiscard` |  |

---

<a id="frameflags"></a>

### frameFlags

`const` `nodiscard`

```cpp
[[nodiscard]] int frameFlags() const
```

Defined in src/http/include/icy/http/websocket.h:222

Returns the frame flags of the most recently received frame. Set by [readFrame()](#readframe)

---

<a id="mustmaskpayload"></a>

### mustMaskPayload

`const` `nodiscard`

```cpp
[[nodiscard]] bool mustMaskPayload() const
```

Defined in src/http/include/icy/http/websocket.h:226

Returns true if the payload must be masked. Used by [writeFrame()](#writeframe)

---

<a id="mode"></a>

### mode

`const` `nodiscard`

```cpp
[[nodiscard]] ws::Mode mode() const
```

Defined in src/http/include/icy/http/websocket.h:228

## Private Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`ws::Mode`](api_Mode.md#namespaceicy_1_1http_1_1ws_1aaa1718b12afc4665a0b4a088bdfe6db5) | [`_mode`](#_mode)  |  |
| `int` | [`_frameFlags`](#_frameflags)  |  |
| `int` | [`_headerState`](#_headerstate)  |  |
| `bool` | [`_maskPayload`](#_maskpayload)  |  |
| `Random` | [`_rnd`](#_rnd)  |  |
| `std::string` | [`_key`](#_key)  |  |
| `bool` | [`_fragmented`](#_fragmented)  | Currently receiving a fragmented message. |
| `int` | [`_fragmentOpcode`](#_fragmentopcode)  | [Opcode](api_Opcode.md#namespaceicy_1_1http_1_1ws_1a520f236714449c0b078af021b3ae3cb1) of the first frame in the fragment sequence. |
| [`Buffer`](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#buffer) | [`_fragmentBuffer`](#_fragmentbuffer)  | Accumulated payload from continuation frames. |
| [`Buffer`](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#buffer) | [`_incompleteFrame`](#_incompleteframe)  | [Buffer](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#buffer) for incomplete frame data across TCP segments. |

---

<a id="_mode"></a>

### _mode

```cpp
ws::Mode _mode
```

Type: [`ws::Mode`](api_Mode.md#namespaceicy_1_1http_1_1ws_1aaa1718b12afc4665a0b4a088bdfe6db5)

Defined in src/http/include/icy/http/websocket.h:238

---

<a id="_frameflags"></a>

### _frameFlags

```cpp
int _frameFlags
```

Defined in src/http/include/icy/http/websocket.h:239

---

<a id="_headerstate"></a>

### _headerState

```cpp
int _headerState
```

Defined in src/http/include/icy/http/websocket.h:240

---

<a id="_maskpayload"></a>

### _maskPayload

```cpp
bool _maskPayload
```

Defined in src/http/include/icy/http/websocket.h:241

---

<a id="_rnd"></a>

### _rnd

```cpp
Random _rnd
```

Defined in src/http/include/icy/http/websocket.h:242

---

<a id="_key"></a>

### _key

```cpp
std::string _key
```

Defined in src/http/include/icy/http/websocket.h:243

---

<a id="_fragmented"></a>

### _fragmented

```cpp
bool _fragmented {false}
```

Defined in src/http/include/icy/http/websocket.h:246

Currently receiving a fragmented message.

---

<a id="_fragmentopcode"></a>

### _fragmentOpcode

```cpp
int _fragmentOpcode {0}
```

Defined in src/http/include/icy/http/websocket.h:247

[Opcode](api_Opcode.md#namespaceicy_1_1http_1_1ws_1a520f236714449c0b078af021b3ae3cb1) of the first frame in the fragment sequence.

---

<a id="_fragmentbuffer"></a>

### _fragmentBuffer

```cpp
Buffer _fragmentBuffer
```

Type: [`Buffer`](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#buffer)

Defined in src/http/include/icy/http/websocket.h:248

Accumulated payload from continuation frames.

---

<a id="_incompleteframe"></a>

### _incompleteFrame

```cpp
Buffer _incompleteFrame
```

Type: [`Buffer`](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#buffer)

Defined in src/http/include/icy/http/websocket.h:251

[Buffer](https://sourcey.com/examples/docs-showcase/reference/cpp/base.md#buffer) for incomplete frame data across TCP segments.