EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE Rückruffunktion (wdfio.h)

[Gilt für KMDF und UMDF]

Die Ereignisrückruffunktion eines Treibers EvtIoCanceledOnQueue informiert den Treiber, 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 zu einem I/O-Warteschlangenobjekt.

[in] Request

Ein Handle zu einem Anforderungsobjekt.

Rückgabewert

Keine

Bemerkungen

Ein Treiber registriert eine EvtIoCanceledOnQueue-Rückruffunktion , wenn sie die WdfIoQueueCreate-Methode aufruft . Weitere Informationen zum Aufrufen von WdfIoQueueCreate finden Sie unter Erstellen von I/O-Warteschlangen.

Wenn ein Treiber eine EvtIoCanceledOnQueue-Rückruffunktion für eine I/O-Warteschlange registriert, ruft das Framework die Rückruffunktion in den folgenden Situationen auf:

Nachdem das Framework die EvtIoCanceledOnQueue-Rückruffunktion aufgerufen hat, besitzt der Treiber das Anforderungsobjektund muss die Anforderung mit einem entsprechenden Statuscode abschließen, entweder in EvtIoCanceledOnQueue oder höher. Wenn das Framework EvtIoCanceledOnQueue aufruft, ist die Anforderung weiterhin der I/O-Warteschlange zugeordnet, aber der Treiber kann die Anforderung nicht erneut anfordern. Der Besitz der Anforderung verbleibt bei dem Fahrer, auch wenn der Fahrer die Anforderung in EvtIoCanceledOnQueue nicht abgeschlossen hat. Wenn der Treiber die Anforderung abgeschlossen hat, nachdem EvtIoCanceledOnQueue zurückgegeben wurde , kann er WdfIoQueueFindRequest und WdfIoQueueRetrieveFoundRequest nicht aufrufen, um den Besitz der Anforderung erneut zu erhalten, da der Treiber bereits Besitz der Anforderung hat.

In der Regel schließt der Treiber in EvtIoCanceledOnQueuedie I/O-Anforderung mit einem Abschlussstatus von STATUS_CANCELLED ab.

In einigen Fällen hat der Treiber möglicherweise zuvor eine E/A-Anforderung an eine manuelle Warteschlange zurückgefragt, vielleicht um auf Informationen zu warten. Beispielsweise kann ein Treiber in einem seiner Anforderungshandler eine 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. Je nach 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 I/O-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 Verteilermethode , 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 Verteiler 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 EvtIoCanceledOnQueue-Rückruffunktion finden Sie unter Abbrechen von I/O-Anforderungen.

Die Rückruffunktion EvtIoCanceledOnQueue kann bei 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.

Wenn die IRQL PASSIVE_LEVEL ist, ruft das Framework die Rückruffunktion innerhalb eines kritischen Bereichs auf.

Beispiele

Um eine EvtIoCanceledOnQueue-Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückruffunktion identifiziert. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und anderen Überprüfungstools, Fehler zu 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 PCMCIA SmartCard Driver-Beispiel .

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;

Im PCMCIA SmartCard Driver-Beispiel 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 abgeschlossen.

_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 Wdfio.h-Headerdatei 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_annotations finden Sie unter Annotating Function Behavior.

Anforderungen

   
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Header wdfio.h (include Wdf.h)
IRQL <= DISPATCH_LEVEL (siehe Abschnitt "Hinweise")

Siehe auch

WdfIoQueueCreate

WdfRequestForwardToIoQueue