Write data to the socket.

Syntax

object.Write( Buffer, [Length], [Options], [RemoteAddress], [RemotePort] )

Parameters

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 string contains Unicode characters, it will be automatically converted to use standard UTF-8 encoding prior to being sent. If the server is expecting binary data, a Byte array should be used instead.

Length

An optional integer value that specifies the maximum number of bytes to send to the server. Its maximum value is 2³¹-1 = 2147483647. This argument is not required for string data. If a value is specified for this argument for other permissible types of data, and it is less than number of bytes that is determined by the control, then Length will override the internally-computed value. If the socket is non-blocking and the send fails because it could not write all of the data to the server, the OnWrite event will be fired when the server can be written to again.

Options

An optional integer value that is reserved for future functionality and should either be omitted, or specified with a value of zero. Specifying a non-zero value will cause the method to fail and return an error.

RemoteAddress

An optional string value that specifies the IP address of the remote host that the data will be sent to. For a TCP connection, it is recommended that this argument be omitted. If it is specified, the IP address must be the same value that was used to establish the connection. When writing data to a UDP socket, this is the IP address of the peer that will receive the datagram. This information can be used in conjunction with the Read method to send a datagram back to that host.

RemotePort

An optional integer value that specifies the port number on the remote host that the data will be sent to. For a TCP connection, it is recommended that this argument be omitted. If it is specified, the port number must be the same value that was used to establish the connection. When writing data on a UDP socket, this is the port number for the peer who will receive the datagram. This information can be used in conjunction with the Read method to send a datagram back to that host.

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 socket. If the connection is buffered, as is typically the case, the data is copied to the send buffer and control immediately returns to the program. If the control is non-blocking and is out of buffer space, an error will be generated. If the control is blocking, the application will wait until the data can be sent.

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 non-ASCII characters, by default they will automatically be converted to 8-bit ANSI encoded text prior to being written. Using a byte array ensures that binary data will be sent as-is without being encoded.

If you want to send text to the remote host a line at a time, use the WriteLine method. If you wish to send a large amount of data using a single method call rather than making multiple calls to the Write method, use the WriteStream method.

See Also

CodePage Property, IsWritable Property, Timeout Property, Read Method, WriteLine Method, WriteStream Method, OnWrite Event

Copyright © 2023 Catalyst Development Corporation. All rights reserved.