Writes data from the stream buffer to the socket.

Syntax

object.WriteStream( Buffer, [Length], [Options] )

Parameters

Buffer

A variable that contains the data to be written to the socket. 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 expecting text data that consists of printable characters. If the string contains Unicode characters, it will be automatically converted to use standard UTF-8 encoding prior to being sent. If the server is expecting binary data, a Byte array should 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.

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.

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.

If the data contains binary characters, particularly non-printable control characters and embedded nulls, you should always provide a Byte array to the WriteStream method. When you provide a String variable as the buffer, the control will process the data as text. If the string contains Unicode characters, they will automatically be converted to 8-bit ANSI encoded text prior to being written. Using a byte array ensures that binary data will be sent as-is without being encoded. You can change the default code page used to convert the text by setting the CodePage property.

This method will force the application to wait 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 wait 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.

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, CodePage Property, ReadStream Method, StoreStream Method, Write Method, OnProgress Event

Copyright © 2023 Catalyst Development Corporation. All rights reserved.