# ws::WebSocketFramer

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

# WebSocketFramer

```cpp
#include <icy/http/websocket.h>

class WebSocketFramer
```

[Defined in src/http/include/icy/http/websocket.h:157](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L157)

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

## Friends

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

---

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

### WebSocketAdapter

```cpp
friend class WebSocketAdapter
```

[Defined in src/http/include/icy/http/websocket.h:254](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L254)

---

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

### wsFramerTestAccess

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

[Defined in src/http/include/icy/http/websocket.h:257](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L257)

---

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

### wsFramerGetFlags

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

[Defined in src/http/include/icy/http/websocket.h:258](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L258)

## Public Methods

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

---

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

### WebSocketFramer

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

[Defined in src/http/include/icy/http/websocket.h:163](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L163)

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

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `mode` | [`ws::Mode`](https://auscaster.com/icey/docs/api-reference/icy-http-ws.md#mode-2) | ServerSide or ClientSide. |

---

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

### ~WebSocketFramer

`virtual`

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

[Defined in src/http/include/icy/http/websocket.h:165](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L165)

---

<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:174](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L174)

Encodes `data` into a [WebSocket](https://auscaster.com/icey/docs/api-reference/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](https://auscaster.com/icey/docs/api-reference/icy-http-ws.md#sendflags), [ws::SendFlags::Binary](https://auscaster.com/icey/docs/api-reference/icy-http-ws.md#sendflags), or a control frame opcode combined with [FrameFlags::Fin](https://auscaster.com/icey/docs/api-reference/icy-http-ws.md#frameflags). |
| `frame` | [`BitWriter`](https://auscaster.com/icey/docs/api-reference/icy-BitWriter.md#bitwriter) & | [BitWriter](https://auscaster.com/icey/docs/api-reference/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:185](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L185)

Decodes a single [WebSocket](https://auscaster.com/icey/docs/api-reference/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://auscaster.com/icey/docs/api-reference/icy-BitReader.md#bitreader) & | [BitReader](https://auscaster.com/icey/docs/api-reference/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`

```cpp
bool handshakeComplete() const
```

[Defined in src/http/include/icy/http/websocket.h:188](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L188)

Returns true if the [WebSocket](https://auscaster.com/icey/docs/api-reference/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:198](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L198)

[Server](https://auscaster.com/icey/docs/api-reference/icy-http-Server.md#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`](https://auscaster.com/icey/docs/api-reference/icy-http-Request.md#request-6) & | Incoming HTTP upgrade request. |
| `response` | [`http::Response`](https://auscaster.com/icey/docs/api-reference/icy-http-Response.md#response-3) & | HTTP response to populate with the handshake reply. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the request is not a valid [WebSocket](https://auscaster.com/icey/docs/api-reference/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:206](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L206)

[Client](https://auscaster.com/icey/docs/api-reference/icy-http-Client.md#client) side.

Populates `request` with the [WebSocket](https://auscaster.com/icey/docs/api-reference/icy-http-ws-WebSocket.md#websocket) upgrade headers ([Connection](https://auscaster.com/icey/docs/api-reference/icy-http-Connection.md#connection-1), Upgrade, Sec-WebSocket-Key, Sec-WebSocket-Version) to initiate the handshake.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `request` | [`http::Request`](https://auscaster.com/icey/docs/api-reference/icy-http-Request.md#request-6) & | 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:212](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L212)

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`](https://auscaster.com/icey/docs/api-reference/icy-http-Response.md#response-3) & | 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:218](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L218)

Completes the client-side handshake by verifying [Connection](https://auscaster.com/icey/docs/api-reference/icy-http-Connection.md#connection-1), Upgrade and Sec-WebSocket-Accept headers. Advances internal state to "complete".

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `response` | [`http::Response`](https://auscaster.com/icey/docs/api-reference/icy-http-Response.md#response-3) & | 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-1) `const` | Returns the frame flags of the most recently received frame. Set by [readFrame()](#readframe) |
| `bool` | [`mustMaskPayload`](#mustmaskpayload) `const` | Returns true if the payload must be masked. Used by [writeFrame()](#writeframe) |
| [`ws::Mode`](https://auscaster.com/icey/docs/api-reference/icy-http-ws.md#mode-2) | [`mode`](#mode-3) `const` |  |

---

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

### frameFlags

`const`

```cpp
int frameFlags() const
```

[Defined in src/http/include/icy/http/websocket.h:223](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L223)

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

---

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

### mustMaskPayload

`const`

```cpp
bool mustMaskPayload() const
```

[Defined in src/http/include/icy/http/websocket.h:227](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L227)

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

---

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

### mode

`const`

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

[Defined in src/http/include/icy/http/websocket.h:229](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L229)

## Private Attributes

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

---

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

### _mode

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

Type: [`ws::Mode`](https://auscaster.com/icey/docs/api-reference/icy-http-ws.md#mode-2)

[Defined in src/http/include/icy/http/websocket.h:239](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L239)

---

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

### _frameFlags

```cpp
int _frameFlags
```

[Defined in src/http/include/icy/http/websocket.h:240](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L240)

---

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

### _headerState

```cpp
int _headerState
```

[Defined in src/http/include/icy/http/websocket.h:241](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L241)

---

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

### _maskPayload

```cpp
bool _maskPayload
```

[Defined in src/http/include/icy/http/websocket.h:242](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L242)

---

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

### _rnd

```cpp
Random _rnd
```

Type: [`Random`](https://auscaster.com/icey/docs/api-reference/icy-Random.md#random)

[Defined in src/http/include/icy/http/websocket.h:243](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L243)

---

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

### _key

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

[Defined in src/http/include/icy/http/websocket.h:244](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L244)

---

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

### _fragmented

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

[Defined in src/http/include/icy/http/websocket.h:247](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L247)

Currently receiving a fragmented message.

---

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

### _fragmentOpcode

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

[Defined in src/http/include/icy/http/websocket.h:248](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L248)

Opcode of the first frame in the fragment sequence.

---

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

### _fragmentBuffer

```cpp
Buffer _fragmentBuffer
```

Type: [`Buffer`](https://auscaster.com/icey/docs/api-reference/base.md#buffer)

[Defined in src/http/include/icy/http/websocket.h:249](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L249)

Accumulated payload from continuation frames.

---

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

### _incompleteFrame

```cpp
Buffer _incompleteFrame
```

Type: [`Buffer`](https://auscaster.com/icey/docs/api-reference/base.md#buffer)

[Defined in src/http/include/icy/http/websocket.h:252](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/websocket.h#L252)

Buffer for incomplete frame data across TCP segments.