Write data to the specified client session.

Syntax

object.Write( Handle, Buffer, [Length] )

Parameters

Handle

An integer value that specifies the handle to the client session.

Buffer

A buffer variable that contains the data to be written to the server. If the variable is a String type, then the data will be written as a string of characters. This is the most appropriate data type to use if the server expects text data that consists of printable characters. If the server is expecting binary data, it is recommended that a Byte array be used instead.

Length

A numeric value which specifies the number of bytes to write. Its maximum value is 2³¹-1 = 2147483647. If a value is specified for this argument and it is greater than the actual size of the buffer, then the Length argument will be ignored and the entire contents of the buffer will be written. If the argument is omitted, then the maximum number of bytes to write is determined by the size of the buffer.

Return Value

This method returns the number of bytes actually written to the socket, or -1 if an error was encountered.

Remarks

The Write method sends the data in Buffer to the specified client socket. Typically the data is copied to an internal buffer and control is immediately returned to the calling thread. If the buffer is full, the current thread will block until the data can be sent. If the client does not acknowledge the data that is being sent to it, this method will eventually fail with an error indicating that the connection has been aborted.

If the data contains binary characters, particularly non-printable control characters and embedded nulls, you should always provide a Byte array to the Write method. When you provide a String variable as the buffer, the control will process the data as text. If the string contains Unicode characters, it will automatically be converted to 8-bit encoded text prior to being written. Using a byte array ensures that binary data will be sent as-is without being encoded.

See Also

CodePage Property, IsWritable Property, Timeout Property, Read Method, Write Method, OnWrite Event

Copyright © 2023 Catalyst Development Corporation. All rights reserved.