BOOL StoreStream(
	LPCTSTR lpszFileName,
	DWORD dwLength,
	LPDWORD lpdwCopied
	DWORD dwOffset,
	DWORD dwOptions
);

The StoreStream method reads the socket data stream and stores the contents in the specified file.

Parameters

lpszFileName

Pointer to a string which specifies the name of the file to create or overwrite.

dwLength

An unsigned integer which specifies the maximum number of bytes to read from the socket and write to the file. If this value is zero, then the method will continue to read data from the socket until the remote host disconnects or an error occurs.

lpdwCopied

A pointer to an unsigned integer value which will contain the number of bytes written to the file when the method returns.

dwOffset

An unsigned integer 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. A value of zero specifies that the file should be completely overwritten if it already exists.

dwOptions

An unsigned integer value which specifies one or more options. Programs can use a bitwise operator to combine any of the following values:

Constant	Description
INET_STREAM_CONVERT	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 written to the file 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.
INET_STREAM_UNICODE	The data stream should be converted to Unicode. This option should only be used with text data, and will result in the stream data being written as 16-bit wide characters rather than 8-bit bytes. The amount of data returned will be twice the amount read from the source data stream. If the dwOffset parameter has a value of zero, the Unicode byte order mark (BOM) will be written to the beginning of the file.

Return Value

If the method succeeds, the return value is non-zero. If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The StoreStream method enables an application to read an arbitrarily large stream of data 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 memory buffers or handles.

This method will force the thread to block until the operation completes. If this method is called with asynchronous events enabled, it will automatically switch the socket into a blocking mode, read the data stream and then restore the socket to asynchronous operation 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 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.

Because StoreStream can potentially cause the application to block for long periods of time as the data stream is being read, the method will periodically generate INET_EVENT_PROGRESS events. An application can register an event handler using the RegisterEvent method, and can obtain information about the current operation by calling the GetStreamInfo method.

Example

DWORD dwCopied;
BOOL bResult;

bResult = pSocket->StoreStream(lpszFileName, 0, &dwCopied, 0,
                               INET_STREAM_CONVERT);

if (bResult && dwCopied > 0)
{
    // The data has been written to the file
}

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header: Include cswsock10.h
Import Library: cswskv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

GetStreamInfo, Read, ReadLine, ReadStream, Write, WriteLine, WriteStream

Copyright © 2023 Catalyst Development Corporation. All rights reserved.