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

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

返回值

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

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

错误代码	含义
WSAEAFNOSUPPORT	：不支持指定的地址系列。
WSAEFAULT	在尝试使用调用的指针参数时，系统检测到地址指针无效。如果 PeerTargetName 参数为 NULL 指针，则返回此错误。
WSAEINVAL	传递的参数无效。如果未使用 AF_INET 或 AF_INET6 的地址系列以及套接字类型为 SOCK_DGRAM 或 SOCK_STREAM 创建在 Socket 参数中传递的套接字，则返回此错误。如果 PEERTargetName 参数指向的 SOCKET_PEER_TARGET_NAME 结构的 PeerAddress 成员中的 IP 地址和端口为零，则无连接套接字也会返回此错误。
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
Library	Fwpuclnt.lib
DLL	Fwpuclnt.dll