WSASetSocketPeerTargetName-Funktion (ws2tcpip.h)

Artikel
08/28/2023

Die WSASetSocketPeerTargetName-Funktion wird verwendet, um den Peerzielnamen (SPN) anzugeben, der einer Peer-IP-Adresse entspricht. Dieser Zielname soll von Clientanwendungen angegeben werden, um den Peer zu identifizieren, der authentifiziert werden soll.

Syntax

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
);

Parameter

[in] Socket

Ein Deskriptor, der einen Socket identifiziert, dem der Peerzielname zugewiesen wird.

[in] PeerTargetName

Ein Zeiger auf eine SOCKET_PEER_TARGET_NAME-Struktur , die den Peerzielnamen definiert.

[in] PeerTargetNameLen

Die Größe des PeerTargetName-Parameters in Bytes.

[in, optional] Overlapped

Ein Zeiger auf eine WSAOVERLAPPED-Struktur . Dieser Parameter wird für nicht überlappende Sockets ignoriert.

[in, optional] CompletionRoutine

Ein Zeiger auf die Vervollständigungsroutine, die aufgerufen wird, wenn der Vorgang abgeschlossen wurde. Dieser Parameter wird für nicht überlappende Sockets ignoriert.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert „0“. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Einige mögliche Fehlercodes sind unten aufgeführt.

Fehlercode	Bedeutung
WSAEAFNOSUPPORT	Die angegebene Adressfamilie wird nicht unterstützt.
WSAEFAULT	Das System hat beim Versuch, ein Zeigerargument eines Aufrufs zu verwenden, einen ungültigen Adresszeiger erkannt. Dieser Fehler wird zurückgegeben, wenn der PeerTargetName-Parameter ein NULL-Zeiger war.
WSAEINVAL	Es wurde ein ungültiger Parameter übergeben. Dieser Fehler wird zurückgegeben, wenn der im Socket-Parameter übergebene Socket nicht mit einer Adressfamilie des AF_INET oder AF_INET6 und einem Sockettyp von SOCK_DGRAM oder SOCK_STREAM erstellt wurde. Dieser Fehler wird auch für einen verbindungslosen Socket zurückgegeben, wenn die IP-Adresse und der Port im PeerAddress-Element der SOCKET_PEER_TARGET_NAME Struktur, auf die der PeerTargetName-Parameter verweist, null sind.
WSAEISCONN	Der Socket ist verbunden. Diese Funktion ist bei einem verbundenen Socket nicht zulässig, unabhängig davon, ob der Socket verbindungsorientiert oder verbindungslos ist.
WSAEMSGSIZE	Ein übergebener Puffer war zu klein.
WSAENOTSOCK	Der im Socket-Parameter übergebene Deskriptor ist kein gültiger Socket.

Hinweise

Die WSASetSocketPeerTargetName-Funktion stellt eine Methode zum Angeben des Zielnamens bereit, der einem Peersicherheitsprinzipal entspricht. Diese Funktion soll von einer Clientanwendung verwendet werden, um den Peer zu identifizieren, der authentifiziert werden soll. Eine Clientanwendung sollte den Peerzielnamen angeben, um vertrauenswürdige Man-in-the-Middle-Angriffe zu verhindern. Für verbindungslose Sockets kann eine Anwendung die WSASetSocketPeerTargetName-Funktion mehrmals aufrufen, um unterschiedliche Zielnamen für verschiedene Peer-IP-Adressen anzugeben.

Diese Funktion vereinfacht das Aufrufen der WSAIoctl-Funktion mit einem dwIoControlCode-Parameter , der auf SIO_SET_PEER_TARGET_NAME festgelegt ist.

Für verbindungsorientierte Sockets sollte die WSASetSocketPeerTargetName-Funktion vor WSAConnect aufgerufen werden. Bei verbindungslosen Sockets sollte diese Funktion vor WSAConnect oder vor dem ersten an die Peeradresse gerichteten WSASendTo-Aufruf aufgerufen werden.

Wenn die folgenden Bedingungen nicht erfüllt sind, wird ein Fehler zurückgegeben.

Die Adressfamilie des Socket-Parameters muss entweder AF_INET oder AF_INET6 sein.
Der Sockettyp muss entweder SOCK_STREAM oder SOCK_DGRAM sein.

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ws2tcpip.h
Bibliothek	Fwpuclnt.lib
DLL	Fwpuclnt.dll