PFLT_INSTANCE_TEARDOWN_CALLBACK função de retorno de chamada (fltkernel.h)

Artigo
08/07/2023

Um driver de minifiltro pode registrar duas rotinas do tipo PFLT_INSTANCE_TEARDOWN_CALLBACK como as rotinas InstanceTeardownStartCallback e InstanceTeardownCompleteCallback do driver de minifiltro.

Sintaxe

PFLT_INSTANCE_TEARDOWN_CALLBACK PfltInstanceTeardownCallback;

void PfltInstanceTeardownCallback(
  [in] PCFLT_RELATED_OBJECTS FltObjects,
  [in] FLT_INSTANCE_TEARDOWN_FLAGS Reason
)
{...}

Parâmetros

[in] FltObjects

Ponteiro para uma estrutura FLT_RELATED_OBJECTS que contém ponteiros opacos para os objetos relacionados à operação de E/S atual.

[in] Reason

Sinalizador que indica por que a instância do driver de minifiltro está sendo interrompida. Um dos seguintes:

Sinalizador	Significado
FLTFL_INSTANCE_TEARDOWN_MANUAL (0x00000001)	A instância está sendo desanexada porque um aplicativo de modo de usuário chamou FilterDetach ou um componente de modo kernel chamado FltDetachVolume.
FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD (0x00000002)	O driver de minifiltro está sendo descarregado.
FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD (0x00000004)	O driver de minifiltro está sendo descarregado.
FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT (0x00000008)	Se definido, o volume está sendo desmontado. (Ou o volume já foi desmontado. Ou a operação de montagem de volume falhou. Ou a instância do driver de minifiltro ou o volume está sendo derrubado. Ou o sistema de arquivos cancelou o registro como um sistema de arquivos ativo.)
FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR (0x00000010)	O sistema sofreu um erro interno inesperado.

Retornar valor

Nenhum

Comentários

Quando um driver de minifiltro se registra chamando FltRegisterFilter de sua rotina DriverEntry , ele pode registrar duas rotinas do tipo PFLT_INSTANCE_TEARDOWN_CALLBACK como as rotinas InstanceTeardownStartCallback e InstanceTeardownCompleteCallback do driver de minifiltro. Para registrar essas rotinas de retorno de chamada, o driver de minifiltro armazena os endereços das duas rotinas do tipo PFLT_INSTANCE_TEARDOWN_CALLBACK nos membros InstanceTeardownStartCallback e InstanceTeardownCompleteCallback da estrutura FLT_REGISTRATION que o driver de minifiltro passa como o parâmetro Registration de FltRegisterFilter.

As rotinas InstanceTeardownStartCallback e InstanceTeardownCompleteCallback são opcionais e podem ser NULL. Se o driver de minifiltro especificar NULL para a rotina InstanceTeardownStartCallback ou InstanceTeardownCompleteCallback , a instância ainda será interrompida.

A rotina InstanceTeardownStartCallback é chamada quando o gerenciador de filtros começa a remover uma instância de driver de minifiltro para permitir que o driver de minifiltro conclua as operações de E/S pendentes e salve as informações de estado.

A rotina InstanceTeardownStartCallback deve:

Chame FltCompletePendedPreOperation para cada operação de E/S pendente na rotina de retorno de chamada de pré-operação do driver de minifiltro para concluir a operação ou retornar o controle da operação para o gerenciador de filtros.
Não pendente nenhuma nova operação de E/S. Se o driver de minifiltro usar uma fila de dados de retorno de chamada, ele deverá chamar FltCbdqDisable para desabilitá-lo.
Chame FltCompletePendedPostOperation para cada operação de E/S pendente na rotina de retorno de chamada postoperation do driver de minifiltro para retornar o controle da operação para o gerenciador de filtros.

Opcionalmente, a rotina InstanceTeardownStartCallback pode fazer o seguinte para permitir que o driver de minifiltro seja descarregado o mais rápido possível:

Feche todos os arquivos abertos.
Verifique se os threads de trabalho executam apenas o mínimo necessário para concluir o processamento de itens de trabalho pendentes.
Chame FltCancelIo para cancelar todas as operações de E/S iniciadas pelo driver de minifiltro.
Pare de enfileirar novos itens de trabalho.

Depois que a rotina InstanceTeardownStartCallback do driver de minifiltro for chamada, as rotinas de retorno de chamada de pré-operação e de operação do minifiltro não serão chamadas para novas operações de E/S. No entanto, eles podem ser chamados para operações de E/S que foram iniciadas antes do início da remoção da instância.

A rotina InstanceTeardownCompleteCallback é chamada quando o processo de desativação é concluído para permitir que o driver de minifiltro feche arquivos abertos e execute qualquer outro processamento de limpeza necessário.

A rotina InstanceTeardownCompleteCallback deve fechar todos os arquivos que foram abertos pelo driver de minifiltro.

O gerenciador de filtros chama a rotina InstanceTeardownCompleteCallback do driver de minifiltro somente depois que todas as operações de E/S pendentes tiverem sido concluídas ou drenadas.

Aviso

A rotina InstanceTeardownCompleteCallback não será chamada se qualquer uma das seguintes condições for verdadeira:

Há operações pendentes de E/S pendentes.
Há quaisquer operações de E/S pendentes que foram iniciadas pelo driver de minifiltro.

Se a instância do driver de minifiltro estiver sendo interrompida porque o driver de minifiltro está sendo descarregado, a operação de descarregamento parecerá travar até que a rotina InstanceTeardownCompleteCallback retorne. Para depurar esses tipos de problemas, você deve habilitar o Verificador de Driver no driver de minifiltro. A opção Verificação de E/S do Verificador de Filtro pode ajudar a identificar possíveis causas, como referências não lançadas, que impediriam o descarregamento do driver de minifiltro. Para obter mais informações, consulte Verificador de Filtro.

Observe que referenciar a instância (chamando FltObjectReference) não impede que a rotina InstanceTeardownCompleteCallback seja chamada.

O gerenciador de filtros chama as rotinas InstanceTeardownStartCallback e InstanceTeardownCompleteCallback no IRQL PASSIVE_LEVEL.