Função FltGetFileNameInformationUnsafe (fltkernel.h)

Artigo
08/07/2023

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

Sintaxe

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parâmetros

[in] FileObject

Ponteiro para um objeto de arquivo para o arquivo ou diretório. O objeto de arquivo deve estar aberto no momento. Esse parâmetro é necessário e não pode ser definido como NULL.

[in, optional] Instance

Ponteiro de instância para o chamador. Esse parâmetro pode ser definido como 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 a ser usado pelo Gerenciador de Filtros. Esse parâmetro é necessário e não pode ser definido como NULL.

A tabela a seguir descreve os valores de sinalizador de formato de nome. Somente um dos sinalizadores pode ser especificado. Para obter mais informações sobre esses formatos, consulte FLT_FILE_NAME_INFORMATION.

Valor	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é mais três caracteres. O nome curto de um arquivo não inclui o nome do volume, o caminho do diretório ou o nome do fluxo.

A tabela a seguir descreve os valores de sinalizador do método de consulta. Somente um dos sinalizadores pode ser especificado.

Valor	Significado
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome do arquivo. Se o nome não for encontrado no cache, FltGetFileNameInformationUnsafe consultará o sistema de arquivos e armazenará o resultado em cache.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome do arquivo. FltGetFileNameInformationUnsafe não consulta o sistema de arquivos.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe consulta o sistema de arquivos para obter as informações de nome de arquivo. FltGetFileNameInformationUnsafe 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	FltGetFileNameInformationUnsafe consulta o cache de nomes do Gerenciador de Filtros para obter as informações de nome do arquivo. Se o nome não for encontrado no cache e atualmente for seguro fazer isso, FltGetFileNameInformationUnsafe consultará o sistema de arquivos para obter as informações de nome de arquivo e armazenará em cache o resultado.

[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. FltGetFileNameInformationUnsafe aloca essa estrutura do pool de páginas. Quando essas informações não forem mais necessárias, o chamador deverá liberar a estrutura chamando FltReleaseFileNameInformation. Esse parâmetro é necessário e não pode ser definido como NULL.

Retornar valor

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

Código de retorno	Descrição
STATUS_FLT_INVALID_NAME_REQUEST	O objeto de arquivo para o qual o parâmetro FileObject aponta não está aberto no momento. Este é um código de erro.
STATUS_INVALID_PARAMETER	Um valor inválido foi passado para o parâmetro FileNameInformation . Este é um código de erro.

Comentários

A rotina FltGetFileNameInformationUnsafe é fornecida para que você possa consultar o nome de um objeto de arquivo fora do contexto de uma operação de E/S nesse objeto de arquivo; caso contrário, você deve chamar FltGetFileNameInformation.

Ao contrário da rotina FltGetFileNameInformation , FltGetFileNameInformationUnsafe não protege o chamador contra os seguintes tipos de circunstâncias, em que consultar o sistema de arquivos para obter informações de nome pode causar deadlocks para métodos de consulta diferentes de FLT_FILE_NAME_QUERY_CACHE_ONLY:

No caminho de E/S de paginação.
Quando o campo TopLevelIrp do thread atual não é NULL. Para obter mais informações, consulte IoGetTopLevelIrp.
Após a conclusão de uma operação de IRP_MJ_CLEANUP; ou seja, no caminho pós-limpo, 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 postoperation para IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION.
Quando todas as APCs estiverem desabilitadas; ou seja, quando KeAreAllApcsDisabled retorna TRUE.

Para o Windows Vista/Server 2008 e posterior, se um minifiltro ainda não tiver uma instância de filtro, como em sua rotina DriverEntry , ele poderá usar NULL para o parâmetro Instance . Isso permite que as rotinas do DriverEntry acessem informações de nome de arquivo. Exceto para esse caso, um NULL valor para o parâmetro de instância é reservado para uso do sistema.

Em operações criar, vincular e renomear, o túnel de nome de arquivo pode invalidar o componente final em informações de nome de arquivo normalizadas que um driver de minifiltro recupera em uma rotina de retorno de chamada de pré-operação. 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 FltGetFileNameInformationUnsafe, 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 de arquivo para o arquivo.

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

Requisitos

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