DRIVER_CANCEL Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die Cancel Routine bricht einen E/A-Vorgang ab.

Syntax

DRIVER_CANCEL DriverCancel;

void DriverCancel(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Parameter

[in, out] DeviceObject

Vom Aufrufer bereitgestellter Zeiger auf eine DEVICE_OBJECT Struktur. Dies ist das Geräteobjekt für das Zielgerät, das zuvor vom AddDevice Routine des Treibers erstellt wurde.

[in, out] Irp

Vom Aufrufer bereitgestellter Zeiger auf eine IRP- Struktur, die den zu abbrechenden E/A-Vorgang beschreibt.

Rückgabewert

Nichts

Bemerkungen

Wenn ein Treiber oder eine andere Systemkomponente IoCancelIrp-aufruft, ruft der IRP-Manager die Cancel Routine des IRP auf, wenn eine für das IRP registriert wurde.

Um eine Cancel Routine für ein IRP zu registrieren, kann ein Treiber eine der folgenden beiden Methoden verwenden:

Ein Treiber, der eine StartIo- Routine bereitstellt und die vom I/O-Manager bereitgestellte Gerätewarteschlange verwendet, kann eine Cancel Routine angeben, wenn IoStartPacketaufgerufen wird.
Ein Treiber, der zusätzliche Gerätewarteschlangen erstellt und verwaltet, kann eine Cancel Routine registrieren, indem IoSetCancelRoutineaufgerufen wird.

Nur eine Cancel Routine kann gleichzeitig für ein IRP registriert werden.

Der E/A-Manager ruft IoAcquireCancelSpinLock- auf, bevor die Cancel-Routine eines Treibers aufgerufen wird, sodass die Cancel Routine IoReleaseCancelSpinLock zu einem bestimmten Zeitpunkt aufrufen muss. Die Routine sollte die Drehsperre nicht länger als nötig halten.

Die Cancel Routine wird in einem beliebigen Threadkontext bei IRQL = DISPATCH_LEVEL ausgeführt, bis sie IoReleaseCancelSpinLockaufruft, wodurch die IRQL in einen von einem Aufrufer bereitgestellten Wert geändert wird. Der Treiber sollte Irp->CancelIrql- für diesen Wert angeben.

Die Cancel Routine muss die Status- Mitglied des E/A-Statusblocks auf STATUS_CANCELLED festlegen und dessen Information Mitglied auf Null festlegen. Die Routine muss dann das angegebene IRP abschließen, indem IoCompleteRequestaufgerufen wird.

Ausführliche Informationen zum Implementieren der Cancel Routine eines Treibers finden Sie unter Canceling IRPs.

Beispiele

Um eine Cancel Callbackroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. 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 beispielsweise eine Cancel Callbackroutine zu definieren, die MyCancelgenannt wird, verwenden Sie den DRIVER_CANCEL Typ, wie in diesem Codebeispiel gezeigt:

DRIVER_CANCEL MyCancel;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
VOID
  MyCancel(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

Der DRIVER_CANCEL Funktionstyp wird in der Wdm.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 DRIVER_CANCEL Funktionstyp 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 WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Zielplattform-	Desktop
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL-	Aufgerufen bei DISPATCH_LEVEL (siehe Abschnitt "Hinweise").

Freigeben über