WSAQuerySocketSecurity-Funktion (ws2tcpip.h)

Artikel
08/28/2023

Die WSAQuerySocketSecurity-Funktion fragt Informationen zur Sicherheit ab, die auf eine Verbindung in einem Socket angewendet wird.

Syntax

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

Parameter

[in] Socket

Ein Deskriptor, der einen Socket identifiziert, für den Sicherheitsinformationen abgefragt werden.

[in, optional] SecurityQueryTemplate

Ein Zeiger auf eine SOCKET_SECURITY_QUERY_TEMPLATE-Struktur , die den Typ der zurückzugebenden Abfrageinformationen angibt.

Eine SOCKET_SECURITY_QUERY_TEMPLATE Struktur, auf die dieser Parameter verweist, kann Nullen für alle Member enthalten, um Standardsicherheitsinformationen anzufordern. Bei erfolgreicher Rückgabe wird nur das Flags-Element im SOCKET_SECURITY_QUERY_INFO im zurückgegebenen SecurityQueryInfo-Parameter festgelegt.

Dieser Parameter kann ein NULL-Zeiger sein, wenn der Socket-Parameter mit einem Protokoll von IPPROTO_TCP erstellt wurde. In diesem Fall sind die zurückgegebenen Informationen identisch, als ob eine SOCKET_SECURITY_QUERY_TEMPLATE-Struktur mit allen Auf null festgelegten Werten übergeben wurde. Dieser Parameter sollte für einen Socket mit IPPROTO_TCP angegeben werden, wenn mehr als die Standardsicherheitsinformationen erforderlich sind.

Wenn die SOCKET_SECURITY_QUERY_TEMPLATE-Struktur angegeben ist und der PeerTokenAccessMask-Member nicht angegeben ist (auf Null festgelegt), gibt die WSAQuerySocketSecurity-Funktion die Elemente PeerApplicationAccessTokenHandle und PeerMachineAccessTokenHandle in der SOCKET_SECURITY_QUERY_INFO-Struktur nicht zurück.

Wenn ein Socket-Parameter mit einem Protokoll erstellt wurde, das nicht gleich IPPROTO_TCP ist, muss der SecurityQueryTemplate-Parameter angegeben werden. In diesen Fällen muss das PeerAddress-Mitglied der SOCKET_SECURITY_QUERY_TEMPLATE-Struktur eine Adressfamilie von AF_INET oder AF_INET6 zusammen mit peer-IP-Adresse und Portnummer angeben.

[in] SecurityQueryTemplateLen

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

Dieser Parameter kann null sein, wenn der Socket-Parameter mit einem Protokoll von IPPROTO_TCP erstellt wurde. Andernfalls muss dieser Parameter die Größe einer SOCKET_SECURITY_QUERY_TEMPLATE-Struktur aufweisen.

[out, optional] SecurityQueryInfo

Ein Zeiger auf einen Puffer, der eine SOCKET_SECURITY_QUERY_INFO Struktur mit den abgefragten Informationen empfängt. Dieser Wert kann auf NULL festgelegt werden, um die Größe des Ausgabepuffers abzufragen.

[in, out] SecurityQueryInfoLen

Zeigen Sie bei der Eingabe auf die Größe des SecurityQueryInfo-Parameters in Bytes. Wenn der Puffer zu klein ist, um die abgefragten Informationen zu empfangen, gibt der Aufruf SOCKET_ERROR zurück, und die Anzahl der Bytes, die zum Zurückgeben der abgefragten Informationen erforderlich sind, wird in dem Wert festgelegt, auf den dieser Parameter verweist. Bei einem erfolgreichen Aufruf wird die Anzahl der kopierten Bytes zurückgegeben.

[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.
WSAECONNRESET	Bei einem Streamsocket wurde die virtuelle Verbindung von der Remoteseite zurückgesetzt. Die Anwendung sollte den Socket schließen, weil er nicht mehr verwendbar ist. Bei einem UDP-Datagrammsocket würde dieser Fehler darauf hindeuten, dass ein vorheriger Sendevorgang zu einer ICMP-Meldung "Port Unreachable" geführt hat.
WSAEFAULT	Beim Versuch, einen Parameter zu verwenden, hat das System eine ungültige Zeigeradresse erkannt. Dieser Fehler wird zurückgegeben, wenn der SecurityQueryInfoLen-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.
WSAEMSGSIZE	Ein übergebener Puffer war zu klein. Dieser Fehler wird für einen Socketparameter zurückgegeben, wenn das Protokoll nicht IPPROTO_TCP wurde, wenn der SecurityQueryInfo-Parameter ein NULL-Zeiger oder der SecurityQueryTemplateLen-Parameter kleiner als die Größe einer SOCKET_SECURITY_QUERY_TEMPLATE-Struktur ist.
WSAENOTSOCK	Der im Socket-Parameter übergebene Deskriptor ist kein gültiger Socket.

Hinweise

Die WSAQuerySocketSecurity-Funktion stellt eine Methode zum Abfragen der aktuellen Sicherheitseinstellungen für einen Socket bereit. Nachdem eine Verbindung hergestellt wurde, ermöglicht die WSAQuerySocketSecurity-Funktion einer Anwendung, die Sicherheitseigenschaften der Verbindung abzufragen, die Informationen zu Peerzugriffstoken enthalten können.

Bei verbindungsorientierten Sockets wird es bevorzugt, die WSAQuerySocketSecurity-Funktion sofort nach dem Herstellen einer Verbindung aufzurufen. Bei verbindungslosen Sockets wird es bevorzugt, die WSAQuerySocketSecurity-Funktion sofort aufzurufen, nachdem Daten an eine neue Peeradresse gesendet oder von einer neuen Peeradresse empfangen wurden. Die WSAQuerySocketSecurity-Funktion kann an einem einzelnen Socket mehrmals aufgerufen werden.

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

Die WSAQuerySocketSecurity-Funktion kann für einen Socketparameter aufgerufen werden, der mit einer Adressfamilie von AF_INET oder AF_INET6 erstellt wurde.

Wenn der Socket-Parameter mit einem Protokoll von IPPROTO_TCP erstellt wurde, kann der SecurityQueryTemplate-ParameterNULL und der SecurityQueryTemplateLen-Parameter 0 sein. Andernfalls muss der SecurityQueryTemplate-Parameter auf eine SOCKET_SECURITY_QUERY_TEMPLATE-Struktur verweisen.

Für eine Clientanwendung, die verbindungsorientierte Sockets verwendet (Socket, der mit einem Protokoll von IPPROTO_TCP erstellt wurde), sollte die WSAQuerySocketSecurity-Funktion aufgerufen werden, nachdem die Funktion connect, ConnectEx oder WSAConnect zurückgegeben wurde. Für eine Serveranwendung, die verbindungsorientierte Sockets (Protokoll von IPPROTO_TCP) verwendet, sollte die WSAQuerySocketSecurity-Funktion aufgerufen werden, nachdem die Funktion accept, AcceptEx oder WSAAccept zurückgegeben wurde.

Für verbindungslose Sockets (Socket, der mit einem Protokoll von IPPROTO_UDP erstellt wurde) sollte die Anwendung die WSAQuerySocketSecurity-Funktion sofort aufrufen, nachdem WSASendTo oder WSARecvFrom-Aufruf für eine neue Peeradresse zurückgegeben wurde.

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

Anforderung	Wert
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