PFN_WSK_RECEIVE_EVENT Rückruffunktion (wsk.h)

Artikel
03/01/2024

Die WskReceiveEvent-Ereignisrückruffunktion benachrichtigt eine WSK-Anwendung darüber, dass Daten auf 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:

Sie 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 von der WSK-Anwendung nach Möglichkeit nicht aufbewahrt werden. Wenn die WSK-Anwendung die Puffer behält, sollte sie sie so schnell wie möglich freigeben, indem die WskRelease-Funktion aufgerufen wird.
WSK_FLAG_ENTIRE_MESSAGE	Die Datenpuffer enthalten entweder eine gesamte Nachricht oder den letzten Teil einer Nachricht. Die Interpretation, was eine gesamte Nachricht ausmacht, ist transportprotokollspezifisch. Für TCP gibt dieses Flag an, dass das Pushbit für mindestens eines der TCP-Segmente festgelegt wurde, die die Daten in den Datenpuffern bilden.
WSK_FLAG_AT_DISPATCH_LEVEL	Das WSK-Subsystem namens WskReceiveEvent-Ereignisrückruffunktion unter IRQL = DISPATCH_LEVEL. Wenn dieses Flag nicht festgelegt ist, hat das WSK-Subsystem möglicherweise die WskReceiveEvent-Ereignisrückruffunktion bei jedem 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 Bytes empfangener Daten, die durch die verknüpfte Liste der WSK_DATA_INDICATION-Strukturen beschrieben wird.

[in, out] BytesAccepted

Ein Zeiger auf eine SIZE_T typisierte Variable, die die Anzahl der Bytes empfangener Daten empfängt, die von der WSK-Anwendung akzeptiert werden. Diese Variable muss nur festgelegt werden, wenn die WSK-Anwendung einen Teil der Gesamtanzahl von Bytes empfangener Daten akzeptiert. Wenn die WSK-Anwendung alle empfangenen Daten akzeptiert, muss sie diese Variable nicht festlegen. 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 einen Teil 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 erst wieder auf, nachdem die WSK-Anwendung die WskReceive-Funktion aufgerufen hat. Nachdem die WSK-Anwendung die WskReceive-Funktion aufgerufen hat, wird das WSK-Subsystem fortgesetzt, indem die WskReceiveEvent-Ereignisrückruffunktion mit allen verbleibenden gepufferten Daten aufgerufen wird, und wenn neue Daten im Socket empfangen werden. Eine WSK-Anwendung kann die WskReceive-Funktion mit einem Puffer der Länge null aufrufen, was dazu führt, dass das WSK-Subsystem den Aufruf der WskReceiveEvent-Ereignisrückruffunktion fortsetzen kann, ohne WskReceive aufzurufen, um Daten vom Socket zu empfangen.
STATUS_PENDING	Die WSK-Anwendung hat die Daten akzeptiert, aber nicht alle Daten in der verknüpften Liste der WSK_DATA_INDICATION-Strukturen abgerufen. 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 an das WSK-Subsystem zu freigeben. Das WSK-Subsystem kann die WskReceiveEvent-Ereignisrückruffunktion erneut aufrufen, wenn neue Daten auf dem Socket empfangen werden.
STATUS_DATA_NOT_ACCEPTED	Die WSK-Anwendung hat die Daten nicht akzeptiert. In dieser Situation verfügt das WSK-Subsystem nach Möglichkeit über den zugrunde liegenden Transportpuffer für die Daten, falls dies vom Protokoll anderweitig erforderlich ist. Das WSK-Subsystem ruft die WskReceiveEvent-Ereignisrückruffunktion erst wieder auf, nachdem die WSK-Anwendung die WskReceive-Funktion aufgerufen hat. Nachdem die WSK-Anwendung die WskReceive-Funktion aufgerufen hat, wird das WSK-Subsystem fortgesetzt, indem die WskReceiveEvent-Ereignisrückruffunktion mit allen verbleibenden gepufferten Daten aufgerufen wird, und wenn neue Daten im Socket empfangen werden. Eine WSK-Anwendung kann die WskReceive-Funktion mit einem Puffer der Länge null aufrufen, was dazu führt, dass das WSK-Subsystem den Aufruf der WskReceiveEvent-Ereignisrückruffunktion fortsetzen kann, ohne WskReceive aufzurufen, um Daten vom Socket zu empfangen.

Hinweise

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

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.

Hinweis

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 unter IRQL <= DISPATCH_LEVEL auf.

Die WskReceiveEvent-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), darf aber 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