WSAImpersonateSocketPeer 函式 (ws2tcpip.h)

發行項
03/04/2024

WSAImpersonateSocketPeer 函式可用來模擬對應至套接字對等的安全性主體，以執行應用層級授權。

語法

INT WSAAPI WSAImpersonateSocketPeer(
  [in]           SOCKET         Socket,
  [in, optional] const sockaddr *PeerAddr,
  [in]           ULONG          PeerAddrLen
);

參數

[in] Socket

識別應用程式套接字。

[in, optional] PeerAddr

要模擬之對等的IP位址。針對連線導向套接字，連接的套接字可唯一識別對等。在此情況下，會忽略此參數。

[in] PeerAddrLen

PeerAddress 參數的大小，以位元組為單位。

傳回值

如果函式成功，則傳回值為 0。否則，會傳回 SOCKET_ERROR 的值，而且可以呼叫 WSAGetLastError 來擷取特定的錯誤碼。

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

錯誤碼	意義
WSAEFAULT	系統在嘗試使用呼叫的指標自變數時偵測到無效的位址指標。如果 PeerAddr 參數是 NULL 指標，就會傳回此錯誤。
WSAEAFNOSUPPORT	不支援指定的位址系列。
WSAEMSGSIZE	傳遞的緩衝區太小。
WSAENOTSOCK	在 Socket 參數中傳遞的描述元不是有效的套接字。

備註

WSAImpersonateSocketPeer 函式可讓應用程式模擬對應至套接字對等的安全性主體，以執行應用層級授權。如果對等使用者 (模擬) 令牌可用，則會用於模擬，否則將使用對等計算機令牌。 WSAImpersonateSocketPeer 函式只能針對封鎖、非重疊的套接字呼叫。執行任何授權檢查之後，應用程式必須呼叫 WSARevertImpersonation 函式來終止模擬。

針對連接導向套接字，應在建立連線之後呼叫 WSAImpersonateSocketPeer 函式。對於使用連接導向套接字的伺服器應用程式，應該在 accept、AcceptEx 或 WSAAccept 函式傳回之後呼叫 WSAImpersonateSocketPeer。

針對無連線套接字，應用程式應該在 recv、recvrom、WSARecv、WSARecvEx、WSARecvFrom 或LPFN_WSARECVMSG (WSARecvMsg) 函式傳回新的對等地址之後呼叫 WSAImpersonateSocketPeer 函式。

單一套接字可以多次呼叫 WSAImpersonateSocketPeer 函式。

如果不符合下列條件，將會傳回錯誤。

Socket 參數的位址系列必須是 AF_INET 或 AF_INET6。
套接字類型必須是SOCK_STREAM或SOCK_DGRAM。

必須呼叫 WSARevertImpersonation 函式以結束模擬。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	ws2tcpip.h
程式庫	Fwpuclnt.lib
Dll	Fwpuclnt.dll