Função FltGetDestinationFileNameInformation (fltkernel.h)

Artigo
12/05/2023

A rotina FltGetDestinationFileNameInformation consulta o nome do arquivo para o diretório pai do destino e, em seguida, constrói um nome de caminho de destino completo para um arquivo ou diretório que está sendo renomeado ou para o qual um link rígido NTFS está sendo criado.

Sintaxe

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

Parâmetros

[in] Instance

Ponteiro de instância opaca para uma instância de driver de minifiltro anexada ao volume em que o arquivo reside.

[in] FileObject

Ponteiro para o objeto de arquivo do arquivo. Esse parâmetro é necessário e não pode ser NULL.

[in, optional] RootDirectory

Para operações de link: Se o link for criado no mesmo diretório que o arquivo que está sendo vinculado ou se FileName contiver o nome de caminho completo para o link a ser criado, esse parâmetro será NULL. Caso contrário, é um identificador para o diretório em que o link deve ser criado.

Para operações de renomeação: Se o arquivo não estiver sendo movido para um diretório diferente ou se FileName contiver o nome de caminho completo, esse parâmetro será NULL. Caso contrário, ele será um identificador para o diretório em que o arquivo reside depois de renomeado.

[in] FileName

Para operações de link: Ponteiro para uma cadeia de caracteres largos que contém o nome a ser atribuído ao link recém-criado.

Para operações de renomeação: Ponteiro para uma cadeia de caracteres largos que contém o novo nome do arquivo.

[in] FileNameLength

Comprimento, em bytes, da cadeia de caracteres largos para a qual FileName aponta.

[in] NameOptions

Um valor FLT_FILE_NAME_OPTIONS que contém sinalizadores que especificam o formato das informações de nome a serem retornadas, o método de consulta que o Gerenciador de Filtros deve usar e sinalizadores de nome de arquivo adicionais. Esse parâmetro é necessário e não pode ser NULL.

Veja a seguir os valores de sinalizador de formato de nome. Somente um sinalizador de formato de nome pode ser especificado. (Observe que FLT_FILE_NAME_SHORT não é um valor de sinalizador válido para esse parâmetro.)

Valor do sinalizador de formato de nome	Significado
FLT_FILE_NAME_NORMALIZED	O parâmetro FileName recebe o nome de destino normalizado para o arquivo.
FLT_FILE_NAME_OPENED	O parâmetro FileName recebe o nome de destino do arquivo, com base no nome que foi usado quando o arquivo foi aberto. Esse nome de arquivo não está normalizado.

Veja a seguir os valores de sinalizador do método de consulta. Somente um sinalizador de método de consulta pode ser especificado.

Valor do sinalizador do método de consulta	Significado
FLT_FILE_NAME_QUERY_DEFAULT	Se atualmente não for seguro consultar o sistema de arquivos para o nome do arquivo de destino, FltGetDestinationFileNameInformation não fará nada. Caso contrário, FltGetDestinationFileNameInformation consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome de arquivo para o diretório pai do destino e acrescenta o nome de destino. Se o nome resultante não for encontrado no cache, FltGetDestinationFileNameInformation consultará o sistema de arquivos e armazenará em cache o resultado.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetDestinationFileNameInformation consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome de arquivo para o diretório pai do destino e acrescenta o nome de destino. Ele não consulta o sistema de arquivos.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetDestinationFileNameInformation consulta o sistema de arquivos para obter informações de nome de arquivo para o diretório pai do destino e acrescenta o nome de destino. Ele não consulta o cache de nomes do Gerenciador de Filtros e não armazena em cache o resultado da consulta do sistema de arquivos.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetDestinationFileNameInformation consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome de arquivo para o diretório pai do destino e acrescenta o nome de destino. Se o nome não for encontrado no cache e atualmente for seguro fazer isso, FltGetDestinationFileNameInformation consultará o sistema de arquivos para obter as informações de nome de arquivo e armazenará em cache o resultado.

Veja a seguir os valores do sinalizador de nome de arquivo. Qualquer combinação desses sinalizadores pode ser especificada. (Observe que FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE não é um sinalizador relevante para esse parâmetro, pois FltGetDestinationFileNameInformation não é usado em um retorno de chamada pós-criação.)

Valor do sinalizador de nome de arquivo	Significado
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation direciona a solicitação de nome para a instância de filtro de chamada a ser concluída.
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation não armazena em cache o nome do arquivo recuperado. Os minifiltros do provedor de nomes usam esse sinalizador à medida que executam consultas intermediárias para gerar um nome.

[out] RetFileNameInformation

Ponteiro para uma variável alocada pelo chamador que recebe o endereço de uma estrutura de FLT_FILE_NAME_INFORMATION alocada pelo sistema que contém as informações de nome do arquivo. FltGetDestinationFileNameInformation aloca essa estrutura do pool de páginas. Esse parâmetro é necessário e não pode ser NULL.

Retornar valor

FltGetDestinationFileNameInformation retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_FLT_INVALID_NAME_REQUEST	Esse valor é retornado por um dos seguintes motivos: (1) FltGetDestinationFileNameInformation não poderá obter informações de nome de arquivo se o campo TopLevelIrp do thread atual não for NULL, pois a recursão resultante do sistema de arquivos pode causar deadlocks ou estouros de pilha. (2) FLT_FILE_NAME_SHORT foi especificado para o sinalizador de formato de nome no parâmetro NameOptions .
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_INVALID_PARAMETER	Um valor inválido foi especificado para o parâmetro NameOptions . Este é um código de erro.
STATUS_MOUNT_POINT_NOT_RESOLVED	O nome do caminho de destino contém um ponto de montagem que é resolvido para um volume diferente daquele em que o arquivo reside. (Como uma operação de renomeação ou criação de link rígido só pode ser executada dentro de um volume e não entre volumes, a operação falha.) Este é um código de erro.

Comentários

Os minifilters normalmente chamam FltGetDestinationFileNameInformation em uma rotina de retorno de chamada de pré-operação para uma operação de renomeação ou criação de link rígido, o que significa que o nome do arquivo de destino provavelmente não existe. O nome "destino" é:

Para uma renomeação de arquivo, o nome que o arquivo terá se a renomeação for bem-sucedida. Por exemplo, ao renomear name1 para name2, name2 é o nome de destino.
Para uma operação de criação de link rígido, o nome que está sendo adicionado ao sistema de arquivos. Por exemplo, ao adicionar o nome do link rígido2 ao arquivo existente chamado name1, name2 é o nome de destino.

FltGetDestinationFileNameInformation retorna as informações de nome de arquivo de destino no formato normalizado ou "arquivo aberto". Para obter mais informações sobre esses formatos, consulte a estrutura FLT_FILE_NAME_INFORMATION .

O ponteiro do objeto de arquivo que é passado para o parâmetro FileObject deve ser o membro FileObject da estrutura FLT_RELATED_OBJECTS da operação ou o ponteiro Data-Iopb-TargetFileObject>> para a operação, em que Data é a estrutura de dados de retorno de chamada para a operação (FLT_CALLBACK_DATA). O ponteiro do objeto de arquivo não pode ser o membro Data-Iopb-Parameters.SetFileInformation.FileObject>>, pois esse campo não é usado uniformemente em sistemas de arquivos.

Se o usuário abriu o arquivo usando a ID do arquivo, mas não tem privilégio de passagem para todo o caminho, FltGetDestinationFileNameInformation retorna apenas a parte do caminho para o qual o usuário tem privilégio.

Uma operação de renomeação ou criação de link rígido só pode ser executada em um volume e não entre volumes. Portanto, essa operação falhará se o nome do caminho de destino contiver um ponto de montagem que seja resolvido para um volume diferente daquele em que o arquivo reside. Para obter mais informações sobre operações de renomeação, consulte a estrutura FILE_RENAME_INFORMATION . Para obter mais informações sobre operações de criação de vínculo rígido, consulte as estruturas de FILE_LINK_INFORMATION .

Após uma chamada bem-sucedida para FltGetDestinationFileNameInformation, o chamador é responsável por liberar o ponteiro retornado no parâmetro RetFileNameInformation quando ele não for mais necessário chamando FltReleaseFileNameInformation.

O chamador não deve modificar o conteúdo da estrutura retornada no parâmetro RetFileNameInformation , pois essa estrutura é armazenada em cache pelo Gerenciador de Filtros para que todos os drivers de minifiltro possam usá-la.

Nas operações criar, vincular e renomear, o túnel de nome de arquivo pode fazer com que o componente final em informações de nome de arquivo normalizado que um driver de minifiltro recupera em uma rotina de retorno de chamada de pré-operação seja invalidado. Se um driver de minifiltro recuperar informações de nome de arquivo normalizadas em uma rotina de retorno de chamada de pré-operação (PFLT_PRE_OPERATION_CALLBACK) chamando uma rotina como FltGetDestinationFileNameInformation, ele deverá chamar FltGetTunneledName de sua rotina de retorno de chamada de postoperation para recuperar as informações corretas de nome de arquivo para o arquivo.

Para obter mais informações sobre o nome do arquivo normalizado, consulte FLT_FILE_NAME_INFORMATION.

O túnel de nome de arquivo afeta apenas operações de criação, vinculação e renomeação dessa maneira. Isso não afeta outras operações de E/S, como leitura e gravação.

As seguintes operações emparelhadas podem fazer com que o nome do nome do arquivo seja túnel: