PFN_WSK_RECEIVE_FROM_EVENT Rückruffunktion (wsk.h)

Artikel
02/07/2025

Die WskReceiveFromEvent Ereignisrückruffunktion benachrichtigt eine WSK-Anwendung, dass mindestens ein Datagramm in einem Datagrammsocket empfangen wurde.

Syntax

PFN_WSK_RECEIVE_FROM_EVENT PfnWskReceiveFromEvent;

NTSTATUS PfnWskReceiveFromEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATAGRAM_INDICATION DataIndication
)
{...}

Parameter

[in, optional] SocketContext

Ein Zeiger auf den Socketkontext für den Datagrammsocket, der die Datagramme empfangen hat. Die WSK-Anwendung hat diesen Zeiger auf das WSK-Subsystem bereitgestellt, wenn sie die WskSocket--Funktion aufgerufen hat, um den Datagrammsocket zu erstellen.

[in] Flags

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

MSG_BCAST

Die Datagramme wurden als Übertragung auf Linkebene oder mit einer Ziel-Transportadresse empfangen, die eine Übertragungsadresse ist.

MSG_MCAST

Die Datagramme wurden mit einer Zieltransportadresse empfangen, bei der es sich um eine Multicastadresse handelt.

WSK_FLAG_AT_DISPATCH_LEVEL

Das WSK-Subsystem namens WskReceiveFromEvent Ereignisrückruffunktion bei IRQL = DISPATCH_LEVEL. Wenn dieses Flag nicht festgelegt ist, hat das WSK-Subsystem möglicherweise die WskReceiveFromEvent Ereignisrückruffunktion bei einer IRQL-<= DISPATCH_LEVEL aufgerufen.

[in, optional] DataIndication

Ein Zeiger auf eine verknüpfte Liste von WSK_DATAGRAM_INDICATION Strukturen, die die empfangenen Datagramme 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.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die WSK-Anwendung akzeptierte die Datagramme und ruft alle Datagramme aus der verknüpften Liste der WSK_DATAGRAM_INDICATION Strukturen. Das WSK-Subsystem kann die WskReceiveFromEvent Ereignisrückruffunktion erneut aufrufen, wenn neue Datagramme im Socket empfangen werden.
STATUS_PENDING	Die WSK-Anwendung akzeptierte die Datagramme, aber nicht alle Datagramme aus der verknüpften Liste der WSK_DATAGRAM_INDICATION Strukturen. Die WSK-Anwendung behält die verknüpfte Liste der WSK_DATAGRAM_INDICATION Strukturen bei, bis alle Datagramme abgerufen wurden. Nachdem die WSK-Anwendung alle Datagramme abgerufen hat, ruft sie die WskRelease--Funktion auf, um die verknüpfte Liste der WSK_DATAGRAM_INDICATION Strukturen wieder in das WSK-Subsystem zurückzugeben. Das WSK-Subsystem kann die WskReceiveFromEvent Ereignisrückruffunktion erneut aufrufen, wenn neue Datagramme im Socket empfangen werden.
STATUS_DATA_NOT_ACCEPTED	Die WSK-Anwendung akzeptierte die Datagramme nicht. Wenn eine WSK-Anwendung diesen Statuscode zurückgibt, reagiert das WSK-Subsystem je nachdem, wie die WSK-Anwendung die WskReceiveFromEvent Ereignisrückruffunktion aktiviert hat. Wenn die WSK-Anwendung die WskReceiveFromEvent Ereignisrückruffunktion mithilfe der SO_WSK_EVENT_CALLBACK Socketoption aktiviert hat, verfügt das WSK-Subsystem über den zugrunde liegenden Transportpuffer, falls möglich oder wenn das Protokoll anderweitig erforderlich ist. Das WSK-Subsystem deaktiviert die WskReceiveFromEvent Ereignisrückruffunktion und ruft die WskReceiveFromEvent Ereignisrückruffunktion erst erneut auf, nachdem die WSK-Anwendung diese Ereignisrückruffunktion mit der SO_WSK_EVENT_CALLBACK Socketoption erneut aktiviert hat. Nachdem die WSK-Anwendung die WskReceiveFromEvent Ereignisrückruffunktion erneut aktiviert hat, setzt das WSK-Subsystem den Aufruf der WskReceiveFromEvent Ereignisrückruffunktion mit allen verbleibenden gepufferten Datagrammen und beim Empfang neuer Datagramme im Socket fort. Wenn die WSK-Anwendung die WskReceiveFromEvent Ereignisrückruffunktion aktiviert hat WSK_SET_STATIC_EVENT_CALLBACKS Clientsteuerungsvorgang deaktiviert das WSK-Subsystem die WskReceiveFromEvent Ereignisrückruffunktion nicht. Das WSK-Subsystem ruft weiterhin die WskReceiveFromEvent Ereignisrückruffunktion auf, wenn neue Datagramme im Socket empfangen werden.

Bemerkungen

Das WSK-Subsystem ruft die WskReceiveFromEvent Ereignisrückruffunktion auf, wenn neue Datagramme nur dann in einem Datagrammsocket empfangen werden, 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 WskReceiveFromEvent Ereignisrückruffunktion einer WSK-Anwendung in einem Datagrammsocket aktiviert ist und die Anwendung auch über einen ausstehenden Aufruf der WskReceiveFrom-Funktion im gleichen Datagrammsocket verfügt, Wenn dann Datagramme eingehen, hat der ausstehende Aufruf der WskReceiveFrom-Funktion Vorrang vor der WskReceiveFromEvent Ereignisrückruffunktion. Das WSK-Subsystem ruft die WskReceiveFromEvent Ereignisrückruffunktion nur auf, wenn keine IRPs aus ausstehenden Aufrufen der WskReceiveFrom-Funktion in die Warteschlange gestellt werden. Eine WSK-Anwendung sollte jedoch nicht davon ausgehen, dass das WSK-Subsystem die WskReceiveFromEvent- Ereignisrückruffunktion für einen Datagrammsocket mit einem ausstehenden Aufruf der WskReceiveFrom-Funktion nicht aufruft. Race conditions exist where the WSK subsystem could still call the WSK application's WskReceiveFromEvent event callback function for the socket. Die einzige Möglichkeit für eine WSK-Anwendung, um sicherzustellen, dass das WSK-Subsystem die WskReceiveFromEvent Ereignisrückruffunktion in einem Datagrammsocket nicht aufruft, besteht darin, die WskReceiveFromEvent Ereignisrückruffunktion der Anwendung im Socket zu deaktivieren.

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

Die WskReceiveFromEvent 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