DRIVER_CANCEL Rückruffunktion (wdm.h)

Artikel
03/01/2024

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 von der AddDevice-Routine des Treibers erstellt wurde.

[in, out] Irp

Vom Aufrufer bereitgestellter Zeiger auf eine IRP-Struktur , die den E/A-Vorgang beschreibt, der abgebrochen werden soll.

Rückgabewert

Keine

Bemerkungen

Wenn ein Treiber oder eine andere Systemkomponente IoCancelIrp aufruft, ruft der E/A-Manager die Cancel-Routine des IRP auf, sofern 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 E/A-Manager bereitgestellte Gerätewarteschlange verwendet, kann beim Aufrufen von IoStartPacket eine Cancel-Routine angeben.
Ein Treiber, der zusätzliche Gerätewarteschlangen erstellt und verwaltet, kann eine Cancel-Routine registrieren, indem er IoSetCancelRoutine aufruft.

Es kann nur eine Cancel-Routine gleichzeitig für ein IRP registriert werden.

Der E/A-Manager ruft IoAcquireCancelSpinLock auf, bevor er die Cancel-Routine eines Treibers aufruft, sodass die Cancel-Routineirgendwann IoReleaseCancelSpinLock aufrufen muss. Die Routine sollte die Drehsperre nicht länger als erforderlich halten.

Die Cancel-Routine wird in einem beliebigen Threadkontext unter IRQL = DISPATCH_LEVEL ausgeführt, bis IoReleaseCancelSpinLock aufgerufen wird, wodurch der IRQL in einen vom Aufrufer bereitgestellten Wert geändert wird. Der Treiber sollte Irp-CancelIrql> für diesen Wert angeben.

Die Cancel-Routine muss den Status-Member des E/A-status-Blocks auf STATUS_CANCELLED und dessen Information-Member auf 0 (null) festlegen. Die Routine muss dann den angegebenen IRP durch Aufrufen von IoCompleteRequest abschließen.

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

Beispiele

Um eine Rückrufroutine abzubrechen zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine 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 beispielsweise eine Rückrufroutine mit dem Namen MyCancelCancel zu definieren, verwenden Sie den typ DRIVER_CANCEL, 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 ist in der Wdm.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den DRIVER_CANCEL 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 WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Wird bei DISPATCH_LEVEL aufgerufen (siehe Abschnitt "Hinweise").

Freigeben über