WriteData Method

Overload 1

Syntax

procedure WriteData(const aText: String; const aSize: Integer = 0; const aStreaming: TwsStreaming = stmNone);

Parameters

Name	Type	Description
aText	const String	The text payload to send to the server as a WebSocket text frame.
aSize	const Integer	Optional fragment size in bytes; when greater than zero the message is split into multiple fragments of this size. Use 0 (the default) to send the whole message 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.

Remarks

WriteData transmits the string as a WebSocket text frame on the active connection. By default the call runs on the calling thread and returns once the bytes are handed to the socket. When QueueOptions.Text is set to a value other than qmNone, the message is queued and actually sent from the connection's own thread, which prevents locks when several threads write concurrently. Any socket exception is forwarded to OnError. Use the stream overload when sending large payloads or binary data.

When the client is not connected, or its WebSocket handshake has not completed yet, 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. (resourcestring S_ERROR_CLIENT_NOT_CONNECTED). The event fires on the calling thread before WriteData 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 and drop the message silently, as earlier versions did. 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

oClient.WriteData('My First sgcWebSockets Message!.');

Overload 2

Syntax

procedure WriteData(const aStream: TStream; const aSize: Integer = 0; const aStreaming: TwsStreaming = stmNone);

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

Remarks

WriteData reads the supplied stream from its current position and transmits the contents as a WebSocket binary frame. The call runs on the calling thread by default; when QueueOptions.Binary is set to a value other than qmNone, the message is queued and actually dispatched from the connection thread. Socket exceptions are captured and forwarded to OnError. When the client is not connected, or its handshake has not completed yet, nothing is sent and the failure is reported through OnError with Connection = nil, as described for the text overload. Free the stream only after the call returns (or, when queuing, after the send is complete).

Example

oStream := TMemoryStream.Create;
try
  oStream.LoadFromFile('payload.bin');
  oClient.WriteData(oStream);
finally
  oStream.Free;
end;