Diretrizes para portabilidade de drivers de filtro herdados

Os desenvolvedores são incentivados a portar drivers de filtro herdados para o modelo do gerenciador de filtros para obter melhor funcionalidade para seus drivers de filtro e melhorar a confiabilidade do sistema. Os desenvolvedores experientes devem achar relativamente fácil portar um driver de filtro herdado para um driver de minifiltro. Os desenvolvedores de driver de filtro na Microsoft recomendam a seguinte abordagem:

• Comece com um conjunto de testes de regressão confiável para verificar o comportamento entre o driver de filtro herdado e o driver de minifiltro portado.

• Crie um shell de driver de minifiltro e mova sistematicamente a funcionalidade do driver de filtro herdado para o driver de minifiltro. Por exemplo, faça com que o anexo funcione e, em seguida, faça a portabilidade de uma operação por vez, testando após cada operação.

• Altere a comunicação do modo de usuário/kernel por último, para que você possa usar as ferramentas existentes para testar o driver de minifiltro.

• Compile com PREfast e teste com a opção de verificação de E/S do Verificador de Filtro no Verificador de Driver habilitada.

Durante o processo de portabilidade, você deve examinar todo o código do driver de filtro herdado para aproveitar ao máximo os recursos do gerenciador de filtros. Em particular, tenha o seguinte em mente:

• As operações de E/S baseadas em IRP e E/S rápidas podem passar pela mesma operação quando apropriado, o que ajuda a reduzir a duplicação de código.

• Ao registrar-se para operações, um driver de minifiltro pode optar explicitamente por ignorar todas as E/S de paginação e E/S armazenadas em cache, o que elimina a necessidade de código marcar-las.

• As notificações de instância simplificam muito a lógica de anexação/desanexação.

• Registre-se somente para operações que o driver de minifiltro deve manipular; você pode ignorar todo o resto.

• Aproveite o contexto do gerenciador de filtros e o suporte ao gerenciamento de nomes.

• Aproveite o suporte do gerenciador de filtros para emitir E/S não recursiva.

• Ao contrário dos drivers de filtro herdados, os drivers de minifiltro não podem contar com variáveis locais para manter o contexto desde o processamento de pré-operação até o processamento de postoperation. Considere alocar uma lista lookaside para armazenar o estado da operação.

• Certifique-se de liberar referências quando terminar com um nome ou contexto.

• As portas de conclusão no modo de usuário adicionam uma técnica avançada para criar filas. Você provavelmente precisará de apenas uma única conexão com uma única porta nomeada.

A tabela a seguir lista as operações comuns em um driver de filtro herdado e como elas são mapeadas para o modelo do gerenciador de filtros.

Modelo de driver de filtro herdado	Modelo do gerenciador de filtros
Operação de passagem sem rotina de conclusão	Se o driver de minifiltro nunca funcionar para esse tipo de operação de E/S, não registre uma rotina de retorno de chamada de pré-operação ou postoperation para esta operação. Caso contrário, retorne FLT_PREOP_SUCCESS_NO_CALLBACK da rotina de retorno de chamada de pré-operação registrada para essa operação. Consulte Retornando FLT_PREOP_SUCCESS_NO_CALLBACK.
Operação de passagem com uma rotina de conclusão	Retorne FLT_PREOP_SUCCESS_WITH_CALLBACK da rotina de retorno de chamada de pré-operação. Consulte Retornando FLT_PREOP_SUCCESS_WITH_CALLBACK.
Operação pendente na rotina de retorno de chamada de pré-operação	Chame FltLockUserBuffer conforme necessário para garantir que todos os buffers de usuário estejam corretamente bloqueados para que possam ser acessados em um thread de trabalho. Enfileirar o trabalho para um thread de trabalho chamando rotinas de suporte como FltAllocateDeferredIoWorkItem e FltQueueDeferredIoWorkItem. Retorne FLT_PREOP_PENDING da rotina de retorno de chamada de pré-operação. Quando estiver pronto para retornar a operação de E/S para o gerenciador de filtros, chame FltCompletePendedPreOperation. Consulte Pendente uma operação de E/S em uma rotina de retorno de chamada de pré-operação.
Operação pendente na rotina de retorno de chamada de postoperation	Na rotina de retorno de chamada de pré-operação, chame FltLockUserBuffer para garantir que os buffers de usuário estejam corretamente bloqueados para que possam ser acessados em um thread de trabalho. Enfileirar o trabalho para um thread de trabalho chamando rotinas de suporte como FltAllocateGenericWorkItem e FltQueueGenericWorkItem. Retorne FLT_POSTOP_MORE_PROCESSING_REQUIRED da rotina de retorno de chamada de postoperation. Quando estiver pronto para retornar a operação de E/S para o gerenciador de filtros, chame FltCompletePendedPostOperation. Consulte Pendente uma operação de E/S em uma rotina de retorno de chamada do Postoperation.
Sincronizar a operação	Retorne FLT_PREOP_SYNCHRONIZE da rotina de retorno de chamada de pré-operação. Consulte Retornando FLT_PREOP_SYNCHRONIZE.
Concluir a operação na rotina de retorno de chamada de pré-operação	Defina a operação final status e informações no membro IoStatus da estrutura FLT_CALLBACK_DATA para a operação. Retorne FLT_PREOP_COMPLETE da rotina de retorno de chamada de pré-operação. Confira Como concluir uma operação de E/S em uma rotina de retorno de chamada de pré-operação.
Concluir a operação depois que ela tiver sido pendente na rotina de retorno de chamada de pré-operação	Defina a operação final status e informações no membro IoStatus da estrutura FLT_CALLBACK_DATA para a operação. Chame FltCompletePendedPreOperation do thread de trabalho que processa a operação de E/S, passando FLT_PREOP_COMPLETE como o parâmetro CallbackStatus . Confira Como concluir uma operação de E/S em uma rotina de retorno de chamada de pré-operação.
Fazer todo o trabalho de conclusão na rotina de conclusão	Retornar FLT_POSTOP_FINISHED_PROCESSING da rotina de retorno de chamada de postoperation. Consulte Escrevendo rotinas de retorno de chamada de postoperação.
Fazer o trabalho de conclusão em IRQL seguro	Chame FltDoCompletionProcessingWhenSafe da rotina de retorno de chamada de postoperation. Consulte Garantindo que o processamento de conclusão seja executado em IRQL seguro.
Sinalizar um evento da rotina de conclusão	Retorne FLT_PREOP_SYNCHRONIZE da rotina de retorno de chamada de pré-operação para essa operação. O gerenciador de filtros chama a rotina de retorno de chamada de postoperation no mesmo contexto de thread que a rotina de retorno de chamada de pré-operação, em IRQL <= APC_LEVEL. Consulte Retornando FLT_PREOP_SYNCHRONIZE.
Falha em uma operação de criação bem-sucedida	Chame FltCancelFileOpen da rotina de retorno de chamada de postoperation para a operação de criação. Defina um valor NTSTATUS de erro apropriado no membro IoStatus da estrutura FLT_CALLBACK_DATA para a operação. Retornar FLT_POSTOP_FINISHED_PROCESSING. Confira Falha em uma operação de E/S em uma rotina de retorno de chamada de postoperation.
Não permitir E/S por meio do caminho de E/S rápido para uma operação de E/S	Retorne FLT_STATUS_DISALLOW_FAST_IO da rotina de retorno de chamada de pré-operação para a operação. Confira Não permitir uma operação de E/S rápida em uma rotina de retorno de chamada de pré-operação.
Modificar os parâmetros de uma operação de E/S	Defina os valores de parâmetro modificados no membro Iopb da estrutura FLT_CALLBACK_DATA para a operação. Marque a estrutura FLT_CALLBACK_DATA como sujo chamando FltSetCallbackDataDirty, exceto quando você tiver modificado o conteúdo do membro IoStatus da estrutura FLT_CALLBACK_DATA. Consulte Modificando os parâmetros para uma operação de E/S.
Bloquear o buffer de usuário para a operação	Use as técnicas e diretrizes descritas em Acessar os buffers de usuário para uma operação de E/S.