|
|
Reads the data stream from the socket and stores it in a
specified file.
Syntax
object.StoreStream( FileName [,
Length] [, Offset] [, Options] )
Remarks
The StoreStream method enables an application to read an
arbitrarily large stream of data from the socket and store it in a
file. This method is essentially a simplified version of the
ReadStream method, designed specifically to be used with
files rather than strings or byte arrays.
- FileName
- A string variable that specifies the name of the file that will
contain the data read from the socket. If the file does not exist,
it will be created. If the file does exist, it will be
overwritten.
- 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.
- Offset
- A numeric value which specifies the byte offset into the file
where the method will start storing data read from the socket. Note
that all data after this offset will be truncated. If this argument
is omitted or a value of zero is specified the file will be
completely overwritten if it already exists.
- 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 with the Blocking
property 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 StoreStream is blocked waiting
for data from the remote host, an error will occur. It is
recommended that this function 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.
Because StoreStream 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.
See Also
Blocking Property,
ReadStream Method, WriteStream Method, OnProgress Event
|
|