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 de 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, seguido imediatamente por um período 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 sistema de arquivos para o nome do arquivo, FltGetFileNameInformation não fará nada. Caso contrário, FltGetFileNameInformation consulta o cache de nomes do Gerenciador de Filtros para obter as informações do nome do 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 do nome do 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 do nome do 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 do nome do arquivo. Se o nome não for encontrado no cache e atualmente for seguro fazer isso, FltGetFileNameInformation consultará o sistema de arquivos quanto às informações do nome do 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ólicos.

[out] FileNameInformation

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

Valor de retorno

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-limpeza, pré-fechamento 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 postoperação 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 do nome do 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 definido em NameOptions pode retornar as informações do nome do 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 symlink que resolveu 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 falhar com esse valor retornado. STATUS_ACCESS_DENIED é um código de erro. -ou- O arquivo é um arquivo do sistema com todo o acesso negado.

Observações

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 fornecido. 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 for 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 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 aberto não exista no volume.

Nota

O suporte ao SMB (Server Message Block) para consultar nomes de arquivos normalizados em um volume remoto varia em diferentes versões do Windows 10. Consulte o do ProtocoloMS-SMB2 para obter detalhes.

Em 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 corretas de nome do arquivo.

Para o Windows 8.1 e anterior, FltGetFileNameInformation pode incluir um tipo de fluxo apenas quando chamado do retorno de chamada 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 do Windows 8, o Gerenciador de Filtros obteve o nome normalizado para 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. A partir do 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. Os 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 informações de nome de arquivo normalizado, consulte FLT_FILE_NAME_INFORMATION.

Nota

O túnel de nome de arquivo afeta somente operações de criação, vínculo rígido 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 arquivo nome 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
da Plataforma de Destino	Universal
cabeçalho	fltkernel.h (inclua Fltkernel.h)
biblioteca	FltMgr.lib
de DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (consulte o valor retornado)