| |
| BOOL WINAPI InetWriteStream( |
| |
SOCKET hSocket, |
|
| |
LPVOID lpvBuffer, |
|
| |
LPDWORD lpdwLength, |
|
| |
DWORD dwOptions |
|
| ); |
The InetWriteStream function writes data from the stream
buffer to the specified socket.
Parameters
- hSocket
- The socket handle. The socket must reference a stream socket,
not a datagram or raw socket. If the socket type is not valid, the
function will return an error.
- lpvBuffer
- Pointer to the buffer that contains or references the data to
be written to the socket. The actual argument depends on the value
of the dwOptions parameter which specifies how the data
stream will be accessed.
- lpdwLength
- A pointer to an unsigned integer value which specifies the size
of the buffer and contains the number of bytes written when the
function returns. This argument should should always point to an
initialized value. If the lpvBuffer argument specifies a
memory buffer or global memory handle, then this argument cannot
point to an initialized value of zero.
- dwOptions
- An unsigned integer value which specifies the stream buffer
type to be used when writing the data stream to the socket. One of
the following stream types may be specified:
| Constant |
Description |
| INET_STREAM_DEFAULT |
The default stream buffer type is determined by the value
passed as the lpvBuffer parameter. If the argument
specifies a a global memory handle, then the function will
write the data referenced by that handle; otherwise, the
function will consider the parameter a pointer to a block of
memory which contains data to be written. In most cases, it
is recommended that an application explicitly specify the
stream buffer type rather than using the default value. |
| INET_STREAM_MEMORY |
The lpvBuffer argument specifies a pointer to a
block of memory which contains the data to be written to the
socket. If this stream buffer type is used, the
lpdwLength argument must point to an unsigned integer
which has been initialized with the size of the buffer. |
| INET_STREAM_HGLOBAL |
The lpvBuffer argument specifies a global memory
handle that references the data to be written to the socket.
The handle must have been created by a call to the
GlobalAlloc or GlobalReAlloc function. If this stream buffer
type is used, the lpdwLength argument must point to an
unsigned integer which has been initialized with the size of
the buffer. |
| INET_STREAM_HANDLE |
The lpvBuffer argument specifies a Windows handle
to an open file, console or pipe. This should be the same
handle value returned by the CreateFile function in the
Windows API. The data read using the ReadFile function with
this handle will be written to the socket. |
| INET_STREAM_SOCKET |
The lpvBuffer argument specifies a socket handle.
The data read from the socket specified by this handle will
be written to the socket specified by the hSocket
parameter. The socket handle passed to this function must
have been created by this library; if it is a socket created
by an third-party library or directly by the Windows Sockets
API, you should either attach the socket using the
InetAttachSocket function or use the INET_STREAM_HANDLE
stream buffer type instead. |
Return Value
If the function succeeds, the return value is non-zero. If the
function fails, the return value is zero. To get extended error
information, call InetGetLastError.
Remarks
The InetWriteStream function enables an application to
write an arbitrarily large stream of data from memory or a file to
the specified socket. Unlike the InetWrite function, which
may not write all of the data in a single function call,
InetWriteStream will only return when all of the data has
been written or an error occurs.
This function will force the thread to block until the operation
completes. If this function is called with asynchronous events
enabled, it will automatically switch the socket into a blocking
mode, write the data stream and then restore the socket to
asynchronous operation when it has finished. If another socket
operation is attempted while InetWriteStream 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 for some data to have been written even if the
function returns a value of zero. Applications should also check
the value of the lpdwLength 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 InetWriteStream can potentially cause the
application to block for long periods of time as the data stream is
being written, the function will periodically generate INET_EVENT_PROGRESS
events. An application can register an event handler using the
InetRegisterEvent function, and can obtain information about the
current operation by calling the InetGetStreamInfo function.
Example
HANDLE hFile;
DWORD dwLength;
hFile = CreateFile(lpszFileName,
GENERIC_READ,
FILE_SHARE_READ,
NULL,
OPEN_EXISTING,
FILE_FLAG_SEQUENTIAL_SCAN,
NULL);
if (hFile == INVALID_HANDLE_VALUE)
return;
dwLength = GetFileSize(hFile, NULL);
if (dwLength > 0)
{
BOOL bResult = InetWriteStream(
hSocket,
hFile,
&dwLength,
INET_STREAM_HANDLE);
}
CloseHandle(hFile);
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
See Also
InetGetStreamInfo, InetRead, InetReadLine, InetReadStream, InetStoreStream, InetWrite, InetWriteLine
|
|