SIO_KEEPALIVE_VALS控制代码

项目
06/13/2023

说明

SIO_KEEPALIVE_VALS控制代码启用或禁用 TCP 保持连接选项的每个连接设置，该选项指定 TCP 保持连接超时和间隔。

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

int WSAIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  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_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  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_KEEPALIVE_VALS 。

lpvInBuffer

指向输入缓冲区的指针。此参数应指向 tcp_keepalive 结构。

cbInBuffer

输入缓冲区的大小（以字节为单位）。此参数应等于或大于 lpvInBuffer 参数指向的 tcp_keepalive 结构的大小。

lpvOutBuffer

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

cbOutBuffer

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

lhttpBytesReturned

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

lpvOverlapped

指向 WSAOVERLAPPED 结构的指针。

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

如果使用重叠属性打开了，并且 lpOverlapped 参数不为 NULL，则该操作将作为重叠 (异步) 操作执行。在这种情况下， lpOverlapped 参数必须指向有效的 WSAOVERLAPPED 结构。

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

lpCompletionRoutine

类型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

指向完成操作时调用的完成例程的指针， (忽略非重叠套接字) 。

lpThreadId

指向 WSATHREADID 结构的指针，供提供程序在后续调用 WPUQueueApc 时使用。在 WPUQueueApc 函数返回之前，提供程序应存储引用的 WSATHREADID 结构 (而不是指向同一) 的指针。

注意此参数仅适用于 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 参数不是有效的命令，或者指定的输入参数不可接受，或者该命令不适用于指定的套接字类型。
WSAENETDOWN	网络子系统失败。
WSAENOPROTOOPT	指定协议不支持套接字选项。对数据报套接字返回此错误。
WSAENOTSOCK	描述符不是套接字。
WSAEOPNOTSUPP	不支持指定的 IOCTL 命令。如果传输提供程序不支持 SIO_KEEPALIVE_VALS IOCTL，则返回此错误。

备注

SIO_KEEPALIVE_VALS IOCTL 在 Windows 2000 及更高版本的操作系统上受支持。

SIO_KEEPALIVE_VALS控制代码启用或禁用 TCP 保持连接选项的每个连接设置，该选项指定用于 TCP 保持连接数据包的 TCP 保持连接超时和间隔。有关“保持连接”选项的详细信息，请参阅 IETF 网站上提供的有关 Internet 主机的要求 - RFC 1122 中指定的通信层的第 4.2.3.6 部分。 (此资源可能仅提供英语。)

lpvInBuffer 参数应指向 Mstcpip.h 头文件中定义的tcp_keepalive结构。此结构定义如下：

/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
    u_long  onoff;
    u_long  keepalivetime;
    u_long  keepaliveinterval;
};

onoff 成员中指定的值确定是启用还是禁用 TCP 保持连接。如果 onoff 成员设置为非零值，则启用 TCP 保持连接并使用结构中的其他成员。 keepalivetime 成员指定超时（以毫秒为单位），在发送第一个 keep-alive 数据包之前没有活动。 keepaliveinterval 成员指定在未收到确认的情况下发送连续保持连接数据包之间的间隔（以毫秒为单位）。

SO_KEEPALIVE选项（SOL_SOCKET套接字选项之一）还可用于启用或禁用连接上的 TCP 保持连接状态，以及查询此选项的当前状态。若要查询是否在套接字上启用了 TCP 保持连接，可以使用 SO_KEEPALIVE 选项调用 getsockopt 函数。若要启用或禁用 TCP 保持连接，可以使用 SO_KEEPALIVE 选项调用 setsockopt 函数。如果使用 SO_KEEPALIVE 启用 TCP 保持连接，则默认 TCP 设置用于保持连接超时和间隔，除非已使用 SIO_KEEPALIVE_VALS 更改这些值。

keep-alive 超时的默认系统范围值可通过 KeepAliveTime 注册表设置进行控制，该设置采用以毫秒为单位的值。如果未设置密钥，则默认保持连接超时为 2 小时。 keep-alive 间隔的默认系统范围值可通过 KeepAliveInterval 注册表设置进行控制，该设置采用以毫秒为单位的值。如果未设置密钥，则默认保持连接间隔为 1 秒。

在 Windows Vista 及更高版本上， (数据重新传输) 保持连接探测数设置为 10，无法更改。

在 Windows Server 2003、Windows XP 和 Windows 2000 上，保持连接探测数的默认设置为 5。保持连接探测的数量可通过 TcpMaxDataRetransmissions 和 PPTPTcpMaxDataRetransmissions 注册表设置进行控制。保持连接探测数设置为两个注册表项值中的较大值。如果此数字为 0，则不会发送保持连接探测。如果此数字高于 255，则将其调整为 255。