WebSocket Unicode C Reference Documentation
WebSocket
Current Version: 11.5.0
Chilkat.WebSocket
Upgrade a connected
Send UTF-8 text or exact binary bytes as single-frame or fragmented
WebSocket messages.
Read frames, inspect opcodes and the FIN state, and accumulate fragments
until a complete message is available.
Use automatic or manual control-frame handling for keep-alive and
responsiveness checks.
Exchange Close frames, inspect the peer's status code and reason, and
terminate the underlying connection cleanly.
Share a connection between two WebSocket objects when one thread needs
to read while another writes.
For an extended overview, see
WebSocket Class Overview.
Connect to WebSocket servers and exchange client-side frames and messages.
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
Rest session to WebSocket and validate
the server's response before exchanging frames.
Text and binary messages
Frame-by-frame receiving
Ping and Pong
Clean close handshake
Separate read/write paths
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.
ReadFrame until
FinalFrame is TRUE, then retrieve the accumulated data with
GetFrameData, GetFrameDataSb, or
GetFrameDataBd.
Create/Dispose
HCkWebSocketW instance = CkWebSocketW_Create(); // ... CkWebSocketW_Dispose(instance);
Creates an instance of the HCkWebSocketW object and returns a handle ("void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.
Objects created by calling CkWebSocketW_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkWebSocketW_Dispose.
Callback Functions
Provides the opportunity for a method call to be aborted. If TRUE is returned, the operation in progress is aborted.
Return FALSE to allow the current method call to continue.
This callback function is called periodically based on the value of the HeartbeatMs property.
(If HeartbeatMs is 0, then no callbacks are made.) As an example, to make 5 AbortCheck callbacks per second, set the HeartbeatMs property equal to 200.
Provides the percentage completed for any method that involves network communications or time-consuming processing (assuming it is a method where a percentage completion can be measured). This callback is only called when it is possible to know a percentage completion, and when it makes sense to express the operation as a percentage completed. The pctDone argument will have a value from 1 to 100. For methods that complete very quickly, the number of PercentDone callbacks will vary, but the final callback should have a value of 100. For long running operations, no more than one callback per percentage point will occur (for example: 1, 2, 3, ... 98, 99, 100).
This callback counts as an AbortCheck callback, and takes the place of the AbortCheck event when it fires.
The return value indicates whether the method call should be aborted, or whether it should proceed. Return TRUE to abort, and FALSE to proceed.
This is a general callback that provides name/value information about what is happening at certain points during a method call. To see the information provided in ProgressInfo callbacks, if any, write code to handle this event and log the name/value pairs. Most are self-explanatory.
Called in the background thread when an asynchronous task completes. (Note: When an async method is running, all callbacks are in the background thread.)
Properties
CloseAutoRespond
void CkWebSocketW_putCloseAutoRespond(HCkWebSocketW cHandle, BOOL newVal);
Controls whether Chilkat automatically answers an incoming Close control frame.
- When
TRUE, 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
FALSE, the application can detect the received Close throughCloseReceivedorFrameOpcodeand callSendCloseitself.
The default is TRUE.
CloseReason
const wchar_t *CkWebSocketW_closeReason(HCkWebSocketW cHandle);
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.
CloseReceived
TRUE after a Close control frame has been received on the current WebSocket connection.
When CloseAutoRespond is FALSE, 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.
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.
0 is an API sentinel; it is not a WebSocket close status transmitted by the peer.
DebugLogFilePath
void CkWebSocketW_putDebugLogFilePath(HCkWebSocketW cHandle, const wchar_t *newVal);
const wchar_t *CkWebSocketW_debugLogFilePath(HCkWebSocketW cHandle);
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
FinalFrame
TRUE if the frame most recently delivered by ReadFrame had its WebSocket FIN bit set; otherwise FALSE.
For a fragmented data message, continue reading while this property is FALSE. The fragment with TRUE completes the message. Unfragmented messages have TRUE on their only frame.
FIN bit is always set.
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.
FinalFrame to determine whether the last received fragment completed the message.
FrameOpcode
const wchar_t *CkWebSocketW_frameOpcode(HCkWebSocketW cHandle);
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.
topFrameOpcodeInt
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.
HeartbeatMs
void CkWebSocketW_putHeartbeatMs(HCkWebSocketW cHandle, int newVal);
Specifies the interval, in milliseconds, between AbortCheck event callbacks during supported blocking operations.
The default is 0, which disables periodic AbortCheck callbacks. Set a positive value when the application needs an opportunity to cancel a long-running send or receive operation.
SendPing and Ping/Pong handling for protocol-level heartbeat behavior.
IdleTimeoutMs
void CkWebSocketW_putIdleTimeoutMs(HCkWebSocketW cHandle, int newVal);
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.
SendPing when the application needs protocol-level keep-alive or responsiveness checks.
IsConnected
TRUE when the underlying WebSocket network connection is currently open; otherwise FALSE.
LastErrorHtml
const wchar_t *CkWebSocketW_lastErrorHtml(HCkWebSocketW cHandle);
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
const wchar_t *CkWebSocketW_lastErrorText(HCkWebSocketW cHandle);
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
const wchar_t *CkWebSocketW_lastErrorXml(HCkWebSocketW cHandle);
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
void CkWebSocketW_putLastMethodSuccess(HCkWebSocketW cHandle, BOOL newVal);
Indicates the success or failure of the most recent method call: TRUE means success, FALSE means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
NeedSendPong
TRUE when a Ping frame has been received but no corresponding Pong has yet been sent.
This property is primarily useful when PingAutoRespond is FALSE. Call SendPong as soon as practical; it automatically sends the received Ping payload in the Pong response.
PingAutoRespond
void CkWebSocketW_putPingAutoRespond(HCkWebSocketW cHandle, BOOL newVal);
Controls automatic handling of incoming Ping control frames.
- When
TRUE, Chilkat sends the required Pong automatically andReadFrameconsumes the Ping internally, continuing until another frame is available. - When
FALSE, the Ping can be returned to the application. CheckNeedSendPongand callSendPongas soon as practical.
The default is TRUE.
SendPong automatically uses the stored payload of the unanswered Ping.
PongAutoConsume
void CkWebSocketW_putPongAutoConsume(HCkWebSocketW cHandle, BOOL newVal);
Controls whether incoming Pong control frames are hidden from the application.
- When
TRUE,ReadFrameconsumes Pong frames internally and continues reading until a non-Pong frame is available. - When
FALSE, an incoming Pong can be returned normally withFrameOpcodeequal toPong.
The default is TRUE. Check PongConsumed after ReadFrame to learn whether one or more Pong frames were consumed during that call.
PongConsumed
TRUE if the most recent call to ReadFrame internally consumed a Pong frame while PongAutoConsume was TRUE.
The property is reset to FALSE at the beginning of each ReadFrame call and set to TRUE if a Pong is consumed during that call.
ReadFrameFailReason
When ReadFrame returns FALSE, 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.
UncommonOptions
const wchar_t *CkWebSocketW_uncommonOptions(HCkWebSocketW cHandle);
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. |
VerboseLogging
void CkWebSocketW_putVerboseLogging(HCkWebSocketW cHandle, BOOL newVal);
If set to TRUE, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is FALSE. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
const wchar_t *CkWebSocketW_version(HCkWebSocketW cHandle);
Methods
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.
Origin, Authorization, cookies, or Sec-WebSocket-Protocol, add them through the associated Rest object before sending the HTTP upgrade request.
Returns TRUE for success, FALSE for failure.
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.
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 TRUE for success, FALSE for failure.
topGetFrameData
const wchar_t *CkWebSocketW_getFrameData(HCkWebSocketW cHandle);
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.
ReadFrame until FinalFrame is TRUE, and then call GetFrameData once. Calling this method earlier returns and clears only the data accumulated so far.
Returns TRUE for success, FALSE for failure.
topGetFrameDataBd
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.
GetFrameData, GetFrameDataSb, or GetFrameDataBd consumes the same internal buffer. Retrieve the data using only the form needed by the application.
GetFrameDataSb
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.
FinalFrame is TRUE before calling this method when the application wants the complete message.
LoadTaskCaller
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 TRUE for success, FALSE for failure.
topPollDataAvailable
Checks whether bytes are currently waiting to be read from the underlying WebSocket connection.
Returns TRUE when incoming data is available and FALSE when no data is presently waiting.
TRUE result does not mean that an entire WebSocket frame or message has arrived. Call ReadFrame to parse the protocol frame. A FALSE result does not indicate that the peer will not send data later.
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.
Call ReadFrame until FinalFrame is TRUE, then retrieve the accumulated message data. A fragmented message begins with a Text or Binary frame and continues with one or more Continuation frames.
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 FALSE, inspect ReadFrameFailReason and LastErrorText.
Returns TRUE for success, FALSE for failure.
ReadFrameAsync (1)
Creates an asynchronous task to call the ReadFrame method with the arguments provided.
Returns NULL on failure
SendClose
Sends a WebSocket Close control frame and begins or completes the closing handshake.
- If
includeStatusisFALSE, the Close frame contains no status code andstatusCodeandreasonare ignored. - If
includeStatusisTRUE, the frame containsstatusCodefollowed by the UTF-8 bytes ofreason.
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.
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.
Returns TRUE for success, FALSE for failure.
topSendCloseAsync (1)
Creates an asynchronous task to call the SendClose method with the arguments provided.
Returns NULL on failure
SendFrame
Sends one WebSocket text data frame containing stringToSend. WebSocket text data is UTF-8 on the wire.
- Set
finalFrametoTRUEwhen this frame completes the message. - Set
finalFrametoFALSEwhen 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 TRUE. For a fragmented message, call it repeatedly and set TRUE only for the final fragment.
Returns TRUE for success, FALSE for failure.
SendFrameAsync (1)
Creates an asynchronous task to call the SendFrame method with the arguments provided.
Returns NULL on failure
SendFrameBd
Sends one WebSocket binary data frame containing the current bytes in bdToSend.
- Set
finalFrametoTRUEwhen this frame completes the binary message. - Set
finalFrametoFALSEwhen additional binary-message fragments will follow.
For an ordinary single-frame binary message, set finalFrame to TRUE.
bdToSend become the frame payload, while Chilkat applies the client-side WebSocket framing and masking required by the protocol.
Returns TRUE for success, FALSE for failure.
SendFrameBdAsync (1)
Creates an asynchronous task to call the SendFrameBd method with the arguments provided.
Returns NULL on failure
SendFrameSb
Sends one WebSocket text data frame containing the current contents of sbToSend.
- Set
finalFrametoTRUEwhen this frame completes the message. - Set
finalFrametoFALSEwhen more fragments will follow.
For an ordinary single-frame text message, set finalFrame to TRUE. WebSocket text data is UTF-8 on the wire.
finalFrame set to FALSE create fragments of the same text message. Complete the message with a final call that passes TRUE.
Returns TRUE for success, FALSE for failure.
topSendFrameSbAsync (1)
Creates an asynchronous task to call the SendFrameSb method with the arguments provided.
Returns NULL on failure
SendPing
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.
Returns TRUE for success, FALSE for failure.
SendPingAsync (1)
Creates an asynchronous task to call the SendPing method with the arguments provided.
Returns NULL on failure
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.
PingAutoRespond is FALSE and NeedSendPong is TRUE. When automatic Ping handling is enabled, Chilkat sends the Pong internally.
Returns TRUE for success, FALSE for failure.
topSendPongAsync (1)
Creates an asynchronous task to call the SendPong method with the arguments provided.
Returns NULL on failure
ShareConnection
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.
Returns TRUE for success, FALSE for failure.
UseConnection
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.
- Connect the
Restobject to the server. - Call
UseConnection. - Call
AddClientHeaders. - Send the HTTP
GETrequest with theRestobject. - Call
ValidateServerHandshake.
Returns TRUE for success, FALSE for failure.
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 TRUE, the connection has entered the WebSocket protocol and data or control frames may be exchanged.
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 TRUE for success, FALSE for failure.