PFN_WSK_RECEIVE_EVENT Rückruffunktion (wsk.h)

Artikel
02/07/2025

Die WskReceiveEvent Ereignisrückruffunktion benachrichtigt eine WSK-Anwendung, dass Daten in einem verbindungsorientierten Socket empfangen wurden.

Syntax

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

Parameter

[in, optional] SocketContext

Ein Zeiger auf den Socketkontext für den verbindungsorientierten Socket, der die Daten empfangen hat. Die WSK-Anwendung hat diesen Zeiger auf das WSK-Subsystem auf eine der folgenden Arten bereitgestellt:

Es hat die WskSocket--Funktion aufgerufen, um den Socket zu erstellen.
Sie hat die WskSocketConnect-Funktion aufgerufen, um den Socket zu erstellen.
Sie hat die WskAccept--Funktion aufgerufen, um den Socket als eingehende Verbindung zu akzeptieren.
Die WskAcceptEvent Ereignisrückruffunktion wurde aufgerufen, um den Socket als eingehende Verbindung zu akzeptieren.

[in] Flags

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

Wert	Bedeutung
WSK_FLAG_RELEASE_ASAP	Die Datenpuffer, die die empfangenen Daten enthalten, sollten ggf. nicht von der WSK-Anwendung aufbewahrt werden. Wenn die WSK-Anwendung die Puffer behält, sollte sie so schnell wie möglich freigegeben werden, indem sie die WskRelease-Funktion aufrufen.
WSK_FLAG_ENTIRE_MESSAGE	Die Datenpuffer enthalten entweder eine gesamte Nachricht oder den endgültigen Teil einer Nachricht. Die Interpretation, was eine gesamte Nachricht darstellt, ist transportprotokollspezifisch. Für TCP gibt dieses Flag an, dass das Pushbit für mindestens ein TCP-Segment festgelegt wurde, das die Daten in den Datenpuffern darstellt.
WSK_FLAG_AT_DISPATCH_LEVEL	Das WSK-Subsystem namens WskReceiveEvent Ereignisrückruffunktion bei IRQL = DISPATCH_LEVEL. Wenn dieses Flag nicht festgelegt ist, hat das WSK-Subsystem möglicherweise die WskReceiveEvent Ereignisrückruffunktion bei einer IRQL-<= DISPATCH_LEVEL aufgerufen.

[in, optional] DataIndication

Ein Zeiger auf eine verknüpfte Liste von WSK_DATA_INDICATION Strukturen, die die empfangenen Daten beschreiben. Wenn dieser Parameter NULL-ist, ist der Socket nicht mehr funktionsfähig, und die WSK-Anwendung muss die WskCloseSocket--Funktion aufrufen, um den Socket so schnell wie möglich zu schließen.

[in] BytesIndicated

Die Anzahl der byte empfangenen Daten, die durch die verknüpfte Liste der WSK_DATA_INDICATION Strukturen beschrieben werden.

[in, out] BytesAccepted

Ein Zeiger auf eine variable SIZE_T Typ, die die Anzahl der empfangenen Daten empfängt, die von der WSK-Anwendung akzeptiert werden. Diese Variable muss nur festgelegt werden, wenn die WSK-Anwendung einen Teil der Gesamtanzahl der empfangenen Daten akzeptiert. Wenn die WSK-Anwendung alle empfangenen Daten akzeptiert, muss diese Variable nicht festgelegt werden. Wenn die WskReceiveEvent Ereignisrückruffunktion einen anderen Status als STATUS_SUCCESS zurückgibt, ignoriert das WSK-Subsystem den Wert dieser Variablen.

Rückgabewert

Die WskReceiveEvent- Ereignisrückruffunktion einer WSK-Anwendung kann einen der folgenden NTSTATUS-Codes zurückgeben:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die WSK-Anwendung akzeptierte mindestens einige der empfangenen Daten. Wenn die WSK-Anwendung alle empfangenen Daten akzeptiert hat, kann das WSK-Subsystem die WskReceiveEvent Ereignisrückruffunktion erneut aufrufen, wenn neue Daten im Socket empfangen werden. Wenn die WSK-Anwendung jedoch nur einen Teil der empfangenen Daten akzeptiert hat, ruft das WSK-Subsystem die WskReceiveEvent Ereignisrückruffunktion nicht erneut auf, bis die WSK-Anwendung die WskReceive--Funktion aufruft. Nachdem die WSK-Anwendung die WskReceive--Funktion aufgerufen hat, wird das WSK-Subsystem den Aufruf der WskReceiveEvent Ereignisrückruffunktion mit allen verbleibenden gepufferten Daten und beim Empfang neuer Daten im Socket fortgesetzt. Eine WSK-Anwendung kann die WskReceive--Funktion mit einem Puffer der Länge Null aufrufen, wodurch das WSK-Subsystem den Aufruf der WskReceiveEvent Ereignisrückruffunktion fortsetzen kann, ohne WskReceive aufzurufen, um daten aus dem Socket zu empfangen.
STATUS_PENDING	Die WSK-Anwendung akzeptierte die Daten, aber nicht alle In der verknüpften Liste der WSK_DATA_INDICATION Strukturen enthaltenen Daten. Die WSK-Anwendung behält die verknüpfte Liste der WSK_DATA_INDICATION Strukturen bei, bis alle Daten abgerufen wurden. Nachdem die WSK-Anwendung alle Daten abgerufen hat, ruft sie die WskRelease Funktion auf, um die verknüpfte Liste der WSK_DATA_INDICATION Strukturen wieder in das WSK-Subsystem zurückzugeben. Das WSK-Subsystem kann die WskReceiveEvent Ereignisrückruffunktion erneut aufrufen, wenn neue Daten im Socket empfangen werden.
STATUS_DATA_NOT_ACCEPTED	Die WSK-Anwendung akzeptierte die Daten nicht. In diesem Fall verfügt das WSK-Subsystem über den zugrunde liegenden Transportpuffer, sofern möglich oder anderweitig vom Protokoll erforderlich. Das WSK-Subsystem ruft die WskReceiveEvent Ereignisrückruffunktion erst erneut auf, nachdem die WSK-Anwendung die WskReceive--Funktion aufruft. Nachdem die WSK-Anwendung die WskReceive--Funktion aufgerufen hat, wird das WSK-Subsystem den Aufruf der WskReceiveEvent Ereignisrückruffunktion mit allen verbleibenden gepufferten Daten und beim Empfang neuer Daten im Socket fortgesetzt. Eine WSK-Anwendung kann die WskReceive--Funktion mit einem Puffer der Länge Null aufrufen, wodurch das WSK-Subsystem den Aufruf der WskReceiveEvent Ereignisrückruffunktion fortsetzen kann, ohne WskReceive aufzurufen, um daten aus dem Socket zu empfangen.

Bemerkungen

Das WSK-Subsystem ruft die WskReceiveEvent Ereignisrückruffunktion einer WSK-Anwendung auf, wenn neue Daten in einem verbindungsorientierten Socket empfangen werden, nur wenn die Ereignisrückruffunktion zuvor mit der SO_WSK_EVENT_CALLBACK Socketoption aktiviert wurde. Weitere Informationen zum Aktivieren der Ereignisrückruffunktionen eines Sockets finden Sie unter Aktivieren und Deaktivieren von Ereignisrückruffunktionen.

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.

Anmerkung

Winsock Kernel (WSK) ruft diesen Rückruf seriell auf, sodass er nicht immer aufgerufen wird, sobald Daten empfangen werden.

Das WSK-Subsystem ruft die WskReceiveEvent Ereignisrückruffunktion einer WSK-Anwendung bei IRQL <= DISPATCH_LEVEL auf.

Die WskReceiveEvent- Ereignisrückruffunktion einer WSK-Anwendung darf nicht auf den Abschluss anderer WSK-Anforderungen im Kontext von WSK-Abschluss- oder Ereignisrückruffunktionen warten. Der Rückruf kann andere WSK-Anforderungen initiieren (vorausgesetzt, es verbringt nicht zu viel Zeit bei DISPATCH_LEVEL), aber er darf nicht auf den Abschluss warten, auch wenn der Rückruf bei IRQL = PASSIVE_LEVEL aufgerufen wird.

Anforderungen

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