IoSetCompletionRoutineEx-Funktion (wdm.h)

Artikel
02/27/2024

Die IoSetCompletionRoutineEx-Routine registriert eine IoCompletion-Routine , die aufgerufen wird, wenn der Treiber der nächstniedrigen Ebene den angeforderten Vorgang für den angegebenen IRP abgeschlossen hat.

Syntax

NTSTATUS IoSetCompletionRoutineEx(
  [in]           PDEVICE_OBJECT         DeviceObject,
  [in]           PIRP                   Irp,
  [in]           PIO_COMPLETION_ROUTINE CompletionRoutine,
  [in, optional] PVOID                  Context,
  [in]           BOOLEAN                InvokeOnSuccess,
  [in]           BOOLEAN                InvokeOnError,
  [in]           BOOLEAN                InvokeOnCancel
);

Parameter

[in] DeviceObject

Zeiger auf das Geräteobjekt des Treibers.

[in] Irp

Zeiger auf den IRP , den der Treiber verarbeitet.

[in] CompletionRoutine

Gibt den Einstiegspunkt für die vom Treiber bereitgestellte IoCompletion-Routine an, die aufgerufen wird, wenn der nächstniedrige Treiber das Paket abschließt.

[in, optional] Context

Zeiger auf einen vom Treiber bestimmten Kontext, der an die IoCompletion-Routine übergeben werden soll. Kontextinformationen müssen im nicht ausgelagerten Arbeitsspeicher gespeichert werden, da die IoCompletion-Routine unter IRQL <= DISPATCH_LEVEL aufgerufen wird.

[in] InvokeOnSuccess

Gibt an, ob die Vervollständigungsroutine aufgerufen wird, wenn die IRP mit einem erfolgreichen status Wert in der IO_STATUS_BLOCK-Struktur des IRP abgeschlossen wird, basierend auf den Ergebnissen des NT_SUCCESS-Makros (siehe Verwenden von NTSTATUS-Werten).

[in] InvokeOnError

Gibt an, ob die Vervollständigungsroutine aufgerufen wird, wenn das IRP mit einem nicht erfolgreichen status-Wert in der IO_STATUS_BLOCK-Struktur des IRP abgeschlossen wird.

[in] InvokeOnCancel

Gibt an, ob die Vervollständigungsroutine aufgerufen wird, wenn ein Treiber oder der Kernel IoCancelIrp aufgerufen hat, um das IRP abzubrechen.

Rückgabewert

Diese Routine gibt bei Erfolg STATUS_SUCCESS oder STATUS_INSUFFICIENT_RESOURCES zurück, wenn nicht genügend Arbeitsspeicher für den Vorgang verfügbar ist.

Hinweise

Im Gegensatz zu IoSetCompletionRoutine gibt die IoSetCompletionRoutineEx-Routine einen NTSTATUS-Wert zurück. Der Treiber muss diesen Wert überprüfen, um festzustellen, ob die IoCompletion-Routine erfolgreich registriert wurde. Wenn die IoCompletion-Routine erfolgreich registriert wurde, ordnet IoSetCompletionRoutineEx Arbeitsspeicher zu, der zugeordnet bleibt, bis die IoCompletion-Routine ausgeführt wird. Treiber müssen sicherstellen, dass ihre IoCompletion-Routine ausgeführt wird, indem sie IoCallDriver aufrufen. Andernfalls wird der Kernel arbeitsspeicherverlusten.

Die IoCompletion-Routine muss zu dem Treiber gehören, dem das Geräteobjekt gehört, auf das von DeviceObject verwiesen wird. Diese Anforderung verhindert, dass die IoCompletion-Routine entladen wird, bevor sie zurückgegeben wird.

Das Verhalten von IoSetCompletionRoutineEx ist identisch mit der IoSetCompletionRoutine-Routine , mit der Ausnahme:

IoSetCompletionRoutineEx garantiert, dass ein Nicht-Plug & Play Treiber nicht entladen wird, bevor die IoCompletion-Routine ausgeführt wird.
IoSetCompletionRoutineEx ist eine Routine, die einen NTSTATUS-Wert zurückgibt.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), HwStorPortProhibitedDIs(storport), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoSetCompletionExCompleteIrp(wdm), IoSetCompletionRoutineExCheck(wdm), IoSetCompletionRoutineCheckDeviceObject(wdm), LowerDriverReturn(wdm), MarkPower(wdm), MarkPowerDown(wdm) , MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequestEx(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait2(wdm), StartDeviceWait4(wdm)