WSAQuerySocketSecurity 函数 (ws2tcpip.h)

项目
03/13/2024

WSAQuerySocketSecurity 函数查询有关应用于套接字上的连接的安全性的信息。

语法

INT WSAAPI WSAQuerySocketSecurity(
  [in]            SOCKET                               Socket,
  [in, optional]  const SOCKET_SECURITY_QUERY_TEMPLATE *SecurityQueryTemplate,
  [in]            ULONG                                SecurityQueryTemplateLen,
  [out, optional] SOCKET_SECURITY_QUERY_INFO           *SecurityQueryInfo,
  [in, out]       ULONG                                *SecurityQueryInfoLen,
  [in, optional]  LPWSAOVERLAPPED                      Overlapped,
  [in, optional]  LPWSAOVERLAPPED_COMPLETION_ROUTINE   CompletionRoutine
);

参数

[in] Socket

标识正在查询其安全信息的套接字的描述符。

[in, optional] SecurityQueryTemplate

指向 SOCKET_SECURITY_QUERY_TEMPLATE 结构的指针，该结构指定要返回的查询信息的类型。

此参数指向的SOCKET_SECURITY_QUERY_TEMPLATE 结构可能包含请求默认安全信息的所有成员的零。成功返回后，只会在返回的 SecurityQueryInfo 参数中设置SOCKET_SECURITY_QUERY_INFO中的 Flags 成员。

如果 Socket 参数是使用 IPPROTO_TCP 协议创建的，则此参数可能是 NULL 指针。在这种情况下，返回的信息与传递所有值设置为零的SOCKET_SECURITY_QUERY_TEMPLATE 结构相同。如果需要超过默认安全信息，则应为协议为 IPPROTO_TCP 的套接字指定此参数。

如果指定SOCKET_SECURITY_QUERY_TEMPLATE结构时未指定 PeerTokenAccessMask 成员 (设置为零) ，则 WSAQuerySocketSecurity 函数将不会返回SOCKET_SECURITY_QUERY_INFO结构中的 PeerApplicationAccessTokenHandle 和 PeerMachineAccessTokenHandle 成员。

如果使用不等于 IPPROTO_TCP 的协议创建了 Socket 参数，则必须指定 SecurityQueryTemplate 参数。在这些情况下，SOCKET_SECURITY_QUERY_TEMPLATE结构的 PeerAddress 成员必须指定AF_INET或AF_INET6的地址系列以及对等 IP 地址和端口号。

[in] SecurityQueryTemplateLen

SecurityQueryTemplate 参数的大小（以字节为单位）。

如果 Socket 参数是使用 IPPROTO_TCP 协议创建的，则此参数可能为零。否则，此参数必须是 SOCKET_SECURITY_QUERY_TEMPLATE 结构的大小。

[out, optional] SecurityQueryInfo

指向缓冲区的指针，该缓冲区将接收包含所查询信息的 SOCKET_SECURITY_QUERY_INFO 结构。此值可以设置为 NULL 以查询输出缓冲区的大小。

[in, out] SecurityQueryInfoLen

输入时，指针指向 SecurityQueryInfo 参数的大小（以字节为单位）。如果缓冲区太小而无法接收查询的信息，则调用将返回SOCKET_ERROR，并且返回查询信息所需的字节数将在此参数指向的值中设置。成功调用后，将返回复制的字节数。

[in, optional] Overlapped

指向 WSAOVERLAPPED 结构的指针。对于非重叠套接字，将忽略此参数。

[in, optional] CompletionRoutine

指向完成操作时调用的完成例程的指针。对于非重叠套接字，将忽略此参数。

返回值

如果函数成功，则返回值为 0。否则，将返回 值 SOCKET_ERROR ，并且可以通过调用 WSAGetLastError 来检索特定的错误代码。

下面列出了一些可能的错误代码。

错误代码	含义
WSAEAFNOSUPPORT	：不支持指定的地址系列。
WSAECONNRESET	对于流套接字，虚拟线路由远程端重置。因为套接字不可再用，应用程序应关闭套接字。对于 UDP 数据报套接字，此错误将指示以前的发送操作导致 ICMP“端口无法访问”消息。
WSAEFAULT	系统在尝试使用参数时检测到指针地址无效。如果 SecurityQueryInfoLen 参数为 NULL 指针，则返回此错误。
WSAEINVAL	传递的参数无效。如果未使用 AF_INET 或 AF_INET6 的地址系列以及套接字类型为 SOCK_DGRAM 或 SOCK_STREAM 创建在 Socket 参数中传递的套接字，则返回此错误。
WSAEMSGSIZE	传递的缓冲区太小。如果 SecurityQueryInfo 参数为 NULL 指针或 SecurityQueryTemplateLen 参数小于SOCKET_SECURITY_QUERY_TEMPLATE结构的大小，则未IPPROTO_TCP协议时，将针对 Socket 参数返回此错误。
WSAENOTSOCK	在 Socket 参数中传递的描述符不是有效的套接字。

注解

WSAQuerySocketSecurity 函数提供了一种在套接字上查询当前安全设置的方法。建立连接后， WSAQuerySocketSecurity 函数允许应用程序查询连接的安全属性，其中可以包含有关对等访问令牌的信息。

对于面向连接的套接字，最好在建立连接后立即调用 WSAQuerySocketSecurity 函数。对于无连接套接字，首选在将数据发送到新的对等地址或从新对等地址接收数据后立即调用 WSAQuerySocketSecurity 函数。可以在单个套接字上多次调用 WSAQuerySocketSecurity 函数。

此函数简化了调用 WSAIoctl 函数（将 dwIoControlCode 参数设置为 SIO_QUERY_SECURITY）的操作。

WSAQuerySocketSecurity 函数可以在使用 AF_INET 或 AF_INET6 的地址系列创建的 Socket 参数上调用。

如果 Socket 参数是使用 IPPROTO_TCP 协议创建的，则 SecurityQueryTemplate 参数可以为 NULL，SecurityQueryTemplateLen 参数可以为零。否则， SecurityQueryTemplate 参数必须指向 SOCKET_SECURITY_QUERY_TEMPLATE 结构。

对于使用面向连接的套接字 (使用 IPPROTO_TCP) 协议创建的套接字的客户端应用程序，应在 connect、ConnectEx 或 WSAConnect 函数返回后调用 WSAQuerySocketSecurity 函数。对于使用面向连接的套接字 (IPPROTO_TCP) 协议的服务器应用程序，应在 accept、AcceptEx 或 WSAAccept 函数返回后调用 WSAQuerySocketSecurity 函数。

对于使用 IPPROTO_UDP) 协议创建的无连接套接字 (套接字，应用程序应在 WSASendTo 或 WSARecvFrom 调用返回新对等地址后立即调用 WSAQuerySocketSecurity 函数。

如果不满足以下条件，将返回错误。

Socket 参数的地址系列必须是AF_INET或AF_INET6。
套接字类型必须是SOCK_STREAM或SOCK_DGRAM。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	ws2tcpip.h
Library	Fwpuclnt.lib
DLL	Fwpuclnt.dll