Expand Minimize

TransmitPackets function

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.

Note  This function is a Microsoft-specific extension to the Windows Sockets specification.

Syntax


BOOL PASCAL TransmitPackets(
  SOCKET hSocket,
  LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
  DWORD nElementCount,
  DWORD nSendSize,
  LPOVERLAPPED lpOverlapped,
  DWORD dwFlags
);

typedef void (*LPFN_TRANSMITPACKETS)();

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.

ValueMeaning
TF_DISCONNECT

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.

TF_REUSE_SOCKET

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.

TF_USE_DEFAULT_WORKER

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

TF_USE_SYSTEM_THREAD

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.

TF_USE_KERNEL_APC

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 codeDescription
WSAECONNABORTED

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.

WSAECONNRESET

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.

WSAEFAULT

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.

WSAEINVAL

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.

WSAENETDOWN

A socket operation encountered a dead network.This error is returned if the network subsystem has failed.

WSAENETRESET

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.

WSAENOBUFS

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.

WSAENOTCONN

A request to send or receive data was disallowed because the socket is not connected. This error is returned for a stream socket.

WSAENOTSOCK

An operation was attempted on something that is not a socket. This error is returned if the hSocket parameter is not a socket.

WSAESHUTDOWN

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.

WSANOTINITIALISED

Either the application has not called the WSAStartup function, or WSAStartup failed. A successful WSAStartup call must occur before using the TransmitFile function.

WSA_IO_PENDING

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.

WSA_OPERATION_ABORTED

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.

Note  The function pointer for the TransmitPackets function must be obtained at run time by making a call to the WSAIoctl function with the SIO_GET_EXTENSION_FUNCTION_POINTER opcode specified. The input buffer passed to the WSAIoctl function must contain WSAID_TRANSMITPACKETS, a globally unique identifier (GUID) whose value identifies the TransmitPackets extension function. On success, the output returned by the WSAIoctl function contains a pointer to the TransmitPackets function. The WSAID_TRANSMITPACKETS GUID is defined in the Mswsock.h header file.

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.

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 operations complete. See ExitThread for more information.

When the TransmitPackets function returns TRUE or returns FALSE and WSAGetLastError returns ERROR_IO_PENDING, Windows sets the event specified by the hEvent member of the OVERLAPPED structure or the socket specified by hSocket to the signaled state, and upon completion, delivers notification to any completion port associated with the socket. Use GetOverlappedResult, or WSAGetOverlappedResult, or GetQueuedCompletionStatus to retrieve final status and number of bytes transmitted.

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.

Note  There is a difference between kernel and user-mode APCs:

  • 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 Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

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

Minimum supported client

Windows 8.1, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Minimum supported phone

Windows Phone 8

Header

Mswsock.h

See also

Winsock Reference
Winsock Functions
connect
WSAConnect
accept
WSAAccept
AcceptEx
WSAJoinLeaf
OVERLAPPED
GetOverlappedResult
WSAGetOverlappedResult
GetQueuedCompletionStatus
send
TransmitFile
TRANSMIT_PACKETS_ELEMENT

 

 

Community Additions

ADD
Show:
© 2014 Microsoft