IoSetCancelRoutine-Funktion (wdm.h)

  • Artikel

Die IoSetCancelRoutine-Routine richtet eine vom Treiber bereitgestellte Cancel-Routine ein, die aufgerufen wird, wenn eine bestimmte IRP abgebrochen wird.

Syntax

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

Parameter

[in] Irp

Zeiger auf das IRP, das in einen abbrechbaren Zustand versetzt oder aus diesem entfernt wird.

[in] CancelRoutine

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

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

Rückgabewert

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

Hinweise

Diese Routine kann die derzeit in einem IRP festgelegte Cancel-Routine deaktivieren.

Ein Treiber muss die Systemabbruchsperre beim Aufrufen dieser Routine halten, wenn der Treiber die vom E/A-Manager bereitgestellte Gerätewarteschlange im Geräteobjekt verwendet. Der Treiber wird bei IRQL = DISPATCH_LEVEL ausgeführt, nachdem IoAcquireCancelSpinLock aufgerufen wurde, bis er die Drehsperre mit IoReleaseCancelSpinLock aufbricht.

Wenn der Treiber seine eigenen Warteschlangen von IRPs verwaltet, muss der Treiber beim Aufrufen dieser Routine nicht die Abbruch-Spin-Sperre halten. IoSetCancelRoutine verwendet einen intrinsischen Austausch, um die Adresse der Cancel-Routine als atomaren Vorgang festzulegen. Eine geringere Nutzung der Drehsperre kann die Treiberleistung und die Gesamtleistung des Systems verbessern.

Driver Cancel-Routinen werden unter IRQL = DISPATCH_LEVEL aufgerufen, wobei die Abbruchdrehsperre gehalten wird. Die Cancel-Routine muss die Abbruch-Drehsperre freigeben, bevor sie die Steuerung zurückgibt.

Anforderungen

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

Weitere Informationen

IoAcquireCancelSpinLock

IoReleaseCancelSpinLock