Функция IoSetCompletionRoutineEx (wdm.h)
Подпрограмма IoSetCompletionRoutineEx регистрирует подпрограмму IoCompletion , которая вызывается, когда драйвер следующего уровня завершает запрошенную операцию для заданного IRP.
Синтаксис
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
);
Параметры
[in] DeviceObject
Указатель на объект устройства драйвера.
[in] Irp
Указатель на IRP , обрабатываемый драйвером.
[in] CompletionRoutine
Указывает точку входа для предоставленной драйвером процедуры IoCompletion , которая вызывается, когда следующий драйвер завершает пакет.
[in, optional] Context
Указатель на определенный драйвером контекст для передачи в подпрограмму IoCompletion . Сведения о контексте должны храниться в памяти без памяти, так как подпрограмма IoCompletion вызывается в IRQL <= DISPATCH_LEVEL.
[in] InvokeOnSuccess
Указывает, вызывается ли подпрограмма завершения, если IRP завершается со значением состояния успешного выполнения в структуре IO_STATUS_BLOCK IRP на основе результатов макроса NT_SUCCESS (см. раздел Использование значений NTSTATUS).
[in] InvokeOnError
Указывает, вызывается ли подпрограмма завершения, если IRP завершена со значением состояния nonsuccess в структуре IRP IO_STATUS_BLOCK .
[in] InvokeOnCancel
Указывает, вызывается ли подпрограмма завершения, если драйвер или ядро вызывает IoCancelIrp для отмены IRP.
Возвращаемое значение
Эта подпрограмма возвращает STATUS_SUCCESS при успешном выполнении или STATUS_INSUFFICIENT_RESOURCES, если для операции недостаточно памяти.
Комментарии
В отличие от IoSetCompletionRoutine, подпрограмма IoSetCompletionRoutineEx возвращает значение NTSTATUS. Драйвер должен проверка это значение, чтобы определить, была ли подпрограмма IoCompletion успешно зарегистрирована. Если подпрограмма IoCompletion успешно зарегистрирована, IoSetCompletionRoutineEx выделяет память, которая остается выделенной до выполнения процедуры IoCompletion . Драйверы должны убедиться, что их подпрограмма IoCompletion выполняется путем вызова IoCallDriver; в противном случае ядро будет утечь память.
Подпрограмма IoCompletion должна принадлежать драйверу, которому принадлежит объект устройства, на который указывает DeviceObject. Это требование предотвращает выгрузку подпрограммы IoCompletion до ее возврата.
Поведение IoSetCompletionRoutineEx аналогично процедуре IoSetCompletionRoutine , за исключением того, что:
IoSetCompletionRoutineEx гарантирует, что драйвер, отличный от Plug and Play, не будет выгружен до запуска процедуры IoCompletion.
IoSetCompletionRoutineEx — это подпрограмма, которая возвращает значение NTSTATUS.