Função FltGetDestinationFileNameInformation (fltkernel.h)
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:
- 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 |
Confira também
FltGetFileNameInformationUnsafe