IoSetCancelRoutine-Funktion (wdm.h)

Artikel
07.02.2025

Die IoSetCancelRoutine Routine richtet eine vom Treiber bereitgestellte Cancel Routine ein, die aufgerufen werden soll, wenn ein bestimmter IRP abgebrochen wird.

Syntax

C++

PDRIVER_CANCEL IoSetCancelRoutine(
  [in] PIRP           Irp,
  [in] PDRIVER_CANCEL CancelRoutine
);

Parameter

[in] Irp

Zeiger auf das IRP, das in einen abbruchbaren Zustand versetzt oder entfernt wird.

[in] CancelRoutine

Gibt den Einstiegspunkt der vom Aufrufer bereitgestellten Cancel Routine an, die aufgerufen werden soll, wenn das angegebene IRP abgebrochen wird oder NULL- ist, wenn der angegebene IRP aus dem abbruchfähigen Zustand entfernt wird. Diese Routine wird wie folgt deklariert:

C++

VOID
(*PDRIVER_CANCEL)(
    IN PDEVICE_OBJECT DeviceObject,
    IN PIRP Irp
    );

Rückgabewert

IoSetCancelRoutine gibt den vorherigen Wert von Irp->CancelRoutinezurück. Wenn zuvor keine Cancel Routine festgelegt wurde oder wenn der IRP-Abbruch bereits ausgeführt wird, gibt IoSetCancelRoutineNULL-zurück.

Bemerkungen

Diese Routine kann die Cancel Routine deaktivieren, die derzeit in einem IRP festgelegt ist.

Ein Treiber muss die Drehungssperre des Systems beim Aufrufen dieser Routine enthalten, wenn der Treiber die vom I/O-Manager bereitgestellte Gerätewarteschlange im Geräteobjekt verwendet. Der Treiber wird bei IRQL = DISPATCH_LEVEL nach dem Aufrufen von IoAcquireCancelSpinLock ausgeführt, bis die Abbruchspinsperre mit IoReleaseCancelSpinLockloslässt.

Wenn der Treiber seine eigenen IRPs-Warteschlangen verwaltet, muss der Treiber beim Aufrufen dieser Routine nicht die Abbruchspinsperre halten. IoSetCancelRoutine verwendet einen systeminternen Interlocked Exchange, um die Adresse der Cancel Routine als atomischen Vorgang festzulegen. Eine reduzierte Nutzung der Drehsperre für das Abbrechen kann die Treiberleistung und die Gesamtsystemleistung verbessern.

Driver Cancel Routinen werden bei IRQL = DISPATCH_LEVEL mit gehaltener Drehsperre aufgerufen. Die Cancel Routine muss die Drehungssperre freigeben, bevor sie die Steuerung zurückgibt.

Anforderungen

Anforderung	Wert
Zielplattform-	Desktop
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	DISPATCH_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	IrpCancelField(wdm), StartIoCancel(wdm)

Siehe auch

IoAcquireCancelSpinLock

IoReleaseCancelSpinLock

Teilen über