PFN_WSK_SOCKET Rückruffunktion (wsk.h)

Artikel
08/08/2023

Die WskSocket-Funktion erstellt einen neuen Socket und gibt einen Zeiger auf das zugeordnete Socketobjekt zurück.

Syntax

PFN_WSK_SOCKET PfnWskSocket;

NTSTATUS PfnWskSocket(
  [in]           PWSK_CLIENT Client,
  [in]           ADDRESS_FAMILY AddressFamily,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const VOID *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

Parameter

[in] Client

Ein Zeiger auf eine WSK_CLIENT-Struktur , die über den WskProviderNpi-Parameter des -Parameters zurückgegeben wurde WskCaptureProviderNPI-Funktion .

[in] AddressFamily

Die Adressfamilie für den Socket, der erstellt wird. Weitere Informationen zu unterstützten Adressfamilien finden Sie unter WSK-Adressfamilien.

[in] SocketType

Der Typ des Sockets, der erstellt wird. Die folgenden Sockettypen werden unterstützt:

SOCK_STREAM

Unterstützt eine zuverlässige verbindungsorientierte Bytestreamkommunikation.

SOCK_DGRAM

Unterstützt unzuverlässige verbindungslose Datagrammkommunikation.

SOCK_RAW

Unterstützt rohen Zugriff auf das Transportprotokoll.

Weitere Informationen zu den Sockettypen, die für jede unterstützte Adressfamilie unterstützt werden, finden Sie unter
WSK-Adressfamilien.

[in] Protocol

Das Transportprotokoll für den socket, der erstellt wird. Weitere Informationen zu den Protokollen, die für jede unterstützte Adressfamilie unterstützt werden, finden Sie unter WSK-Adressfamilien.

[in] Flags

Ein Flag, das die WSK-Socketkategorie für den erstellten Socket angibt. Dieser Parameter kann eines der folgenden Flags sein:

WSK_FLAG_BASIC_SOCKET

Es wird ein grundlegender Socket erstellt, der nur zum Abrufen und Festlegen von Transportstapel-Socketoptionen oder zum Ausführen von Socket-E/A-Steuerungsvorgängen verwendet werden kann.

WSK_FLAG_LISTEN_SOCKET

Es wird ein Überwachungssocket erstellt, das verwendet werden kann, um auf eingehende Verbindungen von Remotetransportadressen zu lauschen.

WSK_FLAG_DATAGRAM_SOCKET

Es wird ein Datagrammsocket erstellt, der zum Senden und Empfangen von Datagrammen verwendet werden kann.

WSK_FLAG_CONNECTION_SOCKET

Es wird ein verbindungsorientierter Socket erstellt, der zum Senden und Empfangen von Netzwerkdaten über eine Verbindung verwendet werden kann.

WSK_FLAG_STREAM_SOCKET

Es wird ein Datenstromsocket erstellt, der entweder zum Lauschen auf eingehende Verbindungen von Remotetransportadressen oder zum Senden und Empfangen von Netzwerkdaten über eine Verbindung verwendet werden kann.

Wenn eine WSK-Anwendung keines der vorherigen Flags angibt, erstellt WskSocket einen Basissocket.

[in, optional] SocketContext

Ein Zeiger auf einen vom Aufrufer bereitgestellten Kontext für den Socket, der erstellt wird. Das WSK-Subsystem übergibt diesen Zeiger an die Ereignisrückruffunktionen des Sockets. Die Kontextinformationen sind für das WSK-Subsystem undurchsichtig und müssen im nicht ausgelagerten Arbeitsspeicher gespeichert werden. Wenn die WSK-Anwendung keine Ereignisrückruffunktionen für den neuen Socket aktiviert, sollte dieser Zeiger auf NULL festgelegt werden. Bei einem Basissocket sollte dieser Zeiger immer NULL sein.

[in, optional] Dispatch

Ein Zeiger auf eine konstante Clientverteilungsstruktur. Diese Struktur ist eine Dispatchtabelle, die Zeiger auf die Ereignisrückruffunktionen für den neuen Socket enthält. Abhängig von der WSK-Socketkategorie des Sockets (wie durch den Flags-Parameter angegeben), ist dieser Parameter ein Zeiger auf eine der folgenden Strukturen.

Flag	Struktur der Verteilungstabelle
WSK_FLAG_LISTEN_SOCKET	WSK_CLIENT_LISTEN_DISPATCH
WSK_FLAG_DATAGRAM_SOCKET	WSK_CLIENT_DATAGRAM_DISPATCH
WSK_FLAG_CONNECTION_SOCKET	WSK_CLIENT_CONNECTION_DISPATCH
WSK_FLAG_STREAM_SOCKET	WSK_CLIENT_STREAM_DISPATCH

Wenn die WSK-Anwendung nicht alle Ereignisrückruffunktionen für den neuen Socket aktiviert, sollten die Zeiger in der Verteilungstabelle für die Ereignisrückruffunktionen, die sie nicht aktiviert, auf NULL festlegen. Wenn die WSK-Anwendung keine Ereignisrückruffunktionen für den neuen Socket aktiviert, sollte sie den Dispatch-Zeiger auf NULL festlegen. Bei einem Basissocket sollte dieser Zeiger immer NULL sein.

[in, optional] OwningProcess

Ein Zeiger auf den Prozess, aus dem das WSK-Subsystem den Sicherheitskontext abruft, der beim Binden des Sockets verwendet werden soll. Das WSK-Subsystem verwendet den Sicherheitskontext, um zu bestimmen, ob die lokale Transportadresse freigegeben werden kann, wenn diese Adresse bereits verwendet wird. Um den aktuellen Prozess anzugeben, legt eine WSK-Anwendung diesen Zeiger auf NULL fest.

[in, optional] OwningThread

Ein Zeiger auf einen bestimmten Thread, aus dem das WSK-Subsystem den Sicherheitskontext abruft, der beim Binden des Sockets verwendet werden soll. Das WSK-Subsystem verwendet den Sicherheitskontext, um zu bestimmen, ob die lokale Transportadresse freigegeben werden kann, wenn diese Adresse bereits verwendet wird. Wenn eine WSK-Anwendung keinen bestimmten Thread angeben muss, wird dieser Zeiger auf NULL festgelegt.

[in, optional] SecurityDescriptor

Ein Zeiger auf eine SECURITY_DESCRIPTOR-Struktur, die den Sicherheitsdeskriptor angibt, der auf den erstellten Socket angewendet werden soll. Der Sicherheitsdeskriptor steuert die Freigabe der lokalen Transportadresse, an die der Socket gebunden ist. Wenn eine WSK-Anwendung einen Zeiger ohne NULL angibt, muss sie einen Zeiger auf eine zwischengespeicherte Kopie eines Sicherheitsdeskriptors angeben, der durch Aufrufen der WskControlClient-Funktion mit dem WSK_CACHE_SD-Steuerelementcode abgerufen wurde. Um einen Standardsicherheitsdeskriptor anzugeben, der die Freigabe der lokalen Transportadresse nicht zulässt, legt eine WSK-Anwendung SecurityDescriptor auf NULL fest.

Weitere Informationen zur SECURITY_DESCRIPTOR-Struktur finden Sie auf der Referenzseite für SECURITY_DESCRIPTOR in der Microsoft Windows SDK-Dokumentation.

[in, out] Irp

Ein Zeiger auf einen vom Aufrufer zugewiesenen IRP, den das WSK-Subsystem verwendet, um die Erstellung des neuen Sockets asynchron abzuschließen. Weitere Informationen zur Verwendung von IRPs mit WSK-Funktionen finden Sie unter Verwenden von IRPs mit Winsock-Kernelfunktionen.

Rückgabewert

WskSocket gibt einen der folgenden NTSTATUS-Codes zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der neue Socket wurde erfolgreich erstellt. Die IRP wird erfolgreich status abgeschlossen.
STATUS_PENDING	Das WSK-Subsystem konnte den Socket nicht sofort erstellen. Das WSK-Subsystem schließt das IRP ab, nachdem es den neuen Socket erstellt hat. Der status der Socketerstellung wird im Feld IoStatus.Status des IRP zurückgegeben.
Andere status Codes	Ein Fehler ist aufgetreten. Die IRP wird mit einem Fehler status abgeschlossen.

Hinweise

Wenn die IRP erfolgreich status abgeschlossen wird, enthält das IoStatus.Information-Feld des IRP einen Zeiger auf eine Socketobjektstruktur ( WSK_SOCKET) für den neuen Socket.

Eine WSK-Anwendung kann eine Liste der verfügbaren Transportprotokolle abrufen, indem sie die WskControlClient-Funktion mit dem WSK_TRANSPORT_LIST_QUERY-Steuerelementcode aufruft. WskControlClient gibt eine Liste von WSK_TRANSPORT Strukturen zurück, die alle gültigen Kombinationen der Parameter AddressFamily, SocketType und Protocol enthält.

Wenn eine WSK-Anwendung erfolgreich einen neuen Socket erstellt, sind alle Ereignisrückruffunktionen für den neuen Socket standardmäßig deaktiviert. Weitere Informationen zum Aktivieren der Ereignisrückruffunktionen des neuen Sockets finden Sie unter Aktivieren und Deaktivieren von Ereignisrückruffunktionen.

Wenn eine WSK-Anwendung einen Zeiger ohne NULL für den SecurityDescriptor-Parameter angibt, darf sie den zwischengespeicherten Sicherheitsdeskriptor erst freigeben, nachdem die IRP abgeschlossen wurde.

Das WSK-Subsystem ordnet den Arbeitsspeicher für die Socketobjektstruktur (WSK_SOCKET) für den neuen Socket im Namen der WSK-Anwendung zu. Das WSK-Subsystem gibt die Zuordnung dieses Arbeitsspeichers auf, wenn der Socket geschlossen wird.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Zielplattform	Universell
Header	wsk.h (einschließen von Wsk.h)
IRQL	<= DISPATCH_LEVEL