Função IoSetCompletionRoutineEx (wdm.h)

Artigo
03/08/2023

A rotina IoSetCompletionRoutineEx registra uma rotina IoCompletion , que é chamada quando o driver de nível inferior seguinte conclui a operação solicitada para o IRP especificado.

Sintaxe

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
);

Parâmetros

[in] DeviceObject

Ponteiro para o objeto de dispositivo do driver.

[in] Irp

Ponteiro para o IRP que o driver está processando.

[in] CompletionRoutine

Especifica o ponto de entrada para a rotina IoCompletion fornecida pelo driver, que é chamada quando o driver inferior seguinte conclui o pacote.

[in, optional] Context

Ponteiro para um contexto determinado pelo driver a ser passado para a rotina IoCompletion . As informações de contexto devem ser armazenadas na memória nãopagada, pois a rotina IoCompletion é chamada em IRQL <= DISPATCH_LEVEL.

[in] InvokeOnSuccess

Especifica se a rotina de conclusão será chamada se o IRP for concluído com um valor de status de êxito na estrutura de IO_STATUS_BLOCK do IRP, com base nos resultados da macro NT_SUCCESS (consulte Usando valores NTSTATUS).

[in] InvokeOnError

Especifica se a rotina de conclusão será chamada se o IRP for concluído com um valor de status não êxito na estrutura de IO_STATUS_BLOCK do IRP.

[in] InvokeOnCancel

Especifica se a rotina de conclusão será chamada se um driver ou o kernel tiver chamado IoCancelIrp para cancelar o IRP.

Retornar valor

Essa rotina retorna STATUS_SUCCESS em caso de êxito ou STATUS_INSUFFICIENT_RESOURCES se a memória insuficiente estiver disponível para a operação.

Comentários

Ao contrário de IoSetCompletionRoutine, a rotina IoSetCompletionRoutineEx retorna um valor NTSTATUS. O driver deve marcar esse valor para determinar se a rotina IoCompletion foi registrada com êxito. Se a rotina IoCompletion for registrada com êxito, IoSetCompletionRoutineEx alocará memória que permanece alocada até que a rotina IoCompletion seja executada. Os drivers devem garantir que sua rotina IoCompletion seja executada chamando IoCallDriver; caso contrário, o kernel vai vazar memória.

A rotina IoCompletion deve pertencer ao driver que possui o objeto de dispositivo apontado por DeviceObject. Esse requisito impede que a rotina IoCompletion seja descarregada antes de retornar.

O comportamento de IoSetCompletionRoutineEx é o mesmo que a rotina IoSetCompletionRoutine , exceto que:

IoSetCompletionRoutineEx garante que um driver não Plug and Play não seja descarregado antes da execução da rotina IoCompletion.
IoSetCompletionRoutineEx é uma rotina que retorna um valor NTSTATUS.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Regras de conformidade da DDI	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), 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)