PFN_WSK_RECEIVE_FROM_EVENT Rückruffunktion (wsk.h)

Artikel
02/27/2024

Die WskReceiveFromEvent-Ereignisrückruffunktion benachrichtigt eine WSK-Anwendung, dass mindestens ein Datagramm für einen 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, als sie die WskSocket-Funktion aufgerufen hat , um den Datagrammsocket-Socket zu erstellen.

[in] Flags

Ein ULONG-Wert, der ein bitweises OR einer Kombination der folgenden Flags enthält:

MSG_BCAST

Die Datagramme wurden als Broadcast auf Linkebene oder mit einer Zieltransportadresse empfangen, bei der es sich um eine Broadcastadresse handelt.

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 hat die WskReceiveFromEvent-Ereignisrückruffunktion unter IRQL = DISPATCH_LEVEL aufgerufen. Wenn dieses Flag nicht festgelegt ist, hat das WSK-Subsystem möglicherweise die WskReceiveFromEvent-Ereignisrückruffunktion bei jedem 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 hat die Datagramme akzeptiert und alle Datagramme aus der verknüpften Liste von abgerufen. 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 von 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 an das WSK-Subsystem freizugeben. Das WSK-Subsystem kann die WskReceiveFromEvent-Ereignisrückruffunktion erneut aufrufen, wenn neue Datagramme im Socket empfangen werden.
STATUS_DATA_NOT_ACCEPTED	Die WSK-Anwendung hat die Datagramme nicht akzeptiert. Wenn eine WSK-Anwendung diesen status Code zurückgibt, reagiert das WSK-Subsystem unterschiedlich, je nachdem, wie die WSK-Anwendung die WskReceiveFromEvent-Ereignisrückruffunktion aktiviert hat. Wenn die WSK-Anwendung die WskReceiveFromEvent-Ereignisrückruffunktion mithilfe der Socketoption SO_WSK_EVENT_CALLBACK aktiviert hat, verfügt das WSK-Subsystem nach Möglichkeit über den zugrunde liegenden Transportpuffer, die Datagramme, oder wenn es anderweitig vom Protokoll erforderlich ist. Das WSK-Subsystem deaktiviert die WskReceiveFromEvent-Ereignisrückruffunktion und ruft die WskReceiveFromEvent-Ereignisrückruffunktion erst wieder auf, nachdem die WSK-Anwendung diese Ereignisrückruffunktion mit der Socketoption SO_WSK_EVENT_CALLBACK erneut aktiviert hat. Nachdem die WSK-Anwendung die WskReceiveFromEvent-Ereignisrückruffunktion wieder aktiviert hat, setzt das WSK-Subsystem den Aufruf der WskReceiveFromEvent-Ereignisrückruffunktion mit allen verbleibenden gepufferten Datagrammen fort, und wenn neue Datagramme im Socket empfangen werden. Wenn die WSK-Anwendung die WskReceiveFromEvent-Ereignisrückruffunktion mithilfe von 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.

Hinweise

Das WSK-Subsystem ruft die WskReceiveFromEvent-Ereignisrückruffunktion einer WSK-Anwendung auf, wenn neue Datagramme nur dann in einem Datagrammsocket empfangen werden, wenn die Ereignisrückruffunktion zuvor mit der Option SO_WSK_EVENT_CALLBACK Socket 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 für einen Datagrammsocket aktiviert ist und die Anwendung auch über einen ausstehenden Aufruf der WskReceiveFrom-Funktion für denselben Datagrammsocket verfügt, hat der ausstehende Aufruf der WskReceiveFrom-Funktion Vorrang vor der WskReceiveFromEvent-Ereignisrückruffunktion . Das WSK-Subsystem ruft die WskReceiveFromEvent-Ereignisrückruffunktion der Anwendung nur auf, wenn keine IRPs aus ausstehenden Aufrufen der WskReceiveFrom-Funktion in die Warteschlange eingereiht sind. Eine WSK-Anwendung sollte jedoch nicht davon ausgehen, dass das WSK-Subsystem nicht die WskReceiveFromEvent-Ereignisrückruffunktion der Anwendung für einen Datagrammsocket aufruft, der über einen ausstehenden Aufruf der WskReceiveFrom-Funktion verfügt . Es gibt Racebedingungen, bei denen das WSK-Subsystem weiterhin die WskReceiveFromEvent-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 WskReceiveFromEvent-Ereignisrückruffunktion der Anwendung nicht für einen Datagrammsocket aufruft, besteht darin, die WskReceiveFromEvent-Ereignisrückruffunktion der Anwendung im Socket zu deaktivieren.

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

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Zielplattform	Windows
Kopfzeile	wsk.h (einschließen von Wsk.h)
IRQL	<= DISPATCH_LEVEL