PFN_WSK_SOCKET_CONNECT Rückruffunktion (wsk.h)

Artikel
03/05/2024

Die WskSocketConnect-Funktion erstellt einen neuen verbindungsorientierten Socket, bindet ihn an eine lokale Transportadresse, stellt eine Verbindung mit einer angegebenen Remotetransportadresse her und gibt einen Zeiger auf das zugeordnete Socketobjekt zurück.

Syntax

PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;

NTSTATUS PfnWskSocketConnect(
  [in]           PWSK_CLIENT Client,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
                 ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *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 WskCaptureProviderNPI-Funktion .

[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] LocalAddress

Ein Zeiger auf eine Struktur, die die lokale Transportadresse angibt, an die der Socket gebunden werden soll. Die WSK-Anwendung muss einen Zeiger auf den spezifischen SOCKADDR-Strukturtyp angeben, der der Adressfamilie für den erstellten Socket entspricht.

[in] RemoteAddress

Ein Zeiger auf eine Struktur, die die Remotetransportadresse angibt, mit der der Socket verbunden werden soll. Die WSK-Anwendung muss einen Zeiger auf den spezifischen SOCKADDR-Strukturtyp angeben, der der Adressfamilie für den erstellten Socket entspricht.

Flags

Dieser Parameter ist für die Systemverwendung reserviert. WSK-Anwendungen müssen diesen Parameter auf 0 festlegen.

[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.

[in, optional] Dispatch

Ein Zeiger auf eine Konstante WSK_CLIENT_CONNECTION_DISPATCH Struktur. Diese Struktur ist eine Dispatchtabelle, die Zeiger auf die Ereignisrückruffunktionen für den neuen Socket enthält. 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 nicht aktiviert werden, auf NULL festgelegt werden. Wenn die WSK-Anwendung keine Ereignisrückruffunktionen für den neuen Socket aktiviert, sollte dieser Zeiger auf NULL festgelegt werden.

[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, legt sie diesen Zeiger auf NULL fest.

[in, optional] SecurityDescriptor

Ein Zeiger auf eine SECURITY_DESCRIPTOR-Struktur, die den Sicherheitsdeskriptor angibt, der auf den erstellten Socket angewendet werden soll. Die Sicherheitsbeschreibung steuert die Freigabe der lokalen Transportadresse, an die der Socket gebunden ist. Wenn eine WSK-Anwendung einen Nicht-NULL-Zeiger angibt, muss sie einen Zeiger auf eine zwischengespeicherte Kopie einer Sicherheitsbeschreibung angeben, die 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

WskSocketConnect 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. Die 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 das 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 WSK_TRANSPORT Strukturen zurück, die alle gültigen Kombinationen der SocketType - und Protocol-Parameter enthält.

Das WSK-Subsystem bestimmt die Adressfamilie für den neuen Socket aus der Adressfamilie, die in der SOCKADDR-Struktur angegeben ist, auf die der LocalAddress-Parameter verweist.

Wenn die WSK-Anwendung vor dem Binden oder Verbinden des Sockets eine Socketoption festlegen oder einen E/A-Steuerungsvorgang für den Socket ausstellen muss, muss die WSK-Anwendung die Funktionen WskSocket, WskBind und WskConnect aufrufen, anstatt die WskSocketConnect-Funktion aufzurufen.

Wenn eine WSK-Anwendung erfolgreich einen neuen Socket erstellt, sind alle Ereignisrückruffunktionen auf dem 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 Nicht-NULL-Zeiger für den SecurityDescriptor-Parameter angibt, darf sie den zwischengespeicherten Sicherheitsdeskriptor erst freigeben, nachdem die IRP abgeschlossen ist.

Das WSK-Subsystem weist den Arbeitsspeicher für die Socketobjektstruktur (WSK_SOCKET) für den neuen Socket im Auftrag der WSK-Anwendung zu. Das WSK-Subsystem ordnet diesen Arbeitsspeicher zu, wenn der Socket geschlossen ist.

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