WriteAndWaitData Method

Overload 1

Syntax

function WriteAndWaitData(const aText: String; const aTimeout: Integer = 10000): string;

Parameters

Name	Type	Description
aText	const String	The text payload to send to the server as a WebSocket text frame.
aTimeout	const Integer	Maximum time in milliseconds to wait for the server reply. Defaults to 10000 (10 seconds).

Return Value

The text message received from the server, or an empty string when the timeout expired, no connection was available, or an error occurred. (string)

Remarks

WriteAndWaitData is a convenience helper for request/response style exchanges over a WebSocket. It sends the text frame and then blocks the calling thread on an internal event until the next text message arrives from the server or the timeout fires. Because it blocks, it should not be called from the main UI thread unless a short timeout is used. An empty string is returned when the server does not reply in time; exceptions at the socket level are trapped and forwarded to OnError. Use the stream overload when you need to send and receive binary payloads.

When the client is not connected, or its WebSocket handshake has not completed yet, WriteAndWaitData sends nothing and returns an empty string immediately instead of waiting for the timeout. 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. (resourcestring S_ERROR_CLIENT_NOT_CONNECTED). The event fires on the calling thread before the method returns, and LastError holds the same text. No exception is raised to the caller and the client is not disconnected. Set Options.RaiseDisconnectExceptions to False to skip this report. When a write fails because its connection was lost and the client has already reconnected, the failure is also reported with Connection = nil, so the new connection stays open.

Example

vReply := oClient.WriteAndWaitData('ping', 5000);
if vReply <> '' then
  ShowMessage(vReply);

Overload 2

Syntax

function WriteAndWaitData(const aStream: TStream; const aSize: Integer = 0; const aStreaming: TwsStreaming = stmNone; const aTimeout: Integer = 10000) : TStream;

Parameters

Name	Type	Description
aStream	const TStream	Source stream whose contents will be sent as a WebSocket binary frame. The caller remains the owner of the stream.
aSize	const Integer	Optional fragment size in bytes; when greater than zero the outgoing stream is split into multiple fragments of this size. Use 0 (the default) to send the whole stream as a single frame.
aStreaming	const TwsStreaming	Streaming mode for fragmented transmission (stmNone, stmStart, stmContinue, stmFinish). Defaults to stmNone, which sends a complete standalone message.
aTimeout	const Integer	Maximum time in milliseconds to wait for the server reply. Defaults to 10000 (10 seconds).

Return Value

A newly allocated stream containing the binary message received from the server, or nil when the timeout expired, no connection was available, or an error occurred. The caller is responsible for freeing the returned stream. (TStream)

Remarks

This overload is the binary counterpart to the text the other overload. It writes the supplied stream as a binary frame and then blocks the calling thread on an internal event until the next binary message arrives from the server or the timeout fires. Because it blocks, avoid calling it from the main UI thread with a long timeout. The return value is nil when the server does not reply in time; exceptions are trapped and forwarded to OnError. When the client is not connected, or its handshake has not completed yet, the method returns nil immediately without waiting for the timeout and reports the failure through OnError with Connection = nil, as described for the text overload. Free both the source stream (after the call) and the returned stream when you are done with them.

Example

oRequest := TMemoryStream.Create;
try
  oRequest.LoadFromFile('request.bin');
  oReply := oClient.WriteAndWaitData(oRequest, 0, stmNone, 5000);
  try
    if Assigned(oReply) then
      oReply.SaveToFile('reply.bin');
  finally
    oReply.Free;
  end;
finally
  oRequest.Free;
end;