Read the socket and store the data stream in the specified buffer.

Syntax

object.ReadStream( Buffer, [Length], [Marker], [Options] )

Parameters

Buffer

A variable that will contain the data read from the socket when the method returns. If the variable is a String type, then the data will be stored as a string of characters. This is the most appropriate data type to use if the server is sending text data that consists of printable characters. If the remote host is sending binary data, a Byte array should be used instead. This parameter must be passed by reference.

Length

A numeric variable which specifies the maximum amount of data to be read from the socket. When the method returns, this variable will be updated with the actual number of bytes read. Note that because this argument is passed by reference and modified by the method, you must provide a variable, not a numeric constant. If this argument is omitted or the value is initialized to zero, this method will read data from the socket until the remote host disconnects or an error occurs.

Marker

A string or array of bytes which is used to designate the logical end of the data stream. When this byte sequence is encountered by the method, it will stop reading and return to the caller. The buffer will contain all of the data read from the socket up to and including the end-of-stream marker. If this argument is omitted, then the function will continue to read from the socket until the maximum buffer size is reached, the remote host closes its socket or an error is encountered.

Options

An optional integer value which specifies any options to be used when reading the data stream. One or more of the following bit flags may be specified by the caller:

Value	Constant	Description
0	swStreamDefault	The data stream will be returned to the caller unmodified. This option should always be used with binary data or data being stored in a byte array. If no options are specified, this is the default option used by this method.
1	swStreamConvert	The data stream is considered to be textual and will be modified so that end-of-line character sequences are converted to follow standard Windows conventions. This will ensure that all lines of text are terminated with a carriage-return and linefeed sequence. Because this option modifies the data stream, it should never be used with binary data. Using this option may result in the amount of data returned in the buffer to be larger than the source data. For example, if the source data only terminates a line of text with a single linefeed, this option will have the effect of inserting a carriage-return character before each linefeed.

Return Value

This method returns a Boolean value. If the method succeeds, the return value is True. If the function fails, the return value is False. To get extended error information, check the value of the LastError property.

Remarks

The ReadStream method enables an application to read an arbitrarily large stream of data and store it in memory, either in a string or a byte array. Unlike the Read method, which will return immediately when any amount of data has been read, the ReadStream method will only return when the buffer is full as specified by the Length argument, the logical end-of-stream marker has been read, the socket closed by the remote host or when an error occurs.

If the data contains binary characters, particularly non-printable control characters and embedded nulls, you should always provide a Byte array to the ReadStream 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.

This method will force the application to wait until the operation completes. If this method is called and the Blocking property is set to False, it will automatically switch the socket into a blocking mode, read the data stream and then restore the socket to non-blocking mode when it has finished. If another socket operation is attempted while ReadStream is blocked waiting for data from the remote host, an error will occur. It is recommended that this method only be used with blocking (synchronous) socket connections; if the application needs to establish multiple simultaneous connections, it should create worker threads to manage each connection.

It is possible for data to be returned in the buffer even if the method returns False. Applications should also check the value of the Length argument to determine if any data was copied into the buffer. For example, if a timeout occurs while the method is waiting for more data to arrive on the socket, it will return zero; however, data may have already been copied into the buffer prior to the error condition. It is the responsibility of the application to process that data, regardless of the method return value.

Because ReadStream can potentially cause the application to block for long periods of time as the data stream is being read, the control will periodically generate OnProgress events. An application can use this event to update the user interface as the data is being read. Note that an application should never perform a blocking operation inside the event handler.

Example

Dim strBuffer As String
Dim nLength As Long

nLength = 0 ' Read socket until connection is closed
If SocketWrench1.ReadStream(strBuffer, nLength, Options:=swStreamConvert) Then
    TextBox1.Text = strBuffer
End If

See Also

Blocking Property, CodePage Property, Read Method, ReadLine Method, StoreStream Method, WriteStream Method, OnProgress Event

Copyright © 2023 Catalyst Development Corporation. All rights reserved.