PFN_WSK_RECEIVE Rückruffunktion (wsk.h)

Artikel
08/08/2023

Die WskReceive-Funktion empfängt Daten über einen verbindungsorientierten Oder Stream-Socket von einer Remotetransportadresse.

Syntax

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

Parameter

[in] Socket

Ein Zeiger auf eine WSK_SOCKET-Struktur , die das Socketobjekt für den Socket angibt, von dem die Daten empfangen werden sollen.

[in] Buffer

Ein Zeiger auf eine initialisierte WSK_BUF-Struktur , die den Datenpuffer beschreibt, der die Daten aus dem Socket empfängt.

[in] Flags

Ein ULONG-Wert, der einen bitweisen OR einer Kombination der folgenden Flags enthält:

WSK_FLAG_WAITALL

Warten Sie, bis der Datenpuffer vollständig gefüllt ist. Wenn dieses Flag angegeben ist, wird die im Irp-Parameter angegebene IRP erst abgeschlossen, wenn eines der folgenden Ereignisse auftritt:

Der Datenpuffer, der von der WSK_BUF-Struktur beschrieben wird, auf die der Buffer-Parameter verweist, ist vollständig gefüllt.
Die Verbindung wird vom Remotesender ordnungsgemäß getrennt.
Die Verbindung wird entweder von der WSK-Anwendung oder vom Remotesender abgebrochen.
Die angegebene IRP wird abgebrochen.

Dieses Flag wird vom Microsoft TCP/IP-Transportprotokoll unterstützt. Dieses Flag wird von anderen Transportprotokollen möglicherweise nicht unterstützt.

WSK_FLAG_DRAIN

Warten Sie, bis der Socket getrennt ist, und verwerfen Sie alle Daten, die auf dem Socket empfangen werden. Wenn dieses Flag angegeben ist, wird die angegebene IRP erst abgeschlossen, wenn eines der folgenden Ereignisse auftritt:

Die Verbindung wird vom Remotesender ordnungsgemäß getrennt.
Die Verbindung wird entweder von der WSK-Anwendung oder vom Remotesender abgebrochen.
Die angegebene IRP wird abgebrochen.

Alle empfangenen Daten werden vom WSK-Subsystem verworfen. Es werden keine empfangenen Daten in den Datenpuffer kopiert. Der Buffer-Parameter ist weiterhin erforderlich, wenn dieses Flag angegeben wird, aber die Länge des Puffers, der von der WSK_BUF-Struktur beschrieben wird, muss 0 sein.

Dieses Flag wird vom Microsoft TCP/IP-Transportprotokoll unterstützt. Dieses Flag wird von anderen Transportprotokollen möglicherweise nicht unterstützt.

Die flags WSK_FLAG_WAITALL und WSK_FLAG_DRAIN schließen sich gegenseitig aus. Eine WSK-Anwendung sollte nicht beide Flags gleichzeitig angeben.

[in, out] Irp

Ein Zeiger auf eine vom Aufrufer zugewiesene IRP, die das WSK-Subsystem verwendet, um den Empfangsvorgang asynchron abzuschließen. Weitere Informationen zur Verwendung von IRPs mit WSK-Funktionen finden Sie unter Verwenden von IRPs mit Winsock-Kernelfunktionen.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_SUCCESS	Daten wurden erfolgreich vom Socket empfangen. Die IRP wird erfolgreich status abgeschlossen. Das Feld IoStatus.Information des IRP enthält die Anzahl der empfangenen Bytes.
STATUS_PENDING	Das WSK-Subsystem konnte die Daten nicht sofort vom Socket empfangen. Das WSK-Subsystem schließt das IRP ab, nachdem es die Daten vom Socket empfangen hat. Die status des Empfangsvorgangs wird im Feld IoStatus.Status des IRP zurückgegeben. Wenn der Vorgang erfolgreich ist, enthält das IoStatus.Information-Feld des IRP die Anzahl der empfangenen Bytes.
STATUS_FILE_FORCED_CLOSED	Der Socket ist nicht mehr funktionsfähig. Die IRP wird mit einem Fehler status abgeschlossen. Die WSK-Anwendung muss die WskCloseSocket-Funktion aufrufen, um den Socket so schnell wie möglich zu schließen.
STATUS_NOT_SUPPORTED	Ein angegebenes Flag wird vom zugrunde liegenden Netzwerktransport nicht unterstützt.
Andere status Codes	Ein Fehler ist aufgetreten. Die IRP wird mit einem Fehler status abgeschlossen.

Hinweise

Eine WSK-Anwendung kann die WskReceive-Funktion nur für einen verbindungsorientierten Socket oder Einen Stream aufrufen, der zuvor mit einer Remotetransportadresse verbunden war. Ein verbindungsorientierter Socket ist mit einer der folgenden Methoden mit einer Remotetransportadresse verbunden:

Die WSK-Anwendung stellt eine Verbindung mit dem Socket her, indem die WskConnect-Funktion aufgerufen wird.
Die WSK-Anwendung erstellt, bindet den Socket und stellt eine Verbindung her, indem die WskSocketConnect-Funktion aufgerufen wird.
Das WSK-Subsystem stellt eine Verbindung mit dem Socket her, wenn die WSK-Anwendung eine eingehende Verbindungsanforderung für einen Listensocket akzeptiert.

Wenn die WskReceiveEvent-Ereignisrückruffunktion einer WskReceiveEvent-Anwendung auf einem verbindungsorientierten Socket aktiviert ist und die Anwendung auch einen ausstehenden Aufruf der WskReceive-Funktion auf demselben verbindungsorientierten Socket aufweist, hat der ausstehende Aufruf der WskReceive-Funktion Vorrang vor der WskReceive-Ereignisrückruffunktion . Das WSK-Subsystem ruft die WskReceiveEvent-Ereignisrückruffunktion der Anwendung nur auf, wenn keine IRPs aus ausstehenden Aufrufen der WskReceive-Funktion in die Warteschlange gestellt werden. Eine WSK-Anwendung sollte jedoch nicht davon ausgehen, dass das WSK-Subsystem die WskReceiveEvent-Ereignisrückruffunktion der Anwendung für einen verbindungsorientierten Socket mit einem ausstehenden Aufruf der WskReceive-Funktion nicht aufruft . Racebedingungen sind vorhanden, bei denen das WSK-Subsystem weiterhin die WskReceiveEvent-Ereignisrückruffunktion der WSK-Anwendung für den Socket aufrufen kann. Die einzige Möglichkeit für eine WSK-Anwendung sicherzustellen, dass das WSK-Subsystem die WskReceiveEvent-Ereignisrückruffunktion der Anwendung für einen verbindungsorientierten Socket nicht aufruft, besteht darin, die WskReceiveEvent-Ereignisrückruffunktion der Anwendung auf dem Socket zu deaktivieren.

Eine WSK-Anwendung kann die WskReceive-Funktion aufrufen, deren Länge null im Length-Member der WSK_BUF Struktur angegeben ist, auf die der Buffer-Parameter verweist. Das Angeben einer Länge von 0 in diesem Member ist in den folgenden Situationen nützlich:

Beim erneuten Aktivieren der WskReceiveEvent-Ereignisrückruffunktion für einen Socket, nachdem die WskReceiveEvent-Ereignisrückruffunktion zuvor STATUS_DATA_NOT_ACCEPTED
Wenn Sie das WSK_FLAG_DRAIN-Flag angeben, um alle zusätzlichen Daten zu verwerfen, die auf dem Socket empfangen werden

Wenn die WskReceive-Funktion STATUS_PENDING zurückgibt, muss die MDL-Kette, die in der WSK_BUF-Struktur beschrieben wird, auf die der Buffer-Parameter verweist, im Arbeitsspeicher bleiben, bis die IRP abgeschlossen 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