---
product: Chilkat
product_version: 11.7.0
language: ckperl
language_label: Perl
class: WebSocket
class_name: CkWebSocket
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/perlCkWebSocketRef.html
---
# Chilkat WebSocket — Perl — v11.7.0

> Chilkat 11.7.0 · language=ckperl · class=WebSocket (CkWebSocket)
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/WebSocket.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/ckperl/guide.md`.

## Purpose

**Connect to WebSocket servers and exchange client-side frames and messages.**

**Client-side only:** `Chilkat.WebSocket` implements the client side of the WebSocket protocol. It initiates an opening handshake with an existing WebSocket server. It does not listen for incoming connections, accept clients, or implement a WebSocket server.

`Chilkat.WebSocket` operates over an established `Chilkat.Rest` connection. It creates and validates the HTTP upgrade handshake, sends and receives text or binary frames, supports fragmented messages, handles Ping, Pong, and Close control frames, polls for incoming data, and exposes frame-level diagnostics.

**Client opening handshake**

Upgrade a connected `Rest` session to WebSocket and validate the server's response before exchanging frames.

**Text and binary messages**

Send UTF-8 text or exact binary bytes as single-frame or fragmented WebSocket messages.

**Frame-by-frame receiving**

Read frames, inspect opcodes and the FIN state, and accumulate fragments until a complete message is available.

**Ping and Pong**

Use automatic or manual control-frame handling for keep-alive and responsiveness checks.

**Clean close handshake**

Exchange Close frames, inspect the peer's status code and reason, and terminate the underlying connection cleanly.

**Separate read/write paths**

Share a connection between two WebSocket objects when one thread needs to read while another writes.

**Typical connection sequence:** Connect a `Rest` object to the server, call `UseConnection`, call `AddClientHeaders`, send the opening HTTP `GET` request through `Rest`, and then call `ValidateServerHandshake`. Only after validation succeeds should the application call frame send/receive methods.

**Frames versus messages:** A WebSocket message may consist of one frame or several fragments. When receiving a fragmented message, call `ReadFrame` until `FinalFrame` is `1`, then retrieve the accumulated data with `GetFrameData`, `GetFrameDataSb`, or `GetFrameDataBd`.

For an extended overview, see [WebSocket Class Overview](https://www.chilkatsoft.com/websocket_class_overview.asp).

## Object creation, unlocking and error handling

**Object Creation**

```perl
$obj = chilkat::CkWebSocket->new();
```

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Perl.

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `# $strVal is a string # $ckStr is a CkString $webSocket->get_DebugLogFilePath($ckStr); $strVal = $webSocket->debugLogFilePath(); $webSocket->put_DebugLogFilePath($strVal);` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `# $strVal is a string # $ckStr is a CkString $webSocket->get_LastErrorHtml($ckStr); $strVal = $webSocket->lastErrorHtml();` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `# $strVal is a string # $ckStr is a CkString $webSocket->get_LastErrorText($ckStr); $strVal = $webSocket->lastErrorText();` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `# $strVal is a string # $ckStr is a CkString $webSocket->get_LastErrorXml($ckStr); $strVal = $webSocket->lastErrorXml();` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `# $boolVal is a boolean $boolVal = $webSocket->get_LastMethodSuccess(); $webSocket->put_LastMethodSuccess($boolVal);` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `Utf8` | `# $boolVal is a boolean $boolVal = $webSocket->get_Utf8(); $webSocket->put_Utf8($boolVal);` | read/write | When set to `1`, all `string` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `# $boolVal is a boolean $boolVal = $webSocket->get_VerboseLogging(); $webSocket->put_VerboseLogging($boolVal);` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `# $strVal is a string # $ckStr is a CkString $webSocket->get_Version($ckStr); $strVal = $webSocket->version();` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `CloseAutoRespond` | property, read/write | `# $boolVal is a boolean $boolVal = $webSocket->get_CloseAutoRespond(); $webSocket->put_CloseAutoRespond($boolVal);` |
| `CloseReason` | property, read-only | `# $strVal is a string # $ckStr is a CkString $webSocket->get_CloseReason($ckStr); $strVal = $webSocket->closeReason();` |
| `CloseReceived` | property, read-only | `# $boolVal is a boolean $boolVal = $webSocket->get_CloseReceived();` |
| `CloseStatusCode` | property, read-only | `# $intVal is an integer $intVal = $webSocket->get_CloseStatusCode();` |
| `FinalFrame` | property, read-only | `# $boolVal is a boolean $boolVal = $webSocket->get_FinalFrame();` |
| `FrameDataLen` | property, read-only | `# $intVal is an integer $intVal = $webSocket->get_FrameDataLen();` |
| `FrameOpcode` | property, read-only | `# $strVal is a string # $ckStr is a CkString $webSocket->get_FrameOpcode($ckStr); $strVal = $webSocket->frameOpcode();` |
| `FrameOpcodeInt` | property, read-only | `# $intVal is an integer $intVal = $webSocket->get_FrameOpcodeInt();` |
| `IdleTimeoutMs` | property, read/write | `# $intVal is an integer $intVal = $webSocket->get_IdleTimeoutMs(); $webSocket->put_IdleTimeoutMs($intVal);` |
| `IsConnected` | property, read-only | `# $boolVal is a boolean $boolVal = $webSocket->get_IsConnected();` |
| `NeedSendPong` | property, read-only | `# $boolVal is a boolean $boolVal = $webSocket->get_NeedSendPong();` |
| `PingAutoRespond` | property, read/write | `# $boolVal is a boolean $boolVal = $webSocket->get_PingAutoRespond(); $webSocket->put_PingAutoRespond($boolVal);` |
| `PongAutoConsume` | property, read/write | `# $boolVal is a boolean $boolVal = $webSocket->get_PongAutoConsume(); $webSocket->put_PongAutoConsume($boolVal);` |
| `PongConsumed` | property, read-only | `# $boolVal is a boolean $boolVal = $webSocket->get_PongConsumed();` |
| `ReadFrameFailReason` | property, read-only | `# $intVal is an integer $intVal = $webSocket->get_ReadFrameFailReason();` |
| `UncommonOptions` | property, read-only | `# $strVal is a string # $ckStr is a CkString $webSocket->get_UncommonOptions($ckStr); $strVal = $webSocket->uncommonOptions();` |
| `AddClientHeaders` | method | `$status = $webSocket->AddClientHeaders();` |
| `CloseConnection` | method | `$status = $webSocket->CloseConnection();` |
| `GetFrameData` | method | `# $outStr is a CkString (output) $status = $webSocket->GetFrameData($outStr); $retStr = $webSocket->getFrameData();` |
| `GetFrameDataBd` | method | `# $binData is a CkBinData $status = $webSocket->GetFrameDataBd($binData);` |
| `GetFrameDataSb` | method | `# $sb is a CkStringBuilder $status = $webSocket->GetFrameDataSb($sb);` |
| `LoadTaskCaller` | method | `# $task is a CkTask $status = $webSocket->LoadTaskCaller($task);` |
| `PollDataAvailable` | method | `$retBool = $webSocket->PollDataAvailable();` |
| `ReadFrame` | method | `$status = $webSocket->ReadFrame();` |
| `SendClose` | method | `# $includeStatus is a boolean # $statusCode is an integer # $reason is a string $status = $webSocket->SendClose($includeStatus, $statusCode, $reason);` |
| `SendFrame` | method | `# $stringToSend is a string # $finalFrame is a boolean $status = $webSocket->SendFrame($stringToSend, $finalFrame);` |
| `SendFrameBd` | method | `# $bdToSend is a CkBinData # $finalFrame is a boolean $status = $webSocket->SendFrameBd($bdToSend, $finalFrame);` |
| `SendFrameSb` | method | `# $sbToSend is a CkStringBuilder # $finalFrame is a boolean $status = $webSocket->SendFrameSb($sbToSend, $finalFrame);` |
| `SendPing` | method | `# $pingData is a string $status = $webSocket->SendPing($pingData);` |
| `SendPong` | method | `$status = $webSocket->SendPong();` |
| `ShareConnection` | method | `# $ws is a CkWebSocket $status = $webSocket->ShareConnection($ws);` |
| `UseConnection` | method | `# $connection is a CkRest $status = $webSocket->UseConnection($connection);` |
| `ValidateServerHandshake` | method | `$status = $webSocket->ValidateServerHandshake();` |

## Properties

### WebSocket.CloseAutoRespond

`Chilkat 11.7.0 · ckperl · WebSocket · CloseAutoRespond · property · read/write · since 9.5.0.70`

```perl
# $boolVal is a boolean

$boolVal = $webSocket->get_CloseAutoRespond();

$webSocket->put_CloseAutoRespond($boolVal);
```

Controls whether Chilkat automatically answers an incoming Close control frame.

- When `1`, an incoming Close is answered automatically if the client did not already initiate the close. After a Close has been both received and sent, Chilkat closes the underlying connection.
- When `0`, the application can detect the received Close through `CloseReceived` or `FrameOpcode` and call `SendClose` itself.

The default is `1`.

**Closing handshake:** A peer that receives a Close and has not already sent one should respond with a Close. Automatic response is usually the safest choice unless the application must control the exact status code or timing.

### WebSocket.CloseReason

`Chilkat 11.7.0 · ckperl · WebSocket · CloseReason · property · read-only · since 9.5.0.70`

```perl
# $strVal is a string

# $ckStr is a CkString

$webSocket->get_CloseReason($ckStr);

$strVal = $webSocket->closeReason();
```

Returns the UTF-8 reason text contained in the received Close control frame.

The value is empty when the peer supplied no reason or when no Close frame has been received. A reason is diagnostic text and should not be treated as a stable machine-readable error identifier; use `CloseStatusCode` for protocol-level handling.

### WebSocket.CloseReceived

`Chilkat 11.7.0 · ckperl · WebSocket · CloseReceived · property · read-only · since 9.5.0.70`

```perl
# $boolVal is a boolean

$boolVal = $webSocket->get_CloseReceived();
```

`1` after a Close control frame has been received on the current WebSocket connection.

When `CloseAutoRespond` is `0`, use this property to determine whether the application needs to call `SendClose` to complete the closing handshake. The received status code and reason, if present, are available through `CloseStatusCode` and `CloseReason`.

### WebSocket.CloseStatusCode

`Chilkat 11.7.0 · ckperl · WebSocket · CloseStatusCode · property · read-only · since 9.5.0.70`

```perl
# $intVal is an integer

$intVal = $webSocket->get_CloseStatusCode();
```

Returns the status code contained in the received Close control frame.

Returns `0` when no Close frame has been received or when the received Close frame did not include a status code.

**Meaning of zero:** `0` is an API sentinel; it is not a WebSocket close status transmitted by the peer.

### WebSocket.FinalFrame

`Chilkat 11.7.0 · ckperl · WebSocket · FinalFrame · property · read-only · since 9.5.0.70`

```perl
# $boolVal is a boolean

$boolVal = $webSocket->get_FinalFrame();
```

`1` if the frame most recently delivered by `ReadFrame` had its WebSocket `FIN` bit set; otherwise `0`.

For a fragmented data message, continue reading while this property is `0`. The fragment with `1` completes the message. Unfragmented messages have `1` on their only frame.

**Control frames:** Close, Ping, and Pong are control frames and are not fragmented by the WebSocket protocol; their `FIN` bit is always set.

### WebSocket.FrameDataLen

`Chilkat 11.7.0 · ckperl · WebSocket · FrameDataLen · property · read-only · since 9.5.0.70`

```perl
# $intVal is an integer

$intVal = $webSocket->get_FrameDataLen();
```

Returns the number of payload bytes currently accumulated in the internal receive buffer.

The value can represent data from one frame or from multiple calls to `ReadFrame`, which is useful when receiving a fragmented message. The accumulated bytes remain available until retrieved by `GetFrameData`, `GetFrameDataSb`, or `GetFrameDataBd`.

**Message length:** This is the length accumulated so far, not necessarily the final length of the complete WebSocket message. Check `FinalFrame` to determine whether the last received fragment completed the message.

### WebSocket.FrameOpcode

`Chilkat 11.7.0 · ckperl · WebSocket · FrameOpcode · property · read-only · since 9.5.0.70`

```perl
# $strVal is a string

# $ckStr is a CkString

$webSocket->get_FrameOpcode($ckStr);

$strVal = $webSocket->frameOpcode();
```

Returns the symbolic opcode of the frame most recently delivered by `ReadFrame`.

| Value | Meaning |
| :--- | :--- |
| `Continuation` | A later fragment of a Text or Binary message |
| `Text` | UTF-8 text data |
| `Binary` | Binary data |
| `Close` | Closing handshake |
| `Ping` | Ping control frame |
| `Pong` | Pong control frame |

Before any frame has been received, the value is the empty string. Ping or Pong frames handled internally by the auto-response/auto-consume options may not be returned as the current frame.

### WebSocket.FrameOpcodeInt

`Chilkat 11.7.0 · ckperl · WebSocket · FrameOpcodeInt · property · read-only · since 9.5.0.70`

```perl
# $intVal is an integer

$intVal = $webSocket->get_FrameOpcodeInt();
```

Returns the numeric opcode of the frame most recently delivered by `ReadFrame`.

| Value | Frame type |
| :--- | :--- |
| `0` | Continuation |
| `1` | Text |
| `2` | Binary |
| `8` | Close |
| `9` | Ping |
| `10` | Pong |

Use `FrameOpcode` when a readable symbolic value is preferred.

### WebSocket.IdleTimeoutMs

`Chilkat 11.7.0 · ckperl · WebSocket · IdleTimeoutMs · property · read/write`

```perl
# $intVal is an integer

$intVal = $webSocket->get_IdleTimeoutMs();

$webSocket->put_IdleTimeoutMs($intVal);
```

Specifies the maximum number of milliseconds an active send or receive operation may remain stalled while waiting for additional network progress.

The default is `30000` milliseconds (30 seconds). This is an **inactivity timeout**, not a total limit on the duration of the operation. An operation may continue longer than this value as long as data continues to be transferred.

**Not a keep-alive interval:** This property does not automatically send WebSocket Ping frames. Use `SendPing` when the application needs protocol-level keep-alive or responsiveness checks.

### WebSocket.IsConnected

`Chilkat 11.7.0 · ckperl · WebSocket · IsConnected · property · read-only · since 9.5.0.70`

```perl
# $boolVal is a boolean

$boolVal = $webSocket->get_IsConnected();
```

`1` when the underlying WebSocket network connection is currently open; otherwise `0`.

**Connection state is not a health check:** A network interruption may not be detected until the next read or write operation. Use normal I/O results—and optionally Ping/Pong—to determine whether a seemingly connected peer is still responsive.

### WebSocket.NeedSendPong

`Chilkat 11.7.0 · ckperl · WebSocket · NeedSendPong · property · read-only · since 9.5.0.70`

```perl
# $boolVal is a boolean

$boolVal = $webSocket->get_NeedSendPong();
```

`1` when a Ping frame has been received but no corresponding Pong has yet been sent.

This property is primarily useful when `PingAutoRespond` is `0`. Call `SendPong` as soon as practical; it automatically sends the received Ping payload in the Pong response.

### WebSocket.PingAutoRespond

`Chilkat 11.7.0 · ckperl · WebSocket · PingAutoRespond · property · read/write · since 9.5.0.70`

```perl
# $boolVal is a boolean

$boolVal = $webSocket->get_PingAutoRespond();

$webSocket->put_PingAutoRespond($boolVal);
```

Controls automatic handling of incoming Ping control frames.

- When `1`, Chilkat sends the required Pong automatically and `ReadFrame` consumes the Ping internally, continuing until another frame is available.
- When `0`, the Ping can be returned to the application. Check `NeedSendPong` and call `SendPong` as soon as practical.

The default is `1`.

**Payload echo:** A Pong sent in response to a Ping must carry the same application data. `SendPong` automatically uses the stored payload of the unanswered Ping.

### WebSocket.PongAutoConsume

`Chilkat 11.7.0 · ckperl · WebSocket · PongAutoConsume · property · read/write · since 9.5.0.70`

```perl
# $boolVal is a boolean

$boolVal = $webSocket->get_PongAutoConsume();

$webSocket->put_PongAutoConsume($boolVal);
```

Controls whether incoming Pong control frames are hidden from the application.

- When `1`, `ReadFrame` consumes Pong frames internally and continues reading until a non-Pong frame is available.
- When `0`, an incoming Pong can be returned normally with `FrameOpcode` equal to `Pong`.

The default is `1`. Check `PongConsumed` after `ReadFrame` to learn whether one or more Pong frames were consumed during that call.

### WebSocket.PongConsumed

`Chilkat 11.7.0 · ckperl · WebSocket · PongConsumed · property · read-only · since 9.5.0.70`

```perl
# $boolVal is a boolean

$boolVal = $webSocket->get_PongConsumed();
```

`1` if the most recent call to `ReadFrame` internally consumed a Pong frame while `PongAutoConsume` was `1`.

The property is reset to `0` at the beginning of each `ReadFrame` call and set to `1` if a Pong is consumed during that call.

**Why unsolicited Pong is possible:** Either endpoint may send a Pong without a preceding Ping, and a response to an earlier Ping may arrive between application data frames. Automatic consumption allows ordinary read loops to ignore these control frames while still detecting that they occurred.

### WebSocket.ReadFrameFailReason

`Chilkat 11.7.0 · ckperl · WebSocket · ReadFrameFailReason · property · read-only · since 9.5.0.70`

```perl
# $intVal is an integer

$intVal = $webSocket->get_ReadFrameFailReason();
```

When `ReadFrame` returns `0`, this property categorizes the reason:

| Value | Meaning |
| :--- | :--- |
| `0` | No failure is recorded |
| `1` | Read inactivity timeout |
| `2` | Aborted by an application callback |
| `3` | Fatal socket error or lost connection |
| `4` | Invalid WebSocket frame bytes were received |
| `99` | Unexpected catch-all failure |

Use this value for programmatic branching and inspect `LastErrorText` for detailed diagnostics.

### WebSocket.UncommonOptions

`Chilkat 11.7.0 · ckperl · WebSocket · UncommonOptions · property · read-only · since 9.5.0.80`

```perl
# $strVal is a string

# $ckStr is a CkString

$webSocket->get_UncommonOptions($ckStr);

$strVal = $webSocket->uncommonOptions();
```

Contains a comma-separated list of rarely needed compatibility or platform options. The default is the empty string and should normally remain unchanged.

| Keyword | Effect |
| :--- | :--- |
| `ProtectFromVpn` | On Android, attempts to route the connection outside an installed or active VPN. Introduced in v9.5.0.80. |

**Platform-specific behavior:** This option applies only on Android. Leave the property empty on other platforms and unless bypassing the device VPN is an explicit application requirement.

## Methods

### WebSocket.AddClientHeaders

`Chilkat 11.7.0 · ckperl · WebSocket · AddClientHeaders · method · since 9.5.0.70`

```perl
$status = $webSocket->AddClientHeaders();
```

Adds the standard client opening-handshake headers to the `Rest` object supplied to `UseConnection`:

```
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: ...
Sec-WebSocket-Version: 13
```

`Sec-WebSocket-Key` contains a newly generated client nonce used by the server to produce `Sec-WebSocket-Accept`.

**Additional handshake headers:** If the server requires headers such as `Origin`, `Authorization`, cookies, or `Sec-WebSocket-Protocol`, add them through the associated `Rest` object before sending the HTTP upgrade request.

Returns 1 for success, 0 for failure.

### WebSocket.CloseConnection

`Chilkat 11.7.0 · ckperl · WebSocket · CloseConnection · method · since 9.5.0.70`

```perl
$status = $webSocket->CloseConnection();
```

Immediately closes the underlying network connection without completing the WebSocket closing handshake.

Use this method when the connection must be abandoned because of a fatal error, timeout, application shutdown, or an unresponsive peer.

**Preferred shutdown:** For a normal shutdown, call `SendClose`, receive the peer's Close frame with `ReadFrame`, and allow the closing handshake to complete. An abrupt transport close does not provide the peer with a WebSocket status code or reason.

Returns 1 for success, 0 for failure.

### WebSocket.GetFrameData

`Chilkat 11.7.0 · ckperl · WebSocket · GetFrameData · method · since 9.5.0.70`

```perl
# $outStr is a CkString (output)

$status = $webSocket->GetFrameData($outStr);

$retStr = $webSocket->getFrameData();
```

Returns the bytes accumulated by successful calls to `ReadFrame` as a string, then clears the internal receive buffer.

This method is intended for WebSocket text-message data. For arbitrary binary payloads, use `GetFrameDataBd` to avoid interpreting binary bytes as text.

**Fragmented messages:** To retrieve an entire fragmented message, continue calling `ReadFrame` until `FinalFrame` is `1`, and then call `GetFrameData` once. Calling this method earlier returns and clears only the data accumulated so far.

Returns 1 for success, 0 for failure.

### WebSocket.GetFrameDataBd

`Chilkat 11.7.0 · ckperl · WebSocket · GetFrameDataBd · method · since 9.5.0.70`

```perl
# $binData is a CkBinData

$status = $webSocket->GetFrameDataBd($binData);
```

Appends the bytes accumulated by successful calls to `ReadFrame` to `binData`, then clears the internal receive buffer.

Use this method for binary messages or whenever the exact received bytes must be preserved. Existing data in the destination `BinData` is retained because the received bytes are appended.

**Receive-buffer ownership:** Calling any one of `GetFrameData`, `GetFrameDataSb`, or `GetFrameDataBd` consumes the same internal buffer. Retrieve the data using only the form needed by the application.

Returns 1 for success, 0 for failure.

### WebSocket.GetFrameDataSb

`Chilkat 11.7.0 · ckperl · WebSocket · GetFrameDataSb · method · since 9.5.0.70`

```perl
# $sb is a CkStringBuilder

$status = $webSocket->GetFrameDataSb($sb);
```

Appends the text represented by the bytes accumulated by successful calls to `ReadFrame` to `sb`, then clears the internal receive buffer.

Existing text in the destination `StringBuilder` is retained. This method is most appropriate for text-message data; use `GetFrameDataBd` for arbitrary binary payloads.

**Fragmented messages:** The receive buffer can accumulate multiple frames. Read until `FinalFrame` is `1` before calling this method when the application wants the complete message.

Returns 1 for success, 0 for failure.

### WebSocket.LoadTaskCaller

`Chilkat 11.7.0 · ckperl · WebSocket · LoadTaskCaller · method · since 9.5.0.80`

```perl
# $task is a CkTask

$status = $webSocket->LoadTaskCaller($task);
```

Loads the caller object associated with an asynchronous `Task` method invocation.

This is used by Chilkat's asynchronous task infrastructure when access to the original `WebSocket` object is required after the task completes.

Returns 1 for success, 0 for failure.

### WebSocket.PollDataAvailable

`Chilkat 11.7.0 · ckperl · WebSocket · PollDataAvailable · method · since 9.5.0.70`

```perl
$retBool = $webSocket->PollDataAvailable();
```

Checks whether bytes are currently waiting to be read from the underlying WebSocket connection.

Returns `1` when incoming data is available and `0` when no data is presently waiting.

**Polling is only a snapshot:** A `1` result does not mean that an entire WebSocket frame or message has arrived. Call `ReadFrame` to parse the protocol frame. A `0` result does not indicate that the peer will not send data later.

### WebSocket.ReadFrame

`Chilkat 11.7.0 · ckperl · WebSocket · ReadFrame · method · since 9.5.0.70`

```perl
$status = $webSocket->ReadFrame();
```

Reads the next WebSocket frame from the connected server. On success, the method updates `FrameOpcode`, `FrameOpcodeInt`, `FinalFrame`, and `FrameDataLen`.

Frame payload bytes are added to an internal receive buffer. The buffer may therefore contain data accumulated by multiple calls to `ReadFrame`. Retrieve and clear it with `GetFrameData`, `GetFrameDataSb`, or `GetFrameDataBd`.

**Reading a complete message**

Call `ReadFrame` until `FinalFrame` is `1`, then retrieve the accumulated message data. A fragmented message begins with a Text or Binary frame and continues with one or more Continuation frames.

**Control-frame automation:** Depending on `PingAutoRespond` and `PongAutoConsume`, incoming Ping and Pong frames may be handled internally, causing this method to continue reading until another frame is available. If the method returns `0`, inspect `ReadFrameFailReason` and `LastErrorText`.

Returns 1 for success, 0 for failure.

Async variant: `ReadFrameAsync` — same arguments, returns a `Task` (see Async variants below).

### WebSocket.SendClose

`Chilkat 11.7.0 · ckperl · WebSocket · SendClose · method · since 9.5.0.70`

```perl
# $includeStatus is a boolean

# $statusCode is an integer

# $reason is a string

$status = $webSocket->SendClose($includeStatus, $statusCode, $reason);
```

Sends a WebSocket Close control frame and begins or completes the closing handshake.

- If `includeStatus` is `0`, the Close frame contains no status code and `statusCode` and `reason` are ignored.
- If `includeStatus` is `1`, the frame contains `statusCode` followed by the UTF-8 bytes of `reason`.

The complete Close payload cannot exceed 125 bytes, leaving at most 123 bytes for the UTF-8 reason after the two-byte status code. Chilkat truncates an overlong reason. The API accepts status-code integers from 0 through 16383.

**Protocol-valid status codes:** The API's numeric range is broader than the set valid for transmission under RFC 6455. Use a defined protocol code such as `1000` for normal closure, or an appropriate application code in the `3000`–`4999` range. Codes `1005`, `1006`, and `1015` are reserved reporting values and must not be sent in a Close frame.

**Clean close:** After initiating a close, read the peer's Close response. If this method answers a Close already received from the server, Chilkat also closes the underlying connection after sending the response.

Returns 1 for success, 0 for failure.

Async variant: `SendCloseAsync` — same arguments, returns a `Task` (see Async variants below).

### WebSocket.SendFrame

`Chilkat 11.7.0 · ckperl · WebSocket · SendFrame · method · since 9.5.0.70`

```perl
# $stringToSend is a string

# $finalFrame is a boolean

$status = $webSocket->SendFrame($stringToSend, $finalFrame);
```

Sends one WebSocket **text data frame** containing `stringToSend`. WebSocket text data is UTF-8 on the wire.

- Set `finalFrame` to `1` when this frame completes the message.
- Set `finalFrame` to `0` when additional frames will follow as part of the same fragmented message.

For a normal unfragmented text message, call this method once with `finalFrame` set to `1`. For a fragmented message, call it repeatedly and set `1` only for the final fragment.

**Frames and messages:** A WebSocket message may contain one frame or multiple fragments. Do not begin a second data message until the current fragmented message has been completed. Control frames such as Ping, Pong, and Close may occur between message fragments.

Returns 1 for success, 0 for failure.

Async variant: `SendFrameAsync` — same arguments, returns a `Task` (see Async variants below).

### WebSocket.SendFrameBd

`Chilkat 11.7.0 · ckperl · WebSocket · SendFrameBd · method · since 9.5.0.70`

```perl
# $bdToSend is a CkBinData

# $finalFrame is a boolean

$status = $webSocket->SendFrameBd($bdToSend, $finalFrame);
```

Sends one WebSocket **binary data frame** containing the current bytes in `bdToSend`.

- Set `finalFrame` to `1` when this frame completes the binary message.
- Set `finalFrame` to `0` when additional binary-message fragments will follow.

For an ordinary single-frame binary message, set `finalFrame` to `1`.

**Exact bytes:** No text encoding is involved. The bytes stored in `bdToSend` become the frame payload, while Chilkat applies the client-side WebSocket framing and masking required by the protocol.

Returns 1 for success, 0 for failure.

Async variant: `SendFrameBdAsync` — same arguments, returns a `Task` (see Async variants below).

### WebSocket.SendFrameSb

`Chilkat 11.7.0 · ckperl · WebSocket · SendFrameSb · method · since 9.5.0.70`

```perl
# $sbToSend is a CkStringBuilder

# $finalFrame is a boolean

$status = $webSocket->SendFrameSb($sbToSend, $finalFrame);
```

Sends one WebSocket **text data frame** containing the current contents of `sbToSend`.

- Set `finalFrame` to `1` when this frame completes the message.
- Set `finalFrame` to `0` when more fragments will follow.

For an ordinary single-frame text message, set `finalFrame` to `1`. WebSocket text data is UTF-8 on the wire.

**Message fragmentation:** Repeated calls with `finalFrame` set to `0` create fragments of the same text message. Complete the message with a final call that passes `1`.

Returns 1 for success, 0 for failure.

Async variant: `SendFrameSbAsync` — same arguments, returns a `Task` (see Async variants below).

### WebSocket.SendPing

`Chilkat 11.7.0 · ckperl · WebSocket · SendPing · method · since 9.5.0.70`

```perl
# $pingData is a string

$status = $webSocket->SendPing($pingData);
```

Sends a WebSocket Ping control frame. If `pingData` is non-empty, its UTF-8 bytes are included as the Ping payload.

WebSocket control-frame payloads are limited to 125 bytes. If the UTF-8 representation exceeds this limit, Chilkat truncates it to 125 bytes.

**Ping/Pong behavior:** A peer that receives a Ping is expected to send a Pong containing the same application data as soon as practical. Ping is useful for protocol-level liveness checks, but receiving a Pong does not by itself prove that the application running above the connection is healthy.

Returns 1 for success, 0 for failure.

Async variant: `SendPingAsync` — same arguments, returns a `Task` (see Async variants below).

### WebSocket.SendPong

`Chilkat 11.7.0 · ckperl · WebSocket · SendPong · method · since 9.5.0.70`

```perl
$status = $webSocket->SendPong();
```

Sends a WebSocket Pong control frame.

When a Ping has been received and has not yet been answered, this method automatically uses the previously received Ping payload as the Pong payload, as required for a Ping response.

**Manual response mode:** This method is normally used when `PingAutoRespond` is `0` and `NeedSendPong` is `1`. When automatic Ping handling is enabled, Chilkat sends the Pong internally.

Returns 1 for success, 0 for failure.

Async variant: `SendPongAsync` — same arguments, returns a `Task` (see Async variants below).

### WebSocket.ShareConnection

`Chilkat 11.7.0 · ckperl · WebSocket · ShareConnection · method · since 11.0.0`

```perl
# $ws is a CkWebSocket

$status = $webSocket->ShareConnection($ws);
```

**Full documentation for this method (same in every language):** [C# WebSocket Bidirectional Reading/Writing in Threads](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/websocket_csharp_bidirectional.md) · [C++ WebSocket Bidirectional Reading/Writing in Threads](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/websocket_cpp_bidirectional.md)

Causes the calling `WebSocket` object to share the already-established WebSocket connection owned by `ws`.

This enables a bidirectional design in which separate `WebSocket` objects operate on the same connection—for example, one thread blocks in `ReadFrame` while another thread sends frames.

**Concurrency model:** Use this feature to separate the read path from the write path. The application remains responsible for coordinating object lifetime, shutdown, and higher-level message state. Avoid multiple concurrent readers or multiple unsynchronized writers unless the application provides its own coordination.

Returns 1 for success, 0 for failure.

### WebSocket.UseConnection

`Chilkat 11.7.0 · ckperl · WebSocket · UseConnection · method · since 9.5.0.70`

```perl
# $connection is a CkRest

$status = $webSocket->UseConnection($connection);
```

Associates this `WebSocket` object with an existing, connected `Rest` object and prepares it for a client-side WebSocket session.

The opening WebSocket handshake is an HTTP `GET` upgrade request. Using `Rest` for the underlying connection allows the application to configure TLS, proxies, authentication, custom request headers, IPv6, socket options, bandwidth limits, and other connection features before the upgrade is performed.

**Client-side API:** Chilkat.WebSocket initiates connections to WebSocket servers. It does not listen for incoming connections or implement a WebSocket server endpoint.

**Typical opening sequence**

1. Connect the `Rest` object to the server.
2. Call `UseConnection`.
3. Call `AddClientHeaders`.
4. Send the HTTP `GET` request with the `Rest` object.
5. Call `ValidateServerHandshake`.

Returns 1 for success, 0 for failure.

### WebSocket.ValidateServerHandshake

`Chilkat 11.7.0 · ckperl · WebSocket · ValidateServerHandshake · method · since 9.5.0.70`

```perl
$status = $webSocket->ValidateServerHandshake();
```

Validates the server's response to the WebSocket opening handshake sent through the associated `Rest` object.

Validation checks that the server accepted the HTTP upgrade and returned the expected WebSocket handshake response, including the value derived from the client's `Sec-WebSocket-Key`. If this method returns `1`, the connection has entered the WebSocket protocol and data or control frames may be exchanged.

**Call order:** Call this method only after the `Rest` object has sent the opening `GET` request and received the server's response. A successful HTTP request alone does not establish a WebSocket session; the response must also pass this validation.

Returns 1 for success, 0 for failure.

## Events and callbacks

This binding has no event callbacks. For progress, percent-done or cancellation use the `*Async` variant of a method and poll the returned `Task` (`PercentDone`, `Finished`, `Cancel`).

## Async variants

Each returns a `Task` instead of the result and takes the same arguments as the synchronous method; run the task, wait for `Finished`, then read the result from the task. No new Async methods are added from 11.7.0 on.

```perl
# returns a CkTask

$ret_task = $webSocket->ReadFrameAsync();
# returns a CkTask

# $includeStatus is a boolean

# $statusCode is an integer

# $reason is a string

$ret_task = $webSocket->SendCloseAsync($includeStatus, $statusCode, $reason);
# returns a CkTask

# $stringToSend is a string

# $finalFrame is a boolean

$ret_task = $webSocket->SendFrameAsync($stringToSend, $finalFrame);
# returns a CkTask

# $bdToSend is a CkBinData

# $finalFrame is a boolean

$ret_task = $webSocket->SendFrameBdAsync($bdToSend, $finalFrame);
# returns a CkTask

# $sbToSend is a CkStringBuilder

# $finalFrame is a boolean

$ret_task = $webSocket->SendFrameSbAsync($sbToSend, $finalFrame);
# returns a CkTask

# $pingData is a string

$ret_task = $webSocket->SendPingAsync($pingData);
# returns a CkTask

$ret_task = $webSocket->SendPongAsync();
```

## Related classes

[`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/ckperl/classes/BinData.md), [`Rest`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/ckperl/classes/Rest.md), [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/ckperl/classes/StringBuilder.md), [`Task`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/ckperl/classes/Task.md)