estrutura FLT_FILE_NAME_INFORMATION (fltkernel.h)

Artigo
03/01/2024

A estrutura FLT_FILE_NAME_INFORMATION contém informações de nome de arquivo.

Sintaxe

typedef struct _FLT_FILE_NAME_INFORMATION {
  USHORT                     Size;
  FLT_FILE_NAME_PARSED_FLAGS NamesParsed;
  FLT_FILE_NAME_OPTIONS      Format;
  UNICODE_STRING             Name;
  UNICODE_STRING             Volume;
  UNICODE_STRING             Share;
  UNICODE_STRING             Extension;
  UNICODE_STRING             Stream;
  UNICODE_STRING             FinalComponent;
  UNICODE_STRING             ParentDir;
} FLT_FILE_NAME_INFORMATION, *PFLT_FILE_NAME_INFORMATION;

Membros

Size

Tamanho, em bytes, da estrutura FLT_FILE_NAME_INFORMATION.

NamesParsed

Bitmask de sinalizadores que indicam quais componentes de nome foram analisados da cadeia de caracteres Name por FltParseFileNameInformation. Observe que, ao analisar a cadeia de caracteres Name , FltParseFileNameInformation define esse sinalizador para cada componente, independentemente de o componente estar presente na cadeia de caracteres. Esses valores podem ser combinados usando o operador OR.

Sinalizador	Componente
FLTFL_FILE_NAME_PARSED_FINAL_COMPONENT	FinalComponent
FLTFL_FILE_NAME_PARSED_EXTENSION	Extensão
FLTFL_FILE_NAME_PARSED_STREAM	Stream
FLTFL_FILE_NAME_PARSED_PARENT_DIR	ParentDir

Format

Formato das informações de nome armazenadas no membro Name . Esse membro pode ser um dos valores a seguir. (Para obter uma explicação desses formatos, consulte a seção Comentários a seguir.)

Valor	Significado
FLT_FILE_NAME_NORMALIZED	O membro Name contém o nome normalizado para o arquivo.
FLT_FILE_NAME_OPENED	O membro Name contém o nome que foi usado quando o arquivo foi aberto. Essa cadeia de caracteres de nome não está normalizada.
FLT_FILE_NAME_SHORT	O membro Name contém o nome curto (8.3) do arquivo. O nome curto de um arquivo não inclui o nome do volume, o caminho do diretório ou o nome do fluxo. Essa cadeia de caracteres de nome não está normalizada.

Name

UNICODE_STRING estrutura que contém a cadeia de caracteres de nome de arquivo, formatada conforme especificado pelo membro Format .

Volume

UNICODE_STRING estrutura que contém o nome do volume analisado da cadeia de caracteres Name . Se Format for FLT_FILE_NAME_SHORT, Volume.Length será zero.

Share

UNICODE_STRING estrutura que contém o nome do compartilhamento de rede analisado da cadeia de caracteres Name para um arquivo remoto. Se Format for FLT_FILE_NAME_SHORT, Share.Length será zero.

Extension

UNICODE_STRING estrutura que contém a extensão analisada da cadeia de caracteres Name . Se nenhuma extensão for encontrada, FltParseFileNameInformation definiráExtension.Length como zero.

Stream

UNICODE_STRING estrutura que contém o nome do fluxo analisado da cadeia de caracteres Name . Se nenhum nome de fluxo for encontrado ou se Format for FLT_FILE_NAME_SHORT, FltParseFileNameInformation definiráStream. Comprimento até zero.

FinalComponent

UNICODE_STRING estrutura que contém o componente de nome final analisado da cadeia de caracteres Name . Se nenhum nome de componente final for encontrado ou se Format for FLT_FILE_NAME_SHORT, FltParseFileNameInformation definiráFinalComponent.Length como zero.

ParentDir

UNICODE_STRING estrutura que contém o nome do diretório pai analisado da cadeia de caracteres Name por FltParseFileNameInformation. Se nenhum nome de diretório pai for encontrado ou se Format for FLT_FILE_NAME_SHORT, FltParseFileNameInformation definirá ParentDir.Length como zero.

Comentários

O membro Name contém um dos seguintes:

O nome normalizado para o arquivo
O nome aberto para o arquivo
O nome curto do arquivo

Um nome de arquivo será considerado normalizado se todos os itens a seguir forem verdadeiros:

Ele contém o caminho completo do diretório para o arquivo, incluindo o nome do volume, a menos que o usuário tenha aberto o arquivo por ID de arquivo, mas não tenha privilégio de passagem para todo o caminho. (Para obter mais informações, consulte FltGetFileNameInformation.)
O nome do volume é o nome do objeto de dispositivo não persistente do volume (por exemplo, "\Device\HarddiskVolume1").
Todos os nomes curtos são expandidos para os nomes longos equivalentes.
Todas as cadeias de caracteres ":$DATA" ou "::$DATA" à direita são removidas do nome do fluxo.
Todos os pontos de montagem são resolvidos.

Veja a seguir um exemplo de um nome de arquivo normalizado para um arquivo local:

\Device\HarddiskVolume1\Documents and Settings\MyUser\My Documents\Test Results.txt:stream1

Veja a seguir um exemplo de um nome de arquivo normalizado para um arquivo remoto:

\Device\LanManRedirector\MyServer\MyShare\Documents and Settings\MyUser\My Documents\Test Results.txt:stream1

O nome aberto para um arquivo é o nome que foi usado quando o arquivo foi aberto. Como o nome normalizado, ele contém o caminho de diretório completo para o arquivo, incluindo o nome do volume. Ela difere do nome normalizado das seguintes maneiras:

O caminho do diretório para o arquivo pode conter nomes curtos, bem como nomes longos.
As cadeias de caracteres ":$DATA" e "::$DATA" à direita não são removidas do nome do fluxo.
Os pontos de montagem não são resolvidos.

Veja a seguir um exemplo de um nome de arquivo aberto para um arquivo local:

\Device\HarddiskVolume1\Docume~1\MyUser\MYDOCU~1\Test Results.txt:stream1:$DATA

Veja a seguir um exemplo de um nome de arquivo aberto para um arquivo remoto:

\Device\LanManRedirector\MyServer\MyShare\Documents and Settings\MyUser\My Documents\Test Results.txt:stream1

O nome curto de um arquivo é o nome curto (8.3) do componente final do nome do arquivo. Como ele é gerado quando o arquivo é aberto, o nome curto não está disponível para um objeto de arquivo não aberto e não está disponível no caminho create dispatch ("pre-create"). Ele também não está disponível para objetos de arquivo de fluxo NTFS. Nem todos os arquivos abertos têm nomes de arquivo curtos. Por exemplo, em partições NTFS em que a geração de nome de arquivo curto foi desabilitada, nenhum arquivo tem nomes de arquivo curtos.

Veja a seguir um exemplo de um nome curto para um arquivo:

TestRe~1.txt

Para obter uma estrutura FLT_FILE_NAME_INFORMATION para um arquivo, chame FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou FltGetDestinationFileNameInformation. Essas rotinas retornam um ponteiro para uma estrutura de FLT_FILE_NAME_INFORMATION de propriedade do Gerenciador de Filtros que é compartilhada por todos os minifiltros.

Nota Não modifique o conteúdo de estruturas de FLT_FILE_NAME_INFORMATION, pois essas estruturas são armazenadas em cache pelo Gerenciador de Filtros para que todos os minifiltros possam usá-las. Se o minifiltro precisar modificar essas informações de alguma forma, ele deverá copiar as informações para outro buffer primeiro.

Sistemas de arquivos como NTFS e FAT usam um cache de túnel por volume para preservar brevemente nomes de arquivo e outros metadados para arquivos que estão sendo renomeados, vinculados ou excluídos. Esse túnel de nome de arquivo pode fazer com que o componente final em informações de nome de arquivo normalizadas retornadas por uma chamada de pré-operação para FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou FltGetDestinationFileNameInformation seja invalidado. Se um minifiltro recuperar informações de nome de arquivo normalizadas na rotina de retorno de chamada de pré-operação (PFLT_PRE_OPERATION_CALLBACK) para uma operação de criação, link rígido ou renomeação, ele deverá chamar FltGetTunneledName de sua rotina de retorno de chamada de operação de postagem (PFLT_POST_OPERATION_CALLBACK) para recuperar as informações de nome de arquivo corretas para o arquivo.

Embora contenha várias estruturas UNICODE_STRING , a estrutura FLT_FILE_NAME_INFORMATION não ocupa muito espaço na memória porque todas as estruturas de UNICODE_STRING em uma estrutura FLT_FILE_NAME_INFORMATION compartilham um único buffer.

Para analisar o conteúdo da cadeia de caracteres Name , chame FltParseFileNameInformation. Essa rotina define os valores dos membros Extension, Stream, FinalComponent, ParentDir e NamesParsed dessa estrutura.

Os minifiltros são responsáveis por chamar FltReleaseFileNameInformation para liberar a estrutura FLT_FILE_NAME_INFORMATION quando ela não for mais necessária.