WSAQuerySocketSecurity 函式 (ws2tcpip.h)

發行項
03/09/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 通訊協定的套接字指定此參數。

如果使用未指定 peerTokenAccessMask 成員指定SOCKET_SECURITY_QUERY_TEMPLATE結構， (設定為零) ，則 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

作業完成時呼叫之完成例程的指標。非重迭套接字會忽略此參數。

傳回值

如果此函式成功，則傳回值為零。否則，會傳回 SOCKET_ERROR 的值，並呼叫 WSAGetLastError 來擷取特定的錯誤碼。

以下列出一些可能的錯誤碼。

錯誤碼	意義
WSAEAFNOSUPPORT	不支援指定的位址系列。
WSAECONNRESET	針對數據流套接字，虛擬線路已由遠端重設。此通訊端無法再使用，應用程式應予以關閉。針對 UDP 數據報套接字，此錯誤會指出先前的傳送作業導致 ICMP「無法連線的埠」訊息。
WSAEFAULT	系統在嘗試使用參數時偵測到無效的指標位址。如果 SecurityQueryInfoLen 參數是 NULL 指標，就會傳回此錯誤。
WSAEINVAL	傳遞了一個無效的參數。如果未使用 AF_INET 或 AF_INET6 的位址系列建立套接字，且套接字類型為 SOCK_DGRAM 或 SOCK_STREAM，則會傳回此錯誤。
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
程式庫	Fwpuclnt.lib
Dll	Fwpuclnt.dll