Ping Method

Overload 1

Syntax

procedure Ping(const aText: String = '');

Parameters

Name	Type	Description
aText	const String	Optional payload to carry inside the ping frame; pass an empty string to send a ping with no payload.

Remarks

This overload fires the ping and returns straight away, without blocking the caller or waiting for the matching pong. When the client has no connection, nothing is sent and the failure is reported through OnError with Connection = nil and the error Data not sent, the client is not connected or its handshake has not completed. The event fires on the calling thread before Ping returns, and no exception is raised to the caller. Set Options.RaiseDisconnectExceptions to False to skip this report. A ping sent before the WebSocket handshake has completed is not reported as an error, because the HeartBeat pings through this method too. Any pong received from the server is delivered asynchronously through the standard connection events. Internally exceptions are trapped and routed to OnError. Use the timeout overload of the other overload when you need confirmation that the peer is still reachable.

Example

oClient.Ping('keepalive');

Overload 2

Syntax

function Ping(aTimeout: Integer; const aText: String = '') : Boolean;

Parameters

Name	Type	Description
aTimeout	Integer	Maximum time in milliseconds to wait for the pong reply before giving up.
aText	const String	Optional payload to carry inside the ping frame; pass an empty string to send a ping with no payload.

Return Value

True if the server replied with a matching pong inside the timeout window; False otherwise. When False is returned the client may choose to close the connection because the peer is considered unreachable. (Boolean)

Remarks

This overload blocks the calling thread until either the pong arrives or the timeout elapses, so it is useful for interactive liveness checks. The method returns False immediately when the client has no connection, and reports it through OnError with Connection = nil, as described for the other overload. Exceptions raised by the underlying socket are caught and forwarded to OnError. For a fire-and-forget ping that does not block, use the parameterless the other overload overload instead.

Example

if not oClient.Ping(5000, 'healthcheck') then
  oClient.Disconnect;