SIO_IDEAL_SEND_BACKLOG_CHANGE 控制代码

项目
10/13/2023

说明

当连接的理想发送积压工作 (ISB) 值更改时，SIO_IDEAL_SEND_BACKLOG_CHANGE 控制代码会通知应用程序。

若要执行此操作，请使用以下参数调用 WSAIoctl 或 WSPIoctl 函数。

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

参数

s

标识套接字的描述符。

dwIoControlCode

操作的控制代码。为此操作使用 SIO_IDEAL_SEND_BACKLOG_CHANGE。

lpvInBuffer

指向输入缓冲区的指针。未为此操作使用此参数。

cbInBuffer

输入缓冲区的大小（以字节为单位）。未为此操作使用此参数。

lpvOutBuffer

指向输出缓冲区的指针。未为此操作使用此参数。

cbOutBuffer

输出缓冲区的大小（以字节为单位）。该参数必须设置为零。

lpcbBytesReturned

指向变量的指针，该变量接收存储在输出缓冲区中的数据的大小（以字节为单位）。此返回的参数指向值为零的此操作的 DWORD，因为无输出。

lpvOverlapped

指向 WSAOVERLAPPED 结构的指针。

如果创建了没有重叠属性的套接字 s，会忽略 lpOverlapped 参数。

如果打开了带有重叠属性的 s，且 lpOverlapped 参数不为 NULL，则将按重叠（异步）操作来执行该操作。在这种情况下，lpOverlapped 参数必须指向有效的 WSAOVERLAPPED 结构。

对于重叠的操作，WSAIoctl 或 WSPIoctl 函数会立即返回，并在操作完成后指示相应的完成方法。否则，在操作完成或发生错误之前，函数不会返回。

lpCompletionRoutine

类型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

指向操作完成时调用的完成例程的指针（非重叠套接字则忽略）。

lpThreadId

指向提供程序在后续调用 WPUQueueApc 时要使用的 WSATHREADID 结构的指针。提供程序应存储引用的 WSATHREADID 结构（而不是指向其的指针），且直到 WPUQueueApc 函数返回。

注释：此参数仅适用于 WSPIoctl 函数。

lpErrno

指向错误代码的指针。

注释：此参数仅适用于 WSPIoctl 函数。

返回值

如果操作成功完成，则 WSAIoctl 或 WSPIoctl 函数会返回零。

如果操作失败或挂起，则 WSAIoctl 或 WSPIoctl 函数会返回 SOCKET_ERROR。要获得更多的错误信息，请调用 WSAGetLastError。

错误代码	含义
WSA_IO_PENDING	成功发起了一个重叠操作，稍后会指示完成操作。
WSA_OPERATION_ABORTED	因套接字关闭或执行了 SIO_FLUSH IOCTL 命令，而取消了一个重叠操作。
WSAEFAULT	lpOverlapped 或 lpCompletionRoutine 参数未完全包含在用户地址空间的有效部分中。
WSAEINPROGRESS	该函数在进行某个回调时被调用。
WSAEINTR	中断了某个阻塞操作。
WSAEINVAL	dwIoControlCode 参数不是有效命令，或指定的输入参数不可接受，或命令不适用于指定类型的套接字。如果 cbOutBuffer 参数不为零，则返回此错误。
WSAENETDOWN	网络子系统故障。
WSAENOPROTOOPT	指定的协议不支持套接字选项。
WSAENOTCONN	未连接套接字 s。
WSAENOTSOCK	描述符 s 不是套接字。
WSAEOPNOTSUPP	不支持指定的 IOCTL 命令。如果传输提供程序不支持 SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL，则返回此错误。如果尝试在数据报套接字上使用 SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL，也会返回此错误。

备注

Windows Server 2008、带 Service Pack 1 (SP1) 的 Windows Vista 及更高版本的操作系统支持 SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL。

使用 Windows 套接字通过 TCP 连接发送数据时，请务必在 TCP 中保留足够多的未完成的数据（已发送但尚未确认的数据），以实现最高的吞吐量。使 TCP 连接达到最佳吞吐量的未完成数据量的理想值称为理想的发送积压工作 (ISB) 大小。 ISB 值是 TCP 连接的带宽延迟积和接收方的播发接收时段（以及一定比例的网络拥塞量）的函数。

每个连接的 ISB 值可通过 Windows Server 2008、Windows Vista SP1 和更高版本的操作系统中的 TCP 协议实现来获取。当连接的 ISB 值动态更改时，应用程序可使用 SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 来获取通知。

在 Windows Server 2008、带 SP1 的 Windows Vista 和更高版本的操作系统上，处于连接状态的流套接字上支持 SIO_IDEAL_SEND_BACKLOG_CHANGE 和 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL。

TCP 连接的 ISB 值的范围理论上可介于 0 到最高 16 兆字节之间。

有关通过高带宽延迟积连接来实现更好吞吐量的 ISB 机制的典型用法，请参阅 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 参考页。

仅允许在处于连接状态的流套接字上使用 SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL。否则使用 WSAENOTCONN 时，WSAIoctl 或 WSPIoctl 函数会失败。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 不使用输入或输出缓冲区，会一直挂起或阻塞直到基础连接发生 ISB 更改。此 IOCTL 后完成，Winsock 应用程序可以使用 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 检索连接上的新 ISB 值。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 不支持无阻塞模式。应用程序可以在无阻塞套接字上发出此 IOCTL，但 IOCTL 会一直阻塞或挂起直到 ISB 值更改。

如果 lpOverlapped 和 lpCompletionRoutine 参数均为 NULL，则此函数中的套接字会视为非重叠套接字。对于非重叠套接字，会忽略 lpOverlapped 和 lpCompletionRoutine 参数，但如果套接字 s 处于阻塞模式，函数可能阻塞。如果套接字 s 处于无阻塞模式，此函数仍会阻塞，因为此特定 IOCTL 不支持无阻塞模式。

对于重叠套接字，无法立即完成的操作会先启动，系统会在稍后提供其完成指示。

任何 IOCTL 都可能会无限期阻塞，具体取决于服务提供程序的实现。如果应用程序无法容忍 WSAIoctl 或 WSPIoctl 函数调用中发生阻塞，则建议为很可能阻塞的 IOCTL 使用重叠 I/O。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 提供通知，并预期会一直阻塞或挂起直到 ISB 值更改。因此它通常在 lpOverlapped 参数设置为有效的 WSAOVERLAPPED 结构的情况下以异步方式调用。

在以下情况下，在使用 WSAEINTR 或 WSA_OPERATION_ABORTED 时，SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 可能会失败：

TCP 连接会在发送方向上正常断开连接。在调用 how 参数设置为 SD_SEND 的 shutdown 函数时、调用 DisconnectEx 函数时或调用 dwFlags 参数设置为 TF_DISCONNECT 或 TF_REUSE 的 TransmitFile 或 TransmitPackets 函数时可能会发生这种情况。
TCP 连接已重置或中止。
应用程序会在已存在挂起的通知请求时发出 SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL。一次只允许挂起一个 SIO_IDEAL_SEND_BACKLOG_CHANGE 请求。
I/O 管理器取消了该请求。
套接字已关闭。

Ws2tcpip.h 头文件中定义了这些 IOCTL 的两个内联包装函数。建议使用这些内联函数，而不是直接使用 SIO_IDEAL_SEND_BACKLOG_CHANGE 和 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 的内联包装函数是 idealsendbacklognotify 函数。

SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 的内联包装函数是 idealsendbacklogquery 函数。