Writes data from the stream buffer to the socket.
Syntax
object.WriteStream( Buffer [,
Length] [, Options] )
Remarks
The WriteStream method enables an application to write an
arbitrarily large stream of data from a string buffer or byte array
to the socket. Unlike the Write method, which may not write
all of the data in a single call, the WriteStream method
will only return when all of the data has been written or an error
occurs.
- Buffer
- A variable that contains the data to be written to the socket.
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 expecting text data that consists of printable
characters. If the remote host is expecting 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 written to the socket. When the method returns, this variable
will be updated with the actual number of bytes written. 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 automatically determine the amount of data based on the
length of the string or the size of the byte array passed to the
method.
- Options
- An optional integer value which specifies any options to be
used when writing the data stream to the socket. Currently this
argument is reserved for future expansion and should either be
omitted or always specified with a value of zero.
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, write the data stream and then restore the socket
to non-blocking mode when it has finished. If another socket
operation is attempted while WriteStream is blocked sending
data to 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.
It is possible that some data will have been written to the
socket even if the method returns False. Applications should also
check the value of the Length argument to determine if any
data was sent. For example, if a timeout occurs while the function
is waiting to write more data, it will return zero; however, some
data may have already been written to the socket prior to the error
condition.
Because WriteStream can potentially cause the application
to block for long periods of time as the data stream is being
written, the control will periodically generate OnProgress
events. An application can use this event to update the user
interface as the data is being written. Note that an application
should never perform a blocking operation inside the event
handler.
Return Value
This method returns a boolean value. If the function 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 hFile As Long
Dim nLength As Long
Dim dataBuffer() As Byte
Dim bResult As Boolean
' Open the file for binary access
hFile = FreeFile()
Open strFileName For Binary Access Read As hFile
' Determine the size of the file and allocate a byte
' array large enough to store the contents
nLength = LOF(hFile)
ReDim dataBuffer(nLength - 1) As Byte
' Read the file contents into the byte array and
' then close the file
Get hFile, , dataBuffer
Close hFile
' Write the data to the socket
bResult = SocketWrench1.WriteStream(dataBuffer, nLength)
See Also
Blocking Property,
ReadStream Method, StoreStream Method, Write Method, OnProgress Event
|