EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE Rückruffunktion (wdfio.h)

  • Artikel

[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:

Nachdem das Framework die Rückruffunktion EvtIoCanceledOnQueue aufgerufen hat, besitzt der Treiber das Anforderungsobjekt und muss die Anforderung mit einem entsprechenden status Code abschließen, entweder in EvtIoCanceledOnQueue oder höher. Wenn das Framework EvtIoCanceledOnQueue aufruft, ist die Anforderung weiterhin der E/A-Warteschlange zugeordnet, aber der Treiber kann die Anforderung nicht erneut in die Warteschlange stellen. Der Besitz der Anforderung bleibt beim Treiber, auch wenn der Treiber die Anforderung in EvtIoCanceledOnQueue nicht abschließt. Wenn der Treiber die Anforderung nach der Rückgabe von EvtIoCanceledOnQueue abgeschlossen hat, können er WdfIoQueueFindRequest und WdfIoQueueRetrieveFoundRequest nicht aufrufen, um den Besitz der Anforderung erneut zu erhalten, da der Treiber bereits über den Besitz der Anforderung verfügt.

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.
Weitere Informationen zur Rückruffunktion EvtIoCanceledOnQueue finden Sie unter Abbrechen von E/A-Anforderungen.

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")

Weitere Informationen

WdfIoQueueErstellen

WdfRequestForwardToIoQueue