LPFN_TRANSMITPACKETS callback function (mswsock.h)
The TransmitPackets function transmits in-memory data or file data over a connected socket. The TransmitPackets function uses the operating system cache manager to retrieve file data, locking memory for the minimum time required to transmit and resulting in efficient, high-performance transmission.
Syntax
LPFN_TRANSMITPACKETS LpfnTransmitpackets;
BOOL LpfnTransmitpackets(
SOCKET hSocket,
LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
DWORD nElementCount,
DWORD nSendSize,
LPOVERLAPPED lpOverlapped,
DWORD dwFlags
)
{...}
Parameters
hSocket
A handle to the connected socket to be used in the transmission. Although the socket does not need to be a connection-oriented circuit, the default destination/peer should have been established using the connect, WSAConnect, accept, WSAAccept, AcceptEx, or WSAJoinLeaf function.
lpPacketArray
An array of type TRANSMIT_PACKETS_ELEMENT, describing the data to be transmitted.
nElementCount
The number of elements in lpPacketArray.
nSendSize
The size, in bytes, of the data block used in the send operation. Set nSendSize to zero to let the sockets layer select a default send size.
Setting nSendSize to 0xFFFFFFF enables the caller to control the size and content of each send request, achieved by using the TP_ELEMENT_EOP flag in the TRANSMIT_PACKETS_ELEMENT array pointed to in the lpPacketArray parameter. This capability is useful for message protocols that place limitations on the size of individual send requests.
lpOverlapped
A pointer to an OVERLAPPED structure. If the socket handle specified in the hSocket parameter has been opened as overlapped, use this parameter to achieve asynchronous (overlapped) I/O operation. Socket handles are opened as overlapped by default.
dwFlags
A set of flags used to customize processing of the TransmitPackets function. The following table outlines the use of the dwFlags parameter.
| Value | Meaning |
|---|---|
|
Starts a transport-level disconnect after all the file data has been queued for transmission. Applies only to connection-oriented sockets. Specifying this flag for sockets that do not support disconnect semantics (such as datagram sockets) results in an error. |
|
Prepares the socket handle to be reused. When the
TransmitPackets function completes, the socket handle can be passed to the
AcceptEx function. Valid only when a connection-oriented socket and TF_DISCONNECT are specified.
Note The socket level packet transmit is subject to the behavior of the underlying transport. For example, a TCP socket may be subject to the TCP TIME_WAIT state, causing the TransmitPackets call to be delayed.
|
|
Directs Winsock to use the system's default thread to process long
TransmitPackets requests. Long
TransmitPackets requests are defined as requests that require more than a single read from the file or a cache; the long request definition therefore depends on the size of the file and the specified length of the send packet.
The system default thread can be adjusted using the following registry parameter as a REG_DWORD:HKEY_LOCAL_MACHINE\CurrentControlSet\Services\AFD\Parameters\TransmitWorker |
|
Directs Winsock to use system threads to process long TransmitPackets requests. Long TransmitPackets requests are defined as requests that require more than a single read from the file or a cache; the long request definition therefore depends on the size of the file and the specified length of the send packet. |
|
Directs Winsock to use kernel Asynchronous Procedure Calls (APCs) instead of worker threads to process long TransmitPackets requests. Long TransmitPackets requests are defined as requests that require more than a single read from the file or a cache; the long request definition therefore depends on the size of the file and the specified length of the send packet. See Remarks for more information. |
Return value
If the TransmitPackets function succeeds, the return value is TRUE. Otherwise, the return value is FALSE. To get extended error information, call WSAGetLastError. An error code of WSA_IO_PENDING or ERROR_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be indicated at a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no completion indication will occur. Applications should handle either ERROR_IO_PENDING or WSA_IO_PENDING in this case.
| Return code | Description |
|---|---|
| An established connection was aborted by the software in your host machine. This error is returned if the virtual circuit was terminated due to a time-out or other failure. | |
| An existing connection was forcibly closed by the remote host. This error is returned for a stream socket when the virtual circuit was reset by the remote side. The application should close the socket as it is no longer usable. | |
| The system detected an invalid pointer address in attempting to use a pointer argument in a call. This error is returned if the lpPacketArray or the lpOverlapped parameter is not totally contained in a valid part of the user address space. | |
| An invalid argument was supplied. This error is returned if the dwFlags parameter has the TF_REUSE_SOCKET flag set, but the TF_DISCONNECT flag was not set. This error is also returned if the offset specified in the OVERLAPPED structure pointed to by the lpOverlapped is not within the file. This error is also returned if the total number of bytes to be transmitted is a value greater than 2,147,483,646, the maximum value for a 32-bit integer minus 1. | |
| A socket operation encountered a dead network.This error is returned if the network subsystem has failed. | |
| The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress. This error is returned for a stream socket where the connection was broken due to keep-alive activity detecting a failure. | |
| An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full. This error is also returned if the Windows Sockets provider reports a buffer deadlock. | |
| A request to send or receive data was disallowed because the socket is not connected. This error is returned for a stream socket. | |
| An operation was attempted on something that is not a socket. This error is returned if the hSocket parameter is not a socket. | |
| A request to send or receive data was disallowed because the socket had already been shut down in that direction with a previous shutdown call. This error is returned if a stream socket has been shut down for sending. It is not possible to call TransmitFile on a stream socket after the shutdown function has been called on the socket with the how parameter set to SD_SEND or SD_BOTH. | |
| Either the application has not called the WSAStartup function, or WSAStartup failed. A successful WSAStartup call must occur before using the TransmitFile function. | |
| An overlapped I/O operation is in progress. This value is returned if an overlapped I/O operation was successfully initiated and indicates that completion will be indicated at a later time. | |
|
The I/O operation has been aborted because of either a thread exit or an application request. This error is returned if the overlapped operation has been canceled due to the closure of the socket, the execution of the "SIO_FLUSH" command in
WSAIoctl, or the thread that initiated the overlapped request exited before the operation completed.
Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous operations can fail if the thread is closed before the asynchronous operations complete. For more information, see ExitThread.
|
Remarks
The TransmitPackets function is optimized according to the operating system on which it is used:
- On Windows server editions, the TransmitPackets function is optimized for high performance.
- On Windows client editions, the TransmitPackets function is optimized for minimum memory and resource utilization.
The maximum number of bytes that can be transmitted using a single call to the TransmitPackets function is 2,147,483,646, the maximum value for a 32-bit integer minus 1. If an application needs to transmit data larger than 2,147,483,646 bytes, then multiple calls to the TransmitPackets function can be used with each call transferring no more than 2,147,483,646 bytes.
Expect better performance results when using the TransmitPackets function on Windows Server 2003.
When lpOverlapped is not NULL, overlapped I/O might not finish before the TransmitPackets function returns. When this occurs, the TransmitPackets function returns fails, and a call to the WSAGetLastError function returns ERROR_IO_PENDING, allowing the caller to continue processing while the transmission completes.
TransmitPackets and Asynchronous Procedure Calls (APCs)
Use of the TF_USE_KERNEL_APC flag can deliver significant performance benefits. If the thread initiating the TransmitPackets function call is being used for heavy computations, it is possible, though unlikely, that APCs could be prevented from launching.
- Kernel APCs launch when a thread is in a wait state.
- User-mode APCs launch when a thread is in an alertable wait state.
Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8.1, Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | mswsock.h |