PFN_WSK_RECEIVE Rückruffunktion (wsk.h)

Artikel
02/07/2025

Die WskReceive-Funktion empfängt Daten über einen verbindungsorientierten Oder Datenstromsocket von einer Remote-Transportadresse.

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 ausgefüllt ist. Wenn dieses Flag angegeben ist, wird das im Irp Parameter angegebene IRP erst abgeschlossen, wenn eines der folgenden Ereignisse eintritt:

Der durch die WSK_BUF Struktur beschriebene Datenpuffer, auf den der parameter Buffer verweist, wird vollständig ausgefüllt.
Die Verbindung wird ordnungsgemäß vom Remoteabsender getrennt.
Die Verbindung wird entweder von der WSK-Anwendung oder vom Remoteabsender getrennt.
Der angegebene IRP wird abgebrochen.

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

WSK_FLAG_DRAIN

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

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

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

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

Die Kennzeichen 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 ein vom Aufrufer zugewiesenes IRP, das vom WSK-Subsystem verwendet wird, um den Empfangsvorgang asynchron abzuschließen. Weitere Informationen zur Verwendung von IRPs mit WSK-Funktionen finden Sie unter Verwenden von IRPs mit Winsock Kernel Functions.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_SUCCESS	Daten wurden erfolgreich vom Socket empfangen. Das IRP wird mit dem Erfolgsstatus abgeschlossen. Das IoStatus.Information Feld des IRP enthält die Anzahl der empfangenen Bytes.
STATUS_PENDING	Das WSK-Subsystem konnte die Daten vom Socket nicht sofort empfangen. Das WSK-Subsystem schließt das IRP ab, nachdem es die Daten vom Socket empfangen hat. Der Status des Empfangsvorgangs wird im feld IoStatus.Status 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. Das IRP wird mit dem Fehlerstatus 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 Statuscodes	Fehler. Das IRP wird mit dem Fehlerstatus abgeschlossen.

Bemerkungen

Eine WSK-Anwendung kann die WskReceive--Funktion nur für einen verbindungsorientierten oder Streamsocket aufrufen, der zuvor mit einer Remote-Transportadresse verbunden wurde. Ein verbindungsorientierter Socket ist über eine der folgenden Methoden mit einer Remote-Transportadresse verbunden:

Die WSK-Anwendung verbindet den Socket durch Aufrufen der funktion WskConnect.
Die WSK-Anwendung erstellt, bindet und verbindet den Socket durch Aufrufen der WskSocketConnect--Funktion.
Das WSK-Subsystem verbindet den Socket, wenn die WSK-Anwendung eine eingehende Verbindungsanforderung für einen Überwachungssocket akzeptiert.

Wenn die WskReceiveEvent Ereignisrückruffunktion einer WSK-Anwendung in einem verbindungsorientierten Socket aktiviert ist und die Anwendung auch über einen ausstehenden Aufruf der WskReceive--Funktion für denselben verbindungsorientierten Socket verfügt, wenn Daten eingehen, hat der ausstehende Aufruf der WskReceive--Funktion Vorrang vor der WskReceiveEvent Ereignisrückruffunktion. Das WSK-Subsystem ruft die WskReceiveEvent Ereignisrückruffunktion 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 für einen verbindungsorientierten Socket mit einem ausstehenden Aufruf der WskReceive--Funktion nicht aufruft. Race conditions exist where the WSK subsystem could still call the WSK application's WskReceiveEvent event callback function for the socket. Die einzige Möglichkeit für eine WSK-Anwendung, um sicherzustellen, dass das WSK-Subsystem die WskReceiveEvent Ereignisrückruffunktion für einen verbindungsorientierten Socket nicht aufruft, besteht darin, die WskReceiveEvent Ereignisrückruffunktion der Anwendung im Socket zu deaktivieren.

Eine WSK-Anwendung kann die WskReceive--Funktion mit einer Länge null aufrufen, die im Length Member der WSK_BUF Struktur angegeben ist, auf die der parameter Buffer verweist. Die Angabe einer Länge null in diesem Element ist in den folgenden Situationen hilfreich:

Beim erneuten Aktivieren der WskReceiveEvent Ereignisrückruffunktion für einen Socket nach dem WskReceiveEvent Ereignisrückruffunktion zuvor STATUS_DATA_NOT_ACCEPTED
Beim Angeben des WSK_FLAG_DRAIN Flags, um alle zusätzlichen Daten zu verwerfen, die im Socket empfangen werden

Wenn die WskReceive--Funktion STATUS_PENDING zurückgibt, muss die in der WSK_BUF Struktur beschriebene MDL-Kette, auf die der parameter Buffer verweist, im Arbeitsspeicher bleiben, bis das IRP abgeschlossen ist.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Zielplattform-	Universal
Header-	wsk.h (include Wsk.h)
IRQL-	<= DISPATCH_LEVEL