WSASetSocketPeerTargetName 函式 (ws2tcpip.h)

發行項
08/28/2023

WSASetSocketPeerTargetName函式可用來指定對應至對等 IP 位址的對等目標名稱 (SPN) 。此目標名稱是要由用戶端應用程式指定，以安全地識別應該驗證的對等。

語法

INT WSAAPI WSASetSocketPeerTargetName(
  [in]           SOCKET                             Socket,
  [in]           const SOCKET_PEER_TARGET_NAME      *PeerTargetName,
  [in]           ULONG                              PeerTargetNameLen,
  [in, optional] LPWSAOVERLAPPED                    Overlapped,
  [in, optional] LPWSAOVERLAPPED_COMPLETION_ROUTINE CompletionRoutine
);

參數

[in] Socket

描述項，識別要指派對等目標名稱的通訊端。

[in] PeerTargetName

定義對等目標名稱之SOCKET_PEER_TARGET_NAME 結構的指標。

[in] PeerTargetNameLen

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

[in, optional] Overlapped

WSAOVERLAPPED結構的指標。非重迭通訊端會忽略此參數。

[in, optional] CompletionRoutine

完成常式的指標，在作業完成時呼叫。非重迭通訊端會忽略此參數。

傳回值

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

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

錯誤碼	意義
WSAEAFNOSUPPORT	不支援指定的位址系列。
WSAEFAULT	系統在嘗試使用呼叫的指標引數時偵測到不正確位址指標。如果 PeerTargetName 參數是 Null 指標，就會傳回此錯誤。
WSAEINVAL	傳遞了一個無效的參數。如果未使用AF_INET或AF_INET6的位址系列和SOCK_DGRAM或SOCK_STREAM的通訊端類型建立通訊端傳入 Socket參數，就會傳回此錯誤。如果 IP 位址和埠在PeerTargetName參數所指向之 SOCKET_PEER_TARGET_NAME結構中的PeerAddress成員中，也會針對無連線通訊端傳回此錯誤。
WSAEISCONN	通訊端已連線。不論通訊端是連線導向還是無連接，都不允許此函式與連線通訊端。
WSAEMSGSIZE	傳遞的緩衝區太小。
WSAENOTSOCK	在 Socket參數中傳遞的描述元不是有效的通訊端。

備註

WSASetSocketPeerTargetName函式提供方法來指定對應至對等安全性主體的目標名稱。此函式是用戶端應用程式用來識別應該驗證的對等。用戶端應用程式應該指定對等目標名稱，以防止受信任的中間人攻擊。針對無連線通訊端，應用程式可以多次呼叫 WSASetSocketPeerTargetName 函式，以針對不同的對等 IP 位址指定不同的目標名稱。

此函式可簡化呼叫 WSAIoctl 函式，並將 dwIoControlCode 參數設定為 SIO_SET_PEER_TARGET_NAME。

針對連接導向通訊端，應該在WSAConnect之前呼叫WSASetSocketPeerTargetName函式。針對無連線通訊端，應該在 WSAConnect 或第一個 WSASendTo 呼叫導向對等位址之前呼叫此函式。

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

Socket參數的位址系列必須是 AF_INET 或 AF_INET6。
通訊端類型必須是SOCK_STREAM或SOCK_DGRAM。

規格需求


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