EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE Rückruffunktion (wdfio.h)
[Gilt für KMDF und UMDF]
Die EvtIoCanceledOnQueue-Ereignisrückruffunktion eines Treibers informiert den Treiber darüber, dass er eine E/A-Anforderung abschließen muss, die das Framework aus einer E/A-Warteschlange entfernt hat.
Syntax
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;
void EvtWdfIoQueueIoCanceledOnQueue(
[in] WDFQUEUE Queue,
[in] WDFREQUEST Request
)
{...}
Parameter
[in] Queue
Ein Handle für ein E/A-Warteschlangenobjekt.
[in] Request
Ein Handle für ein Anforderungsobjekt.
Rückgabewert
Keine
Bemerkungen
Ein Treiber registriert eine EvtIoCanceledOnQueue-Rückruffunktion , wenn er die WdfIoQueueCreate-Methode aufruft . Weitere Informationen zum Aufrufen von WdfIoQueueCreate finden Sie unter Erstellen von E/A-Warteschlangen.
Wenn ein Treiber eine EvtIoCanceledOnQueue-Rückruffunktion für eine E/A-Warteschlange registriert, ruft das Framework die Rückruffunktion in den folgenden Situationen auf:
- Ein Anforderungshandler empfängt eine E/A-Anforderung von einer E/A-Warteschlange, der Treiber ruft WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueue oder WdfRequestRequeue auf, um die Anforderung erneut in die E/A-Warteschlange zu stellen, für die die Rückruffunktion EvtIoCanceledOnQueue registriert ist, und der zugehörige E/A-Vorgang wird anschließend abgebrochen.
- Die EvtIoInCallerContext-Rückruffunktion des Treibers empfängt eine E/A-Anforderung, der Treiber ruft WdfDeviceEnqueueRequest auf, um die Anforderung zurück an das Framework zu übergeben, das Framework platziert die Anforderung dann in der E/A-Warteschlange, für die die Rückruffunktion EvtIoCanceledOnQueue registriert ist, und der zugehörige E/A-Vorgang wird anschließend abgebrochen.
In der Regel schließt der Treiber in EvtIoCanceledOnQueuedie E/A-Anforderung mit einem Abschluss status STATUS_CANCELLED ab.
In einigen Fällen hat der Treiber möglicherweise zuvor eine E/A-Anforderung erneut in eine manuelle Warteschlange queuiert, um möglicherweise auf Informationen zu warten. Beispielsweise kann ein Treiber in einem seiner Anforderungshandler eine E/A-Anforderung, die einer ausstehenden DMA-Transaktion zugeordnet ist, in einer manuellen Warteschlange platzieren. In diesem Fall versucht der Treiber, die DMA-Transaktion in seinem EvtIoCanceledOnQueue-Rückruf abzubrechen. Abhängig von den Ergebnissen des Abbruchvorgangs führt der Treiber die Anforderung mit einer geeigneten status aus, entweder in EvtIoCanceledOnQueue oder höher.
Das Framework ruft die EvtIoCanceledOnQueue-Rückruffunktion des Treibers nicht für E/A-Anforderungen auf, die das Framework nie an den Treiber übermittelt hat.
Das Framework ruft eine EvtIoCanceledOnQueue-Rückruffunktion auf, sobald festgestellt wird, dass eine E/A-Anforderung abgebrochen wurde, unabhängig von der Verteilmethode , die der Treiber für die E/A-Warteschlange festgelegt hat. Daher kann das Framework eine EvtIoCanceledOnQueue-Rückruffunktion für Folgendes aufrufen:
- Eine Anforderung in einer Warteschlange, die die sequenzielle Verteilung verwendet, auch wenn der Treiber derzeit eine andere Anforderung aus der Warteschlange besitzt.
- Eine Anforderung in einer Warteschlange, für die der Treiber NumberOfPresentedRequests festgelegt hat, auch wenn der Treiber derzeit die maximale Anzahl von Anforderungen besitzt.
Die EvtIoCanceledOnQueue-Rückruffunktion kann unter IRQL <= DISPATCH_LEVEL aufgerufen werden, es sei denn, der ExecutionLevel-Member der WDF_OBJECT_ATTRIBUTES-Struktur des Geräts oder Treibers ist auf WdfExecutionLevelPassive festgelegt.
Wenn der IRQL PASSIVE_LEVEL ist, ruft das Framework die Rückruffunktion in einem kritischen Bereich auf.
Beispiele
Um eine EvtIoCanceledOnQueue-Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.
Um eine EvtIoCanceledOnQueue-Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die SDV und andere Überprüfungstools erfordern. Das folgende Beispiel stammt aus dem PCMCIA-Smartcardtreiberbeispiel .
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;
Im PcMCIA-Smartcardtreiberbeispiel verwendet der Treiber eine manuelle Warteschlange, um ausstehende Smart Karte-Benachrichtigungsanforderungen zu speichern. Der Treiber stellt eine EvtIoCanceledOnQueue-Rückruffunktion bereit, in der der Treiber das Benachrichtigungsfeld löscht und die Anforderung abschließt.
_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
WDFQUEUE Queue,
WDFREQUEST Request
)
{
PDEVICE_EXTENSION DeviceExtension;
PSMARTCARD_EXTENSION smartcardExtension;
DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;
//KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));
InterlockedExchangePointer(
&(smartcardExtension->OsData->NotificationIrp),
NULL
);
WdfRequestComplete(Request, STATUS_CANCELLED);
}
Der EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE Funktionstyp ist in der Wdfio.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für KMDF-Treiber. Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.
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") |