Package com.chilkatsoft.chilkat2

Class WebSocket

java.lang.Object

com.chilkatsoft.chilkat2.ChilkatObject

com.chilkatsoft.chilkat2.WebSocket

All Implemented Interfaces:

AutoCloseable

public class WebSocket
extends ChilkatObject

<section class="websocket-summary">

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 true, then retrieve the accumulated data with GetFrameData, GetFrameDataSb, or GetFrameDataBd.

For an extended overview, see WebSocket Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:

Online reference

Constructor Summary

Constructors

Constructor	Description
WebSocket()	Creates a new WebSocket object.

Method Summary

Modifier and Type	Method	Description
void	addClientHeaders()	Adds the standard client opening-handshake headers to the Rest object supplied to UseConnection:
void	closeConnection()	Immediately closes the underlying network connection without completing the WebSocket closing handshake.
boolean	getCloseAutoRespond()	Controls whether Chilkat automatically answers an incoming Close control frame.
String	getCloseReason()	Returns the UTF-8 reason text contained in the received Close control frame.
boolean	getCloseReceived()	true after a Close control frame has been received on the current WebSocket connection.
int	getCloseStatusCode()	Returns the status code contained in the received Close control frame.
boolean	getFinalFrame()	true if the frame most recently delivered by ReadFrame had its WebSocket FIN bit set; otherwise false.
String	getFrameData()	Returns the bytes accumulated by successful calls to ReadFrame as a string, then clears the internal receive buffer.
void	getFrameDataBd(BinData binData)	Appends the bytes accumulated by successful calls to ReadFrame to binData, then clears the internal receive buffer.
int	getFrameDataLen()	Returns the number of payload bytes currently accumulated in the internal receive buffer.
void	getFrameDataSb(StringBuilder sb)	Appends the text represented by the bytes accumulated by successful calls to ReadFrame to sb, then clears the internal receive buffer.
String	getFrameOpcode()	Returns the symbolic opcode of the frame most recently delivered by ReadFrame.
int	getFrameOpcodeInt()	Returns the numeric opcode of the frame most recently delivered by ReadFrame.
int	getHeartbeatMs()	Specifies the interval, in milliseconds, between AbortCheck event callbacks during supported blocking operations.
int	getIdleTimeoutMs()	Specifies the maximum number of milliseconds an active send or receive operation may remain stalled while waiting for additional network progress.
boolean	getIsConnected()	true when the underlying WebSocket network connection is currently open; otherwise false.
boolean	getNeedSendPong()	true when a Ping frame has been received but no corresponding Pong has yet been sent.
boolean	getPingAutoRespond()	Controls automatic handling of incoming Ping control frames.
boolean	getPongAutoConsume()	Controls whether incoming Pong control frames are hidden from the application.
boolean	getPongConsumed()	true if the most recent call to ReadFrame internally consumed a Pong frame while PongAutoConsume was true.
ProgressListener	getProgressListener()	Returns the installed listener, or null.
int	getReadFrameFailReason()	When ReadFrame returns false, this property categorizes the reason:
String	getUncommonOptions()	Contains a comma-separated list of rarely needed compatibility or platform options.
void	onAbortCheck(BooleanSupplier callback)	Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it.
void	onPercentDone(IntPredicate callback)	Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it.
void	onProgressInfo(BiConsumer<String,String> callback)	Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds.
boolean	pollDataAvailable()	Checks whether bytes are currently waiting to be read from the underlying WebSocket connection.
void	readFrame()	Reads the next WebSocket frame from the connected server.
void	sendClose(boolean includeStatus, int statusCode, String reason)	Sends a WebSocket Close control frame and begins or completes the closing handshake.
void	sendFrame(String stringToSend, boolean finalFrame)	Sends one WebSocket text data frame containing stringToSend.
void	sendFrameBd(BinData bdToSend, boolean finalFrame)	Sends one WebSocket binary data frame containing the current bytes in bdToSend.
void	sendFrameSb(StringBuilder sbToSend, boolean finalFrame)	Sends one WebSocket text data frame containing the current contents of sbToSend.
void	sendPing(String pingData)	Sends a WebSocket Ping control frame.
void	sendPong()	Sends a WebSocket Pong control frame.
void	setCloseAutoRespond(boolean value)	Sets the CloseAutoRespond property; see getCloseAutoRespond().
void	setHeartbeatMs(int value)	Sets the HeartbeatMs property; see getHeartbeatMs().
void	setIdleTimeoutMs(int value)	Sets the IdleTimeoutMs property; see getIdleTimeoutMs().
void	setPingAutoRespond(boolean value)	Sets the PingAutoRespond property; see getPingAutoRespond().
void	setPongAutoConsume(boolean value)	Sets the PongAutoConsume property; see getPongAutoConsume().
void	setProgressListener(ProgressListener listener)	Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
void	shareConnection(WebSocket ws)	Causes the calling WebSocket object to share the already-established WebSocket connection owned by ws.
void	useConnection(Rest connection)	Associates this WebSocket object with an existing, connected Rest object and prepares it for a client-side WebSocket session.
void	validateServerHandshake()	Validates the server's response to the WebSocket opening handshake sent through the associated Rest object.

Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject

close, getDebugLogFilePath, getLastErrorHtml, getLastErrorText, getLastErrorXml, getLastMethodSuccess, getVerboseLogging, getVersion, isClosed, setDebugLogFilePath, setLastMethodSuccess, setVerboseLogging, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

WebSocket

public WebSocket()

Creates a new WebSocket object.

Method Details

getCloseAutoRespond

public boolean getCloseAutoRespond()

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 through CloseReceived or FrameOpcode and call SendClose itself.

The default is true.

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.

Returns:

the value of the CloseAutoRespond property

setCloseAutoRespond

public void setCloseAutoRespond(boolean value)

Sets the CloseAutoRespond property; see getCloseAutoRespond().

Parameters:

value - the new value

getCloseReason

public String getCloseReason()

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.

Returns:

the value of the CloseReason property (read-only)

getCloseReceived

public boolean getCloseReceived()

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.

Returns:

the value of the CloseReceived property (read-only)

getCloseStatusCode

public int getCloseStatusCode()

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.

Returns:

the value of the CloseStatusCode property (read-only)

getFinalFrame

public boolean getFinalFrame()

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.

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

Returns:

the value of the FinalFrame property (read-only)

getFrameDataLen

public int getFrameDataLen()

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.

Returns:

the value of the FrameDataLen property (read-only)

getFrameOpcode

public String getFrameOpcode()

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.

Returns:

the value of the FrameOpcode property (read-only)

getFrameOpcodeInt

public int getFrameOpcodeInt()

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.

Returns:

the value of the FrameOpcodeInt property (read-only)

getHeartbeatMs

public int getHeartbeatMs()

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.

Not a WebSocket heartbeat: Despite the property name, this setting does not transmit Ping frames and does not monitor peer liveness. Use SendPing and Ping/Pong handling for protocol-level heartbeat behavior.

Returns:

the value of the HeartbeatMs property

setHeartbeatMs

public void setHeartbeatMs(int value)

Sets the HeartbeatMs property; see getHeartbeatMs().

Parameters:

value - the new value

getIdleTimeoutMs

public int getIdleTimeoutMs()

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.

Returns:

the value of the IdleTimeoutMs property

setIdleTimeoutMs

public void setIdleTimeoutMs(int value)

Sets the IdleTimeoutMs property; see getIdleTimeoutMs().

Parameters:

value - the new value

getIsConnected

public boolean getIsConnected()

true when the underlying WebSocket network connection is currently open; otherwise false.

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.

Returns:

the value of the IsConnected property (read-only)

getNeedSendPong

public boolean getNeedSendPong()

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.

Returns:

the value of the NeedSendPong property (read-only)

getPingAutoRespond

public boolean getPingAutoRespond()

Controls automatic handling of incoming Ping control frames.

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

The default is true.

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.

Returns:

the value of the PingAutoRespond property

setPingAutoRespond

public void setPingAutoRespond(boolean value)

Sets the PingAutoRespond property; see getPingAutoRespond().

Parameters:

value - the new value

getPongAutoConsume

public boolean getPongAutoConsume()

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

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

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

Returns:

the value of the PongAutoConsume property

setPongAutoConsume

public void setPongAutoConsume(boolean value)

Sets the PongAutoConsume property; see getPongAutoConsume().

Parameters:

value - the new value

getPongConsumed

public boolean getPongConsumed()

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.

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.

Returns:

the value of the PongConsumed property (read-only)

getReadFrameFailReason

public int getReadFrameFailReason()

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.

Returns:

the value of the ReadFrameFailReason property (read-only)

getUncommonOptions

public String getUncommonOptions()

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.

Returns:

the value of the UncommonOptions property (read-only)

addClientHeaders

public void 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.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

closeConnection

public void 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.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getFrameData

public String 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 true, and then call GetFrameData once. Calling this method earlier returns and clears only the data accumulated so far.

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getFrameDataBd

public void getFrameDataBd(BinData 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.

Parameters:

binData - the binData argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getFrameDataSb

public void getFrameDataSb(StringBuilder 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 true before calling this method when the application wants the complete message.

Parameters:

sb - the sb argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

pollDataAvailable

public boolean pollDataAvailable()

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.

Polling is only a snapshot: A 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.

Returns:

the result; this method never throws ChilkatException

readFrame

public void 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 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.

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 false, inspect ReadFrameFailReason and LastErrorText.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

sendClose

public void sendClose(boolean includeStatus,
 int statusCode,
 String reason)

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

• If includeStatus is false, the Close frame contains no status code and statusCode and reason are ignored.
• If includeStatus is true, 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.

Parameters:

includeStatus - the includeStatus argument

statusCode - the statusCode argument

reason - the reason argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

sendFrame

public void sendFrame(String stringToSend,
 boolean finalFrame)

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

• Set finalFrame to true when this frame completes the message.
• Set finalFrame to false 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 true. For a fragmented message, call it repeatedly and set true 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.

Parameters:

stringToSend - the stringToSend argument (not null)

finalFrame - the finalFrame argument

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

sendFrameBd

public void sendFrameBd(BinData bdToSend,
 boolean finalFrame)

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

• Set finalFrame to true when this frame completes the binary message.
• Set finalFrame to false when additional binary-message fragments will follow.

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

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.

Parameters:

bdToSend - the bdToSend argument (not null)

finalFrame - the finalFrame argument

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

sendFrameSb

public void sendFrameSb(StringBuilder sbToSend,
 boolean finalFrame)

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

• Set finalFrame to true when this frame completes the message.
• Set finalFrame to false when more fragments will follow.

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

Message fragmentation: Repeated calls with finalFrame set to false create fragments of the same text message. Complete the message with a final call that passes true.

Parameters:

sbToSend - the sbToSend argument (not null)

finalFrame - the finalFrame argument

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

sendPing

public void sendPing(String 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.

Parameters:

pingData - the pingData argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

sendPong

public void 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 false and NeedSendPong is true. When automatic Ping handling is enabled, Chilkat sends the Pong internally.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

shareConnection

public void shareConnection(WebSocket ws)

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.

Parameters:

ws - the ws argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

useConnection

public void useConnection(Rest 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.

Parameters:

connection - the connection argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

validateServerHandshake

public void 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.

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.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setProgressListener

public void setProgressListener(ProgressListener listener)

Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.

Parameters:

listener - the listener, or null

Throws:

IllegalStateException - if called from inside one of this object's own callbacks

getProgressListener

public ProgressListener getProgressListener()

Returns the installed listener, or null.

Returns:

the listener installed with setProgressListener(ProgressListener) or one of the on... methods

onAbortCheck

public void onAbortCheck(BooleanSupplier callback)

Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.

Parameters:

callback - the callback, or null to remove the listener

onPercentDone

public void onPercentDone(IntPredicate callback)

Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.

Parameters:

callback - the callback, or null to remove the listener

onProgressInfo

public void onProgressInfo(BiConsumer<String,String> callback)

Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.

Parameters:

callback - the callback, or null to remove the listener