EVT_WDF_IO_QUEUE_IO_STOP Rückruffunktion (wdfio.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die EvtIoStop-Ereignisrückruffunktion eines Treibers schließt die Verarbeitung einer angegebenen Anforderung ab, wird erneut queuesiert oder angehalten, da die E/A-Warteschlange der Anforderung beendet wird.

Syntax

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

void EvtWdfIoQueueIoStop(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] ULONG ActionFlags
)
{...}

Parameter

[in] Queue

Ein Handle für das Frameworkwarteschlangenobjekt, das der E/A-Anforderung zugeordnet ist.

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

[in] ActionFlags

Ein bitweiser OR mit einem oder mehreren WDF_REQUEST_STOP_ACTION_FLAGS typisierten Flags, die den Grund für den Aufruf der Rückruffunktion und die Abbruchsanforderung angeben.

Rückgabewert

Keine

Bemerkungen

Ein Treiber registriert eine EvtIoStop-Rückruffunktion , wenn er WdfIoQueueCreate aufruft. Weitere Informationen zum Aufrufen von WdfIoQueueCreate finden Sie unter Erstellen von E/A-Warteschlangen.

Wenn ein Treiber eine EvtIoStop-Rückruffunktion für eine E/A-Warteschlange registriert, ruft das Framework sie auf, wenn das der Warteschlange zugrunde liegende Gerät seinen Arbeitszustand (D0) verlässt. Das Framework ruft die EvtIoStop-Rückruffunktion für jede E/A-Anforderung auf, die der Treiber nicht abgeschlossen hat, einschließlich Anforderungen, die der Treiber besitzt und die er an ein E/A-Ziel weitergeleitet hat.

In den meisten Fällen wird die weitere Verarbeitung der E/A-Anforderung durch die Rückruffunktion EvtIoStopabgeschlossen, abgebrochen oder verschoben.

In der Regel führt der Treiber eine der folgenden Aktionen aus:

Wenn der Treiber die E/A-Anforderung besitzt, ruft er WdfRequestUnmarkCancelable auf (wenn die Anforderung abgebrochen werden kann) und ruft entweder WdfRequestStopAcknowledge mit dem Requeue-Wert TRUE auf, oder er ruft WdfRequestComplete mit einer Vervollständigung status Wert von STATUS_SUCCESS oder STATUS_CANCELLED auf.
Bevor er WdfRequestXxx-Methoden sicher aufrufen kann, muss der Treiber sicherstellen, dass seine Implementierung von EvtIoStop exklusiven Zugriff auf die Anforderung hat.

Dazu muss der Treiber den Zugriff auf die Anforderung synchronisieren, um zu verhindern, dass andere Threads die Anforderung gleichzeitig bearbeiten. Die Synchronisierungsmethode, die Sie auswählen, hängt vom Design Ihres Treibers ab.

Wenn die Anforderung beispielsweise in einem freigegebenen Kontextbereich gespeichert wird, kann der EvtIoStop-Rückruf eine interne Treibersperre abrufen, die Anforderung aus dem freigegebenen Kontext entfernen und dann die Sperre freigeben. An diesem Punkt besitzt der EvtIoStop-Rückruf die Anforderung und kann die Anforderung sicher abschließen oder erneut ausstellen.

Alternativ verschiebt der Treiber die weitere Verarbeitung der Anforderung und ruft WdfRequestStopAcknowledge mit dem Requeue-Wert FALSE auf.
Wenn der Treiber die E/A-Anforderung an ein E/A-Ziel weitergeleitet hat, kann er WdfRequestCancelSentRequest aufrufen, um zu versuchen, die Anforderung abzubrechen.
Wenn der Treiber die E/A-Anforderung an einen Treiber auf niedrigerer Ebene in seinem eigenen Treiberstapel weitergeleitet hat und das Framework den EvtIoStop-Rückruf des Treibers mit dem ActionFlags-WertWdfRequestStopActionSuspend aufruft, kann der Treiber WdfRequestStopAcknowledge mit dem Requeue-Wert FALSE aufrufen. Zuvor sollte der Treiber überprüfen, ob die folgenden Bedingungen erfüllt sind:
- Der niedrigere Treiber beendet die Verarbeitung aller ausstehenden E/A-Anforderungen als Reaktion auf den Empfang eines Gerätesatz-IRP (Dx).
- Die CompletionRoutine-Rückruffunktion des Treibers kann Anforderungen abschließen, während sich das Gerät in einem Energiesparzustand befindet.

Ein Treiber kann in EvtIoStop keine Maßnahmen für Anforderungen ergreifen, die garantiert in kurzer Zeit abgeschlossen werden.

In diesem Fall wartet das Framework, bis die angegebene Anforderung abgeschlossen ist, bevor das Gerät (oder das System) in einen niedrigeren Leistungszustand verschoben oder das Gerät entfernt wird. Möglicherweise kann diese Untätigkeit verhindern, dass ein System in seinen Ruhezustand oder einen anderen niedrigen Systemleistungszustand wechselt. In extremen Fällen kann es dazu führen, dass das System mit dem Fehlercheckcode 9F abstürzt.

Wenn das WdfRequestStopRequestCancelable-Flag im ActionFlags-Parameter festgelegt ist, muss der Treiber WdfRequestUnmarkCancelable aufrufen, bevor er WdfRequestComplete aufruft , um die Anforderung oder WdfRequestStopAcknowledge auszuführen, um die Anforderung erneut zu queue.

Wenn der Treiber eine E/A-Anforderung von einem seiner Anforderungshandler weiterleitet und das WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET-Flag in der WDF_REQUEST_SEND_OPTIONS Struktur der Anforderung angibt, ruft das Framework die EvtIoStop-Rückruffunktion des Treibers für diese Anforderung nicht auf. Wenn der Treiber jedoch dieselbe E/A-Anforderung von einem anderen Thread weiterleitet, ruft das Framework evtIoStop für diese Anforderung möglicherweise auf.

Weitere Informationen zur Rückruffunktion EvtIoStop finden Sie unter Verwenden Power-Managed E/A-Warteschlangen.

Diese Rückruffunktion kann unter IRQL <= DISPATCH_LEVEL aufgerufen werden, es sei denn, das ExecutionLevel-Element der WDF_OBJECT_ATTRIBUTES Struktur des Geräts oder Treibers ist auf WdfExecutionLevelPassive festgelegt.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfio.h (einschließen von Wdf.h)
IRQL	<= DISPATCH_LEVEL (siehe Abschnitt Hinweise)