TChilkatWebSocket

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.

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.

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.

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.

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.

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.

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.

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

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.

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

Use FrameOpcode when a readable symbolic value is preferred.

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.

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.

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

This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.

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.

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.

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.

Indicates the success or failure of the most recent method call: 1 means success, 0 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.

In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.

The length, in characters, of the string contained in the LastStringResult property.

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.

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.

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.

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.

When ReadFrame returns 0, this property categorizes the reason:

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

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

If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

Version of the component/library, such as "10.1.0"

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns a zero-length WideString on failure

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.

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.

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.

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.

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReadFrame method with the arguments provided.

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendClose method with the arguments provided.

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendFrame method with the arguments provided.

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendFrameBd method with the arguments provided.

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendFrameSb method with the arguments provided.

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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 1 for success, 0 for failure.

Creates an asynchronous task to call the SendPing method with the arguments provided.

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendPong method with the arguments provided.

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.

Delphi ActiveX Event callback implementation:

procedure TForm1.websocketAbortCheck(ASender: TObject;  out abort: Integer);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  websocket: TChilkatWebSocket;

begin
  websocket := TChilkatWebSocket.Create(Self);
  websocket.OnAbortCheck := websocketAbortCheck;
  // ...

This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pctDone argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pctDone equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).

The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.

To abort the operation, set the abort output argument to 1. This will cause the method to terminate and return a failure status or corresponding failure value.

Delphi ActiveX Event callback implementation:

procedure TForm1.websocketPercentDone(ASender: TObject;  pctDone: Integer; out abort: Integer);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  websocket: TChilkatWebSocket;

begin
  websocket := TChilkatWebSocket.Create(Self);
  websocket.OnPercentDone := websocketPercentDone;
  // ...

This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.

Note: Some Chilkat methods don't fire any ProgressInfo events.

Delphi ActiveX Event callback implementation:

procedure TForm1.websocketProgressInfo(ASender: TObject;  const name: WideString; const value: WideString);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  websocket: TChilkatWebSocket;

begin
  websocket := TChilkatWebSocket.Create(Self);
  websocket.OnProgressInfo := websocketProgressInfo;
  // ...

Called from the background thread when an asynchronous task completes.

Delphi ActiveX Event callback implementation:

procedure TForm1.websocketTaskCompleted(ASender: TObject;  const task: IChilkatTask);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  websocket: TChilkatWebSocket;

begin
  websocket := TChilkatWebSocket.Create(Self);
  websocket.OnTaskCompleted := websocketTaskCompleted;
  // ...