Função IoSetCompletionRoutine (wdm.h)
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 .