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
)
{...}
Die Parameter
[in] Queue
Ein Handle zu einem E/A-Warteschlangenobjekt.
[in] Request
Ein Handle zu einem Anforderungsobjekt.
Rückgabewert
Nichts
Bemerkungen
Ein Treiber registriert eine EvtIoCanceledOnQueue Rückruffunktion, wenn die WdfIoQueueCreate-Methode aufgerufen wird. Weitere Informationen zum Aufrufen WdfIoQueueCreatefinden 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 eine E/A-Anforderung von einer E/A-Warteschlange empfängt, der Treiber ruft WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueue, oder WdfRequestRequeue erneut die Anforderung an die E/A-Warteschlange zurück, für die die EvtIoCanceledOnQueue Rückruffunktion registriert ist, und der zugeordnete E/A-Vorgang wird anschließend abgebrochen.
- Die EvtIoInCallerContext Rückruffunktion des Treibers empfängt eine E/A-Anforderung, der Treiber ruft WdfDeviceEnqueueRequest, um die Anforderung an das Framework zurückzugeben, platziert das Framework dann die Anforderung in der E/A-Warteschlange, für die die EvtIoCanceledOnQueue Rückruffunktion registriert ist, und anschließend der zugeordnete E/A-Vorgang abgebrochen wird.
In der Regel schließt der Treiber in EvtIoCanceledOnQueuedie E/A-Anforderung mit dem Abschlussstatus STATUS_CANCELLED ab.
In einigen Fällen hat der Treiber möglicherweise zuvor eine E/A-Anforderung in eine manuelle Warteschlange zurückgefragt, vielleicht um auf Informationen zu warten. Beispielsweise kann ein Treiber in einem seiner Anforderungshandlereine E/A-Anforderung platzieren, die einer ausstehenden DMA-Transaktion in einer manuellen Warteschlange zugeordnet ist. In diesem Fall versucht der Treiber, die DMA-Transaktion in seinem EvtIoCanceledOnQueue Rückruf abzubrechen. Abhängig von den Ergebnissen des Abbruchvorgangs schließt der Treiber die Anforderung mit einem geeigneten Status ab, entweder in EvtIoCanceledOnQueue oder höher.
Das Framework ruft nicht die EvtIoCanceledOnQueue Rückruffunktion 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 Dispatching-Methode, die der Treiber für die E/A-Warteschlange festgelegt hat. Daher kann das Framework eine EvtIoCanceledOnQueue Rückruffunktion aufrufen für:
- Eine Anforderung in einer Warteschlange, die sequenzielle Verteilerverwendet, auch wenn der Treiber derzeit eine andere Anforderung aus der Warteschlange besitzt.
- Eine Anforderung in einer Warteschlange, für die der Treiber NumberOfPresentedRequestsfestgelegt hat, auch wenn der Treiber derzeit die maximale Anzahl von Anforderungen besitzt.
Die EvtIoCanceledOnQueue- Rückruffunktion kann bei IRQL <= DISPATCH_LEVEL aufgerufen werden, es sei denn, das ExecutionLevel Member der WDF_OBJECT_ATTRIBUTES Struktur des Geräts oder Treibers wird auf WdfExecutionLevelPassivefestgelegt.
Wenn die IRQL PASSIVE_LEVEL ist, ruft das Framework die Rückruffunktion innerhalb eines kritischen Bereichsauf.
Beispiele
Um eine EvtIoCanceledOnQueue Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückruffunktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.
Um eine EvtIoCanceledOnQueue Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die SDV und andere Überprüfungstools erfordern. Das folgende Beispiel stammt aus dem beispiel PCMCIA SmartCard Driver Beispiel.
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;
Im beispiel PCMCIA Smart Card Driver verwendet der Treiber eine manuelle Warteschlange, um ausstehende Smartcardbenachrichtigungsanforderungen 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 wird in der Headerdatei "Wdfio.h" definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.
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") |