Função FltGetFileNameInformation (fltkernel.h)

Artigo
08/07/2023

A rotina FltGetFileNameInformation retorna informações de nome para um arquivo ou diretório.

Sintaxe

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parâmetros

[in] CallbackData

Ponteiro para uma estrutura FLT_CALLBACK_DATA , que é a estrutura de dados de retorno de chamada para a operação de E/S. Esse parâmetro é necessário e não pode ser NULL.

[in] NameOptions

Um valor FLT_FILE_NAME_OPTIONS que contém sinalizadores que especificam o formato das informações de nome a serem retornadas, bem como o método de consulta que o Gerenciador de Filtros deve usar. O chamador deve incluir um sinalizador de formato de nome e um sinalizador de método de consulta. Sinalizadores adicionais podem ser usados por drivers de minifiltro do provedor de nomes para especificar opções de consulta de nome. Esse parâmetro é necessário e não pode ser NULL.

Veja a seguir os valores de sinalizador de formato de nome de arquivo. Somente um dos sinalizadores a seguir pode ser especificado. Para obter uma explicação desses formatos, consulte FLT_FILE_NAME_INFORMATION.

Valor do sinalizador de formato de nome	Significado
FLT_FILE_NAME_NORMALIZED	O parâmetro FileNameInformation recebe o endereço de uma estrutura que contém o nome normalizado do arquivo.
FLT_FILE_NAME_OPENED	O parâmetro FileNameInformation recebe o endereço de uma estrutura que contém o nome que foi usado quando o arquivo foi aberto.
FLT_FILE_NAME_SHORT	O parâmetro FileNameInformation recebe o endereço de uma estrutura que contém o nome curto (8.3) do arquivo. O nome curto consiste em até 8 caracteres, seguidos imediatamente por um ponto e até três caracteres a mais. O nome curto de um arquivo não inclui o nome do volume, o caminho do diretório ou o nome do fluxo. Não é válido no caminho de pré-criação.

A seguir estão os valores de sinalizador do método de consulta de nome de arquivo. Somente um dos sinalizadores a seguir 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 nome do arquivo no sistema de arquivos, FltGetFileNameInformation não fará nada. Caso contrário, FltGetFileNameInformation consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome de arquivo. Se o nome não for encontrado no cache, FltGetFileNameInformation consultará o sistema de arquivos e armazenará o resultado em cache.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome de arquivo. FltGetFileNameInformation não consulta o sistema de arquivos.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation consulta o sistema de arquivos para obter as informações de nome de arquivo. FltGetFileNameInformation 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	FltGetFileNameInformation consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome de arquivo. Se o nome não for encontrado no cache e, no momento, for seguro fazer isso, FltGetFileNameInformation consultará o sistema de arquivos para obter as informações de nome de arquivo e armazenará em cache o resultado.

Os minifiltros do provedor de nomes usam os sinalizadores a seguir para especificar as propriedades das operações de nome de arquivo.

Valor do sinalizador do provedor de nomes	Significado
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	Um minifiltro do provedor de nomes pode usar esse sinalizador para especificar que uma solicitação de consulta de nome deve ser redirecionada para si mesma (o minifiltro do provedor de nomes) em vez de ser atendida pelos provedores de nomes mais baixos na pilha.
FLT_FILE_NAME_DO_NOT_CACHE	Esse sinalizador indica que o nome recuperado dessa consulta não deve ser armazenado em cache. Os minifiltros do provedor de nomes usam esse sinalizador enquanto executam consultas intermediárias para gerar um nome.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	Um minifiltro do provedor de nomes pode usar esse sinalizador para especificar que é seguro consultar o nome no caminho pós-criação, mesmo que STATUS_REPARSE tenha sido retornado. É responsabilidade do chamador garantir que o campo FileObject-FileName> não tenha sido alterado. Não use esse sinalizador com pontos de montagem ou pontos de nova análise de link simbólico.

[out] FileNameInformation

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 de arquivo. FltGetFileNameInformation aloca essa estrutura do pool paginado. Esse parâmetro é necessário e não pode ser NULL.

Retornar valor

Se as informações de nome forem retornadas com êxito, FltGetFileNameInformation retornará STATUS_SUCCESS. Caso contrário, ele retornará um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation não poderá obter informações de nome de arquivo em nenhuma das seguintes circunstâncias se a consulta não puder ser atendida no cache de nomes do Gerenciador de Filtros: No caminho de E/S de paginação. Quando o campo TopLevelIrp do thread atual não é NULL, porque a recursão resultante do sistema de arquivos pode causar deadlocks ou estouros de pilha. (Para obter mais informações sobre esse problema, consulte IoGetTopLevelIrp.) Após a conclusão de uma operação de IRP_MJ_CLEANUP; ou seja, no caminho pós-limpo para cima, pré-fechar ou pós-fechamento (o objeto de arquivo de destino tem o sinalizador FO_CLEANUP_COMPLETE definido). Em uma rotina de retorno de chamada de pré-operação (PFLT_PRE_OPERATION_CALLBACK) ou postoperation (PFLT_POST_OPERATION_CALLBACK) para qualquer uma das seguintes operações: IRP_MJ_ACQUIRE_FOR_CC_FLUSH IRP_MJ_ACQUIRE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_CC_FLUSH IRP_MJ_RELEASE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION Em uma rotina de retorno de chamada de postoperation para IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION. Quando todas as APCs estiverem desabilitadas; ou seja, quando KeAreAllApcsDisabled retorna TRUE. FltGetFileNameInformation não pode obter o nome curto de um arquivo no caminho de pré-criação. STATUS_FLT_INVALID_NAME_REQUEST é um código de erro.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_INVALID_PARAMETER	Retornado quando um parâmetro inválido é passado, como um dos seguintes: O parâmetro FileNameInformation não pode ser NULL. O parâmetro CallbackData não pode ser NULL. STATUS_INVALID_PARAMETER é um código de erro.
STATUS_FLT_NAME_CACHE_MISS	As informações de nome de arquivo não são encontradas no cache de nomes e NameOptions inclui FLT_FILE_NAME_QUERY_CACHE_ONLY. -ou- As informações de nome de arquivo não são encontradas no cache de nomes quando NameOptions inclui FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP e as informações de nome de arquivo não podem ser consultadas do sistema de arquivos. Uma chamada adicional para FltGetFileNameInformation com FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY definida em NameOptions pode retornar as informações de nome de arquivo.
STATUS_NOT_SAME_DEVICE	O arquivo que está sendo consultado durante a pré-criação está em um volume diferente do diretório pai. Esse erro é retornado para consultas de nome normalizadas, em que o arquivo era uma junção ou um symlink que foi resolvido para um volume diferente.
STATUS_ACCESS_DENIED	Se o usuário abriu o arquivo por ID de arquivo, mas não tem privilégios de passagem para todo o caminho, FltGetFileNameInformation falha com esse valor retornado. STATUS_ACCESS_DENIED é um código de erro. -ou- O arquivo é um arquivo do sistema com todo o acesso negado.

Comentários

FltGetFileNameInformation retorna as informações de nome solicitadas para o arquivo ou diretório que é o destino da operação descrita por CallbackData, no formato especificado. O arquivo ou diretório ainda não precisa ser aberto pelo sistema de arquivos.

Para uma operação de pré-criação, se o membro CallbackData-Iopb-OperationFlags>> contiver o sinalizador SL_OPEN_TARGET_DIRECTORY bit a bit, FltGetFileNameInformation retornará o nome do diretório contendo (pai) para o arquivo especificado. Esse nome é o caminho real que a operação de criação abre.

Para analisar o conteúdo da estrutura FLT_FILE_NAME_INFORMATION retornada por FltGetFileNameInformation, chame FltParseFileNameInformation. (Para obter mais informações sobre formatos de nome de arquivo, consulte FLT_FILE_NAME_INFORMATION.)

Após uma chamada bem-sucedida para FltGetFileNameInformation, o chamador é responsável por liberar o ponteiro retornado no parâmetro FileNameInformation quando o ponteiro não é mais necessário. O chamador faz isso chamando FltReleaseFileNameInformation.

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

Se FltGetFileNameInformation for chamado na rotina de retorno de chamada de pré-operação para uma operação de criação para recuperar o nome aberto, FltGetFileNameInformation terá êxito mesmo que o caminho para o arquivo que está sendo aberto não exista no volume.

Se FltGetFileNameInformation for chamado na rotina de retorno de chamada de pré-operação para uma operação de criação para recuperar o nome normalizado, FltGetFileNameInformation terá êxito mesmo que o componente final do caminho para o arquivo que está sendo aberto não exista no volume.

Observação

O suporte ao SMB (Bloco de Mensagens do Servidor) para consultar nomes de arquivo normalizados em um volume remoto varia em diferentes Windows 10 versões. Consulte o Protocolo MS-SMB2 para obter detalhes.

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 FltGetFileNameInformation, ele deverá chamar FltGetTunneledName de sua rotina de retorno de chamada de postoperation (PFLT_POST_OPERATION_CALLBACK) para recuperar as informações de nome de arquivo corretas para o arquivo.

Para Windows 8.1 e anteriores, FltGetFileNameInformation pode incluir um tipo de fluxosomente quando chamado do retorno de chamada de pré-criação de um filtro. Para distinguir entre fluxo padrão de um arquivo e fluxos de metadados, essa chamada deve ser feita na operação de pré-criação. O tipo de fluxo resultante permanecerá válido durante todo o tempo de vida do arquivo.

Antes de Windows 8, o Gerenciador de Filtros obteve o nome normalizado de um arquivo ou diretório coletando as informações de nome para cada componente do caminho do arquivo. Isso exigiu várias consultas ao sistema de arquivos para compilar o caminho completo. Começando com Windows 8, os sistemas de arquivos locais dão suporte à classe de informações de arquivo FileNormalizedNameInformation e apenas uma única consulta é necessária para obter o nome normalizado. Sistemas de arquivos remotos podem não dar suporte à classe de informações de arquivo FileNormalizedNameInformation . Quando esse for o caso, uma consulta para cada componente do caminho do arquivo ainda será necessária para montar o nome normalizado. Em determinadas condições de rede, uma consulta de nome completo pode exigir uma quantidade significativa de tempo para ser concluída.

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

Observação

O túnel de nome de arquivo afeta apenas operações de criação, vinculação e renomeação dessa maneira. Ele 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:

delete (name)/create(name)
delete (name)/rename(source, name)
rename (name, newname)/create(name)
rename (name, newname)/rename(source,name)

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua Fltkernel.h)
Biblioteca	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (consulte Valor retornado)