Функция IoSetCompletionRoutineEx (wdm.h)

Статья
03/08/2023

Подпрограмма 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.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), HwStorPortProhibitedDDIs(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), IoSetCompletionRoutineExCheckDeviceObject(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)