EVT_WDF_IO_QUEUE_IO_STOP Rückruffunktion (wdfio.h)
[Gilt für KMDF und UMDF]
Die EvtIoStop Ereignisrückruffunktion eines Treibers wird abgeschlossen, erneut abgefragt oder die Verarbeitung einer angegebenen Anforderung 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
)
{...}
Die Parameter
[in] Queue
Ein Handle für das Framework-Warteschlangenobjekt, das der E/A-Anforderung zugeordnet ist.
[in] Request
Ein Handle zu einem Framework-Anforderungsobjekt.
[in] ActionFlags
Ein bitweises ODER eines oder mehrerer WDF_REQUEST_STOP_ACTION_FLAGS-typed Flags, die den Grund für den Aufruf der Rückruffunktion und den Abbruch der Anforderung identifizieren.
Rückgabewert
Nichts
Bemerkungen
Ein Treiber registriert eine EvtIoStop- Rückruffunktion, wenn sie WdfIoQueueCreateaufruft. Weitere Informationen zum Aufrufen WdfIoQueueCreatefinden 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 zugrunde liegende Gerät der Warteschlange den 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 diejenigen, die er an ein E/A-Ziel weitergeleitet hat.
In den meisten Fällen schließt die EvtIoStop- Rückruffunktion ab, brichtab oder verschiebt die weitere Verarbeitung der E/A-Anforderung.
In der Regel führt der Treiber eine der folgenden Aktionen aus:
-
Wenn der Treiber die E/A-Anforderung besitzt, sie ruft WdfRequestUnmarkCancelable auf (wenn die Anforderung abgebrochen werden kann) und ruft entweder WdfRequestStopAcknowledge mit einem Requeue Wert von TRUE auf, oder sie ruft WdfRequestComplete mit einem Abschlussstatuswert von STATUS_SUCCESS oder STATUS_CANCELLED auf.
Bevor sie WdfRequest-Xxx- Methoden sicher aufrufen kann, muss der Treiber sicherstellen, dass die Implementierung von EvtIoStop- exklusiven Zugriff auf die Anforderung hat.
Um dies zu tun, muss der Treiber den Zugriff auf die Anforderung synchronisieren, um zu verhindern, dass andere Threads die Anforderung gleichzeitig bearbeiten. Die gewählte Synchronisierungsmethode hängt vom Design Des Treibers ab.
Wenn die Anforderung z. B. in einem freigegebenen Kontextbereich gehalten 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 anfordern.
Alternativ verschiebt der Treiber die weitere Verarbeitung der Anforderung und ruft WdfRequestStopAcknowledge mit einem Requeue Wert von 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.
Oder, wenn der Treiber die E/A-Anforderung an einen Treiber auf niedrigerer Ebene in seinem eigenen Treiberstapel weitergeleitet hat, und das Framework ruft den EvtIoStop Rückruf des Treibers mit einem ActionFlags- Wert von WdfRequestStopActionSuspendauf, der Treiber kann WdfRequestStopAcknowledge mit einem Requeue Wert von FALSE aufrufen. Bevor sie dies tun, 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 Callbackfunktion des Treibers kann Anforderungen abschließen, während sich das Gerät im Energiesparmodus befindet.
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. Potenziell kann diese Inaktion verhindern, dass ein System in den Ruhezustand oder einen anderen Energiesparmodus 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 WdfRequestComplete aufgerufen wird, um die Anforderung abzuschließen (oder abzubrechen), oder WdfRequestStopAcknowledge, um die Anforderung erneut abzufragen.
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 möglicherweise EvtIoStop- für diese Anforderung auf.
Weitere Informationen zur EvtIoStop- Rückruffunktion finden Sie unter Verwenden von Power-Managed E/A-Warteschlangen.
Diese Rückruffunktion kann bei IRQL <= DISPATCH_LEVEL aufgerufen werden, es sei denn, das ExecutionLevel Mitglied der WDF_OBJECT_ATTRIBUTES Struktur des Geräts oder Treibers wird auf WdfExecutionLevelPassivefestgelegt.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | universell |
| Minimale KMDF-Version | 1.0 |
| Mindest-UMDF-Version | 2.0 |
| Kopfzeile | wdfio.h (einschließen Wdf.h) |
| IRQL | <= DISPATCH_LEVEL (siehe Abschnitt "Hinweise") |