| |
Reads the data stream from the socket and stores it in a specified
file.
Syntax
object.StoreStream( FileName,
[Length], [Offset], [Options] )
Parameters
- 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 |
Description |
| 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. |
| 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 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.
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.
See Also
Blocking Property,
ReadStream Method,
WriteStream Method,
OnProgress Event
|
|