Return data read from the socket.

Syntax

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

Parameters

Buffer

A buffer that the data will be stored in. If the variable is a String then the data will be returned as a string of characters. This is the most appropriate data type to use if the server is sending data that consists of printable characters. If the server is sending binary data, a Byte array should be used instead. This parameter must be passed by reference.

Length

An optional integer value which specifies the number of bytes to read. Its maximum value is 2³¹-1 = 2147483647. This argument is required to be present 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 argument is omitted, then the maximum number of bytes to read is determined by the size of the buffer.

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 that will contain the IP address of the remote host when the method returns. This parameter must be passed by reference. For a TCP connection, the IP address is the same value that was used to establish the connection. When reading data from a UDP socket, this is the IP address of the peer that sent the datagram. This information can be used in conjunction with the Write method to send a datagram back to that host. If the peer's IP address is not required, this parameter may be omitted.

RemotePort

An optional integer that will contain the port number for the remote host when the method returns. This parameter must be passed by reference. When reading a datagram from a UDP socket, this is the port number used by the peer who sent the datagram. This information can be used in conjunction with the Write method to send a datagram back to that host. If the peer's port number is not required, this parameter may be omitted.

Return Value

The number of bytes actually read from the socket is returned by this method. If an error occurs, a value of -1 is returned.

Remarks

The Read method returns data that has been read from the socket, up to the number of bytes specified. If no data is available to be read, an error will be generated if the control is non-blocking mode. If the control is in blocking mode, the program will wait until data is returned by the server or the connection is closed.

If the data contains binary characters, particularly non-printable control characters and embedded nulls, you should always provide a Byte array to the Read method. When you provide a String variable as the buffer, the control will process the data as text. Binary characters may be interpreted as 8-bit ANSI encoding and embedded null characters will corrupt the data. Reading the data into a byte array ensures that you receive the data exactly as it was sent by the server.

If the remote host is sending text that you want to read a line at a time, use the ReadLine method. If you wish to read a large amount of data using a single method call rather than making multiple calls to the Read method, use the ReadStream method.

See Also

CodePage Property, IsReadable Property, ReadLine Method, ReadStream Method Write Method, OnRead Event, OnWrite Event

Copyright © 2023 Catalyst Development Corporation. All rights reserved.