|
|
Read the socket and store the data stream in the specified
buffer.
Syntax
object.ReadStream( Buffer [, Length]
[, Marker] [, Options] )
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.
- Buffer
- A variable that will contain the data read from the socket when
the method returns. If the variable is a String 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,
it is recommended that a Byte array be used instead.
- 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. |
This method will force the thread to block 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.
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.
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,
Read Method, StoreStream Method, WriteStream Method, OnProgress Event
|
|