IoSetCompletionRoutineEx-Funktion (wdm.h)
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.