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