Função IoSetCompletionRoutine (wdm.h)

Artigo
02/27/2024

A rotina IoSetCompletionRoutine registra uma rotina IoCompletion , que será chamada quando o próximo driver de nível inferior concluir a operação solicitada para o IRP especificado.

Sintaxe

void IoSetCompletionRoutine(
  [in]           PIRP                   Irp,
  [in, optional] PIO_COMPLETION_ROUTINE CompletionRoutine,
  [in, optional] __drv_aliasesMem PVOID Context,
  [in]           BOOLEAN                InvokeOnSuccess,
  [in]           BOOLEAN                InvokeOnError,
  [in]           BOOLEAN                InvokeOnCancel
);

Parâmetros

[in] Irp

Ponteiro para o IRP que o driver está processando.

[in, optional] 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 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 não êxito status na estrutura IO_STATUS_BLOCK do IRP.

[in] InvokeOnCancel

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

Retornar valor

Nenhum

Comentários

Somente um driver que possa garantir que ele não será descarregado antes que sua rotina de conclusão seja concluída pode usar IoSetCompletionRoutine. Caso contrário, o driver deve usar IoSetCompletionRoutineEx, o que impede que o driver descarregue até que sua rotina de conclusão seja executada.

Essa rotina define o endereço de transferência da rotina IoCompletion no IRP especificado. O driver de nível mais baixo em uma cadeia de drivers em camadas não pode chamar essa rotina.

IoSetCompletionRoutine registra a rotina especificada a ser chamada quando o próximo driver de nível inferior concluir a operação solicitada de qualquer uma ou todas as seguintes maneiras:

Com um valor status de êxito
Com um valor de status não êxito
Cancelando o IRP

Normalmente, o bloco status de E/S é definido pelo driver de dispositivo subjacente. Ele é lido, mas não alterado por rotinas de IoCompletion de drivers de nível superior.

Drivers de nível superior que alocam IRP com IoAllocateIrp ou IoBuildAsynchronousFsdRequest devem chamar essa rotina com todos os parâmetros InvokeOnXxx definidos como TRUE antes de passar o IRP alocado pelo driver para IoCallDriver. Quando a rotina IoCompletion é chamada com esse IRP, ela deve liberar o IRP alocado pelo driver e quaisquer outros recursos que o driver configurou para a solicitação, como MDLs com IoBuildPartialMdl. Esse driver deve retornar STATUS_MORE_PROCESSING_REQUIRED quando chamar IoFreeIrp para evitar todo o processamento de conclusão do gerente de E/S para o IRP alocado pelo driver.

Drivers não PnP que podem ser descarregados antes da execução das rotinas IoCompletion devem usar IoSetCompletionRoutineEx .

Requisitos

Requisito	Valor
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	IRQL <= DISPATCH_LEVEL
Regras de conformidade de DDI	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoFreeIrp(storport), IoSetCompletionRoutineNonPnpDriver(wdm), LowerDriverReturn(wdm), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequest(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait(wdm), StartDeviceWait3(wdm)