WSAQuerySocketSecurity 函式 (ws2tcpip.h)
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來擷取特定的錯誤碼。
以下列出一些可能的錯誤碼。
| 錯誤碼 | 意義 |
|---|---|
| 不支援指定的位址系列。 | |
| 針對資料流程通訊端，虛擬線路已由遠端重設。 此通訊端無法再使用，應用程式應予以關閉。 針對 UDP 資料包通訊端，此錯誤會指出先前的傳送作業導致 ICMP「無法連線的埠」訊息。 | |
| 系統在嘗試使用 參數時偵測到不正確指標位址。 如果 SecurityQueryInfoLen 參數是 Null 指標，就會傳回此錯誤。 | |
| 傳遞了一個無效的參數。 如果未使用AF_INET或AF_INET6的位址系列建立通訊端，且通訊端類型為SOCK_DGRAM或SOCK_STREAM，則會傳回此錯誤。 | |
| 傳遞的緩衝區太小。 如果SecurityQueryInfo參數是Null指標，或SecurityQueryTemplateLen參數小於SOCKET_SECURITY_QUERY_TEMPLATE結構的大小，則當通訊協定未IPPROTO_TCP時，Socket 參數就會傳回此錯誤。 | |
| 在 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 |