LPFN_TRANSMITPACKETS回调函数 (mswsock.h)

TransmitPackets 函数通过连接的套接字传输内存中数据或文件数据。 TransmitPackets 函数使用操作系统缓存管理器来检索文件数据，在传输所需的最短时间内锁定内存，从而实现高效、高性能的传输。

注意 此函数是 Windows 套接字规范的特定于 Microsoft 的扩展。

 

语法

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

BOOL LpfnTransmitpackets(
  SOCKET hSocket,
  LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
  DWORD nElementCount,
  DWORD nSendSize,
  LPOVERLAPPED lpOverlapped,
  DWORD dwFlags
)
{...}

参数

hSocket

要用于传输的连接套接字的句柄。 尽管套接字不需要是面向连接的线路，但默认的目标/对等应已使用 connect、 WSAConnect、 accept、 WSAAccept、 AcceptEx 或 WSAJoinLeaf 函数建立。

lpPacketArray

TRANSMIT_PACKETS_ELEMENT 类型的数组，描述要传输的数据。

nElementCount

lpPacketArray 中的元素数。

nSendSize

发送操作中使用的数据块的大小（以字节为单位）。 将 nSendSize 设置为零，以便套接字层选择默认 的发送 大小。

将 nSendSize 设置为 0xFFFFFFF 使调用方能够控制每个发送请求的大小和内容，通过使用 lpPacketArray 参数中指向的TRANSMIT_PACKETS_ELEMENT数组中的 TP_ELEMENT_EOP 标志来实现。 此功能对于对单个 发送 请求的大小施加限制的消息协议非常有用。

lpOverlapped

指向 OVERLAPPED 结构的指针。 如果 hSocket 参数中指定的套接字句柄已作为重叠打开，请使用此参数实现异步 (重叠) I/O 操作。 默认情况下，套接字句柄作为重叠打开。

dwFlags

一组标志，用于自定义 TransmitPackets 函数的处理。 下表概述了 dwFlags 参数的用法。

值	含义
TF_DISCONNECT	在所有文件数据已排队等待传输后，启动传输级断开连接。 仅适用于面向连接的套接字。 为不支持断开连接语义的套接字指定此标志 (如数据报套接字) 会导致错误。
TF_REUSE_SOCKET	准备要重复使用的套接字句柄。 当 TransmitPackets 函数完成时，套接字句柄可以传递给 AcceptEx 函数。 仅当指定了面向连接的套接字和TF_DISCONNECT时有效。 注意 套接字级数据包传输受基础传输行为的约束。 例如，TCP 套接字可能受 TCP TIME_WAIT状态的约束，从而导致 TransmitPackets 调用延迟。
TF_USE_DEFAULT_WORKER	指示 Winsock 使用系统的默认线程来处理较长的 TransmitPackets 请求。 Long TransmitPackets 请求定义为需要多次从文件或缓存读取的请求;因此，长请求定义取决于文件的大小和发送数据包的指定长度。 可以使用以下注册表参数作为 REG_DWORD：HKEY_LOCAL_MACHINE\CurrentControlSet\Services\AFD\Parameters\TransmitWorker 调整系统默认线程
TF_USE_SYSTEM_THREAD	指示 Winsock 使用系统线程来处理较长 的 TransmitPackets 请求。 Long TransmitPackets 请求定义为需要多次从文件或缓存读取的请求;因此，长请求定义取决于文件的大小和发送数据包的指定长度。
TF_USE_KERNEL_APC	指示 Winsock 使用内核 异步过程调用 (APC) 而不是工作线程来处理较长 的 TransmitPackets 请求。 Long TransmitPackets 请求定义为需要多次从文件或缓存读取的请求;因此，长请求定义取决于文件的大小和发送数据包的指定长度。 有关更多信息，请参见备注。

返回值

如果 TransmitPackets 函数成功，则返回值为 TRUE。 否则，返回值为 FALSE。 若要获取扩展的错误信息，请调用 WSAGetLastError。 WSA_IO_PENDING或ERROR_IO_PENDING错误代码指示重叠的操作已成功启动，将在以后指示完成。 任何其他错误代码指示重叠的操作未成功启动，并且不会发生完成指示。 在这种情况下，应用程序应处理ERROR_IO_PENDING或WSA_IO_PENDING。

返回代码	说明
WSAECONNABORTED	您的主机中的软件中止了已建立的连接。 如果虚拟线路因超时或其他故障而终止，则返回此错误。
WSAECONNRESET	远程主机强行关闭现有连接。 当远程端重置虚拟线路时，为流套接字返回此错误。 因为套接字不可再用，应用程序应关闭套接字。
WSAEFAULT	系统尝试在调用中使用指针参数时检测到指针地址无效。 如果 lpPacketArray 或 lpOverlapped 参数未完全包含在用户地址空间的有效部分，则返回此错误。
WSAEINVAL	提供的参数无效。 如果 dwFlags 参数设置了 TF_REUSE_SOCKET 标志，但未设置 TF_DISCONNECT 标志，则返回此错误。 如果 lpOverlapped 指向的 OVERLAPPED 结构中指定的偏移量不在文件中，也会返回此错误。 如果要传输的字节总数大于 2,147,483,646（32 位整数减 1 的最大值），也会返回此错误。
WSAENETDOWN	套接字操作遇到死网络。如果网络子系统发生故障，则返回此错误。
WSAENETRESET	由于操作执行过程中持续的活动检测到故障，连接损坏。 对于由于检测故障的保持活动活动而中断的流套接字，将返回此错误。
WSAENOBUFS	无法执行某个套接字操作，因为系统缺少足够的缓冲空间或队列已满。 如果 Windows 套接字提供程序报告缓冲区死锁，也会返回此错误。
WSAENOTCONN	不允许发送或接收数据的请求，因为套接字未连接。 流套接字返回此错误。
WSAENOTSOCK	某个操作尝试对非套接字执行操作。 如果 hSocket 参数不是套接字，则返回此错误。
WSAESHUTDOWN	因为该方向的套接字在上一关闭调用中已关闭，发送或接收数据的请求被禁止。 如果已关闭流套接字以便发送，则返回此错误。 在将 how参数设置为 SD_SEND 或 SD_BOTH 的情况下，在套接字上调用关闭函数后，无法在流套接字上调用 TransmitFile。
WSANOTINITIALISED	应用程序未调用 WSAStartup 函数，或者 WSAStartup 失败。 在使用 TransmitFile 函数之前，必须成功调用 WSAStartup。
WSA_IO_PENDING	重叠的 I/O 操作正在进行中。 如果已成功启动重叠的 I/O 操作，并且指示稍后将指示完成，则返回此值。
WSA_OPERATION_ABORTED	由于发生线程退出或应用程序请求，I/O 操作已中止。 如果由于套接字关闭、 WSAIoctl 中的“SIO_FLUSH”命令的执行或启动重叠请求的线程在操作完成之前退出而取消了重叠操作，则返回此错误。 注意 当给定线程退出时，将取消由该线程发起的所有 I/O。 对于重叠套接字，如果在异步操作完成之前关闭线程，挂起的异步操作可能会失败。 有关详细信息，请参阅 ExitThread。

注解

TransmitPackets 函数根据使用它的操作系统进行优化：

• 在 Windows Server 版本上， TransmitPackets 函数针对高性能进行了优化。
• 在 Windows 客户端版本上， TransmitPackets 函数针对最小内存和资源利用率进行了优化。

使用对 TransmitPackets 函数的单个调用可以传输的最大字节数为 2,147,483,646，即 32 位整数减 1 的最大值。 如果应用程序需要传输大于 2,147,483,646 字节的数据，则对 TransmitPackets 函数的多次调用可用于传输不超过 2,147,483,646 个字节的调用。

注意必须在运行时通过调用 WSAIoctl 函数并指定SIO_GET_EXTENSION_FUNCTION_POINTER操作码来获取 TransmitPackets 函数的函数指针。 传递给 WSAIoctl 函数的输入缓冲区必须包含 WSAID_TRANSMITPACKETS，这是一个全局唯一标识符， (GUID) 其值标识 TransmitPackets 扩展函数。 成功后， WSAIoctl 函数返回的输出包含指向 TransmitPackets 函数的指针。 WSAID_TRANSMITPACKETS GUID 在 Mswsock.h 头文件中定义。

 

在 Windows Server 2003 上使用 TransmitPackets 函数时，预期性能会更好。

当 lpOverlapped 不为 NULL 时，重叠 I/O 可能不会在 TransmitPackets 函数返回之前完成。 发生这种情况时， TransmitPackets 函数返回失败，对 WSAGetLastError 函数的调用将返回ERROR_IO_PENDING，从而允许调用方在传输完成时继续处理。

注意 当给定线程退出时，将取消由该线程发起的所有 I/O。 对于重叠的套接字，如果在操作完成之前关闭线程，挂起的异步操作可能会失败。 有关详细信息 ，请参阅 ExitThread 。

 

当 TransmitPackets 函数返回 TRUE 或返回 FALSE 且 WSAGetLastError 返回ERROR_IO_PENDING时，Windows 会将由 OVERLAPPED 结构的 hEvent 成员指定的事件或由 hSocket 指定的套接字设置为信号状态，并在完成后将通知传递到与套接字关联的任何完成端口。 使用 GetOverlappedResult、 WSAGetOverlappedResult 或 GetQueuedCompletionStatus 检索最终状态和传输的字节数。

TransmitPackets 和异步过程调用 (APC)

使用 TF_USE_KERNEL_APC 标志可提供显著的性能优势。 如果发起 TransmitPackets 函数调用的线程用于繁重的计算，则有可能阻止 APC 启动，尽管不太可能。

注意 内核和用户模式 APC 之间存在差异：

• 内核 APC 在线程处于等待状态时启动。
• 当线程处于可警报等待状态时，用户模式 APC 将启动。

 

Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone 应用商店应用支持此函数。

Windows 8.1和Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持此函数。

要求

要求	值
最低受支持的客户端	Windows 8.1、Windows Vista [桌面应用 |UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 | UWP 应用]
目标平台	Windows
标头	mswsock.h

另请参阅

AcceptEx

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED

TRANSMIT_PACKETS_ELEMENT

TransmitFile

WSAAccept

WSAConnect

WSAGetOverlappedResult

WSAJoinLeaf

Winsock 函数

Winsock 参考

accept

connect

send