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

Artigo
08/07/2023

Um driver de minifiltro que fornece nomes de arquivo para o cache de nomes do gerenciador de filtros pode registrar uma rotina do tipo PFLT_GENERATE_FILE_NAME como a rotina 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 dessa 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; defina 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.

Retornar valor

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

Comentários

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 membro GenerateFileNameCallback 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 de Windows 8, essa rotina de retorno de chamada é chamada apenas para nomes de arquivo abertos e nomes de arquivos 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.

Começando com 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 especificado no parâmetro NameOptions . Se o minifiltro retornar STATUS_SUCCESS desse retorno de chamada, o retorno de chamada PFLT_NORMALIZE_NAME_COMPONENT do minifiltro 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. Em seguida, 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 de nome de arquivo, o driver de minifiltro deve chamar FltCheckAndGrowNameControl para marcar se o FLT_NAME_CONTROL estrutura para a qual o parâmetro FileName aponta contém 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. Em seguida, o driver de minifiltro armazena as informações de nome de arquivo no buffer de nome e retorna.