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

Artigo
02/06/2025

Um driver de minifiltro que fornece nomes de arquivo para o cache de nomes do gerenciador de filtros pode registrar uma rotina de tipo PFLT_GENERATE_FILE_NAME como a rotina de generateFileNameCallback do driver de minifiltro.

Sintaxe

PFLT_GENERATE_FILE_NAME PfltGenerateFileName;

NTSTATUS PfltGenerateFileName(
  [in]           PFLT_INSTANCE Instance,
  [in]           PFILE_OBJECT FileObject,
  [in, optional] PFLT_CALLBACK_DATA CallbackData,
  [in]           FLT_FILE_NAME_OPTIONS NameOptions,
  [out]          PBOOLEAN CacheFileNameInformation,
  [out]          PFLT_NAME_CONTROL FileName
)
{...}

Parâmetros

[in] Instance

Ponteiro de instância opaca para a instância do driver de minifiltro para a qual essa rotina de retorno de chamada está registrada.

[in] FileObject

Um ponteiro para um objeto de arquivo para o arquivo cujo nome está sendo solicitado.

[in, optional] CallbackData

Um ponteiro para a estrutura de dados de retorno de chamada para a operação durante a qual esse nome está sendo solicitado. Esse parâmetro é NULL quando FltGetFileNameInformationUnsafe é chamado para recuperar o nome do arquivo.

[in] NameOptions

FLT_FILE_NAME_OPTIONS valor que especifica o formato de nome, o método de consulta e os sinalizadores para essa consulta de informações de nome de arquivo.

[out] CacheFileNameInformation

Um ponteiro para um valor booliano que especifica se esse nome pode ser armazenado em cache. Defina como TRUE na saída se o nome puder ser armazenado em cache; definido como false caso contrário.

[out] FileName

Um ponteiro para uma estrutura de FLT_NAME_CONTROL alocada pelo gerenciador de filtros para receber o nome do arquivo na saída.

Valor de retorno

Essa rotina de retorno de chamada retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado.

Observações

Para registrar essa rotina de retorno de chamada, o driver de minifiltro armazena o endereço de uma rotina do tipo PFLT_GENERATE_FILE_NAME no GenerateFileNameCallback membro da estrutura FLT_REGISTRATION que o driver de minifiltro passa como um parâmetro para FltRegisterFilter.

O gerenciador de filtros chama essa rotina de retorno de chamada para permitir que o driver de minifiltro intercepte solicitações de nome de arquivo por outros drivers de minifiltro acima dele na pilha de instâncias do driver de minifiltro. Usando essa rotina de retorno de chamada e a rotina de retorno de chamada PFLT_NORMALIZE_NAME_COMPONENT, o driver de minifiltro pode fornecer suas próprias informações de nome de arquivo.

Para determinar qual formato de nome de arquivo está sendo solicitado, chame FltGetFileNameFormat no parâmetro NameOptions.

Antes do Windows 8, essa rotina de retorno de chamada é chamada apenas para nomes de arquivo abertos e nomes de arquivo curtos. Quando o gerenciador de filtros recebe uma solicitação de um nome de arquivo normalizado, ele chama essa rotina de retorno de chamada para solicitar o nome do arquivo aberto. Em seguida, ele chama o retorno de chamada PFLT_NORMALIZE_NAME_COMPONENT do driver de minifiltro para normalizar cada componente no nome do arquivo.

A partir do Windows 8, essa rotina de retorno de chamada também é chamada para nomes normalizados. Quando o gerenciador de filtros recebe uma solicitação de um nome de arquivo normalizado, ele chama essa rotina de retorno de chamada com FLT_FILE_NAME_NORMALIZED especificada no parâmetro NameOptions. Se o minifiltro retornar STATUS_SUCCESS desse retorno de chamada, o minifiltro PFLT_NORMALIZE_NAME_COMPONENT retorno de chamada não será chamado. Se o minifiltro retornar um código de falha (como STATUS_NOT_SUPPORTED), o gerenciador de filtros chamará essa rotina de retorno de chamada novamente, solicitando o nome do arquivo aberto. O gerenciador de filtros chamará o retorno de chamada PFLT_NORMALIZE_NAME_COMPONENT do driver de minifiltro para normalizar cada componente no nome do arquivo.

Quando essa rotina de retorno de chamada é invocada, o driver de minifiltro gera suas próprias informações de nome de arquivo, com base nas informações de nome de arquivo do sistema de arquivos para o arquivo. Para obter informações de nome de arquivo do sistema de arquivos para um arquivo, chame FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou FltGetDestinationFileNameInformation.

Para nomes de arquivo abertos, as informações de nome de arquivo geradas devem incluir informações de volume. Para um arquivo remoto, ele também deve incluir informações de compartilhamento.

Veja a seguir um exemplo de um nome de arquivo aberto para um arquivo remoto:

\Device\LanManRedirector\MyServer\MyShare\Docume~1\MyUser\My Documents\TestRe~1.txt:stream1

Para obter mais informações sobre formatos de nome de arquivo, consulte as entradas de referência para FLT_FILE_NAME_INFORMATION e FltParseFileNameInformation.

Depois de gerar as informações do nome do arquivo, o driver de minifiltro deve chamar FltCheckAndGrowNameControl para verificar se a estrutura de FLT_NAME_CONTROL que o FileName aponta para conter um buffer de nome grande o suficiente para manter o nome do arquivo gerado. Se o buffer de nome for muito pequeno, FltCheckAndGrowNameControl o substituirá por um maior. O driver de minifiltro armazena as informações do nome do arquivo no buffer de nome e retorna.