SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS控制代码

项目
06/13/2023

说明

SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS控制代码检索接受的 TCP/IP 连接的重定向记录，供 Windows 筛选平台 (WFP) 重定向服务使用。

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

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

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

参数

S

标识套接字的描述符。

dwIoControlCode

操作的控制代码。对此操作使用 SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS 。

lpvInBuffer

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

cbInBuffer

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

lpvOutBuffer

指向输出缓冲区的指针。如果 lpOverlapped 和 lpCompletionRoutine 参数为 NULL，则此参数应指向 ULONG 数据类型。

cbOutBuffer

输出缓冲区的大小（以字节为单位）。此参数必须至少为 ULONG 数据类型的大小。

lhttpBytesReturned

指向变量的指针，该变量接收输出缓冲区中存储的数据的大小（以字节为单位）。

如果输出缓冲区太小，调用会失败， WSAGetLastError 将返回 WSAEINVAL，并且 lhttpBytesReturned 参数指向 DWORD 值零。

如果 lpOverlapped 为 NULL，则成功调用时返回的lBytesReturned 参数指向的 DWORD 值不能为零。

如果重叠套接字的 lpOverlapped 参数不为 NULL ，则将启动无法立即完成的操作，并在以后指示完成。返回的lBytesReturned 参数指向的 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。

错误代码	含义
ERROR_INSUFFICIENT_BUFFER	传递给系统调用的数据区域太小。如果 lpvOutBuffer 参数指向的缓冲区大小在 cbOutBuffer 参数中传递的缓冲区太小，则返回此错误。所需的缓冲区大小将返回在lBytesReturned 参数中。
WSA_IO_PENDING	已成功启动重叠操作，稍后将指示完成。
WSA_OPERATION_ABORTED	由于套接字关闭或执行了 SIO_FLUSH IOCTL 命令，已取消重叠的操作。
WSAEFAULT	lpvOutBuffer、l的身份tesReturned、lpOverlapped 或 lpCompletionRoutine 参数并不完全包含在用户地址空间的有效部分。
WSAEINPROGRESS	当回调正在进行时，将调用函数。
WSAEINTR	阻止操作中断。
WSAEINVAL	dwIoControlCode 参数不是有效的命令，或者指定的输入参数不可接受，或者该命令不适用于指定的套接字类型。如果 cbOutBuffer 参数小于 ULONG 数据类型的大小，则返回此错误。
WSAENETDOWN	网络子系统失败。
WSAENOPROTOOPT	指定协议不支持套接字选项。
WSAENOTCONN	套接字未连接。
WSAENOTSOCK	描述符不是套接字。
WSAEOPNOTSUPP	不支持指定的 IOCTL 命令。如果传输提供程序不支持 SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL，则返回此错误。

备注

Windows 8、Windows Server 2012及更高版本的操作系统支持SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL。

WFP 允许访问 TCP/IP 数据包处理路径，其中可以检查或更改传出和传入数据包，然后再允许进一步处理它们。通过利用 TCP/IP 处理路径， (ISV) 的独立软件供应商可以更轻松地创建防火墙、防病毒软件、诊断软件以及其他类型的应用程序和服务。 WFP 提供用户模式和内核模式组件，以便第三方 ISV 可以参与在 TCP/IP 协议堆栈中的多个层以及整个操作系统中发生的筛选决策。 WFP 连接重定向功能允许 WFP 标注内核驱动程序在本地将连接重定向到用户模式进程，在用户模式下执行内容检查，并使用其他连接将检查的内容转发到原始目标。

SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 和其他几个相关的 IOCTLS 是用户模式组件，用于允许多个基于 WFP 的连接代理应用程序以协作方式检查相同的流量流。每个检查代理可以安全地重新检查已由另一个检查代理检查的网络流量。如果存在多个代理 (由不同的 ISV 开发，例如) 一个代理用来与最终目标通信的连接反过来可由第二个代理重定向，并且原始代理可以再次重定向新连接。如果没有连接跟踪，原始连接可能永远不会到达其最终目标，因为它卡在无限代理循环中。

SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 用于在重定向的套接字连接上提供代理连接跟踪。此 WFP 功能有助于跟踪从连接的初始重定向到目标的最终连接的重定向记录。

基于 WFP 的重定向服务使用 SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 从接受的 TCP/IP 数据包连接检索重定向记录， (TCP 套接字或 UDP 套接字的连接套接字，例如，) 由在内核模式驱动程序 ALE_CONNECT_REDIRECT层中 注册的配套内核模式标注重定向到它。基于 WFP 的重定向服务使用 SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL 从接受的 TCP/IP 数据包连接检索重定向记录的重定向上下文， (TCP 套接字或 UDP 套接字的连接套接字，例如，) 通过 ALE_CONNECT_REDIRECT层注册 的配套标注重定向到它。如果连接的当前重定向状态是连接已由调用重定向服务重定向，或者连接以前由调用重定向服务重定向，但后来又由其他重定向服务重定向，则重定向上下文是可选的驱动程序分配上下文。对于 TCP 代理连接，重定向服务会将检索到的重定向记录传输到它使用 SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 代理原始内容的 TCP 套接字。

当重定向服务重定向非 TCP 套接字 (UDP（例如) ）时，SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL 返回的重定向记录会使用与 LPFN_WSARECVMSG (WSARecvMsg) 函数一起使用的 WSAMSG 结构向重定向服务指示这一点。 WSAMSG 结构的 Control 成员将在 WSACMSGHDR 结构中将cmsg_type设置为 IP_CONNECTION_REDIRECT_RECORD。接受非 TCP 重定向时，重定向服务必须提供 LPFN_WSARECVMSG (WSARecvMsg) 参数。

对于非 TCP 流量，重定向记录使用 WSASendMsg 函数的 WSAMSG 结构转发。

请注意，对于非 TCP 流量，只有流创建数据包将携带 IP_CONNECTION_REDIRECT_RECORD。因此，只有第一个代理数据包需要使用 LPFN_WSARECVMSG (WSARecvMsg) 函数包含此信息。

由于 WFP 重定向记录是可变长度的数据 Blob，因此调用方可以 (lpvOutBuffer 参数指向的 1，024 字节缓冲区（例如) ）提供较大的输出缓冲区，也可以传递 cbOutBuffer 参数 0 中的输出缓冲区大小，以查询保存返回的 blob 所需的缓冲区大小。如果输出缓冲区大小不足以保存数据， 则 WSAIoctl 或 WSPIoctl 函数将返回 ERROR_INSUFFICIENT_BUFFER ，并且所需的缓冲区大小将以 l ERROR_INSUFFICIENT_BUFFER BytesReturned 参数指向的值返回。

调用 SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT 的应用程序不需要了解包含检索到的重定向上下文的 Blob。这是应用程序需要检索并传回新套接字的不透明数据 Blob。