Função FltGetTunneledName (fltkernel.h)

Artigo
10/30/2024

A rotina FltGetTunneledName recupera o nome em túnel de um arquivo, dado o nome normalizado retornado para o arquivo por uma chamada anterior para FltGetFileNameInformation, FltGetFileNameInformationUnsafeou FltGetDestinationFileNameInformation.

Sintaxe

NTSTATUS FLTAPI FltGetTunneledName(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  PFLT_FILE_NAME_INFORMATION FileNameInformation,
  [out] PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);

Parâmetros

[in] CallbackData

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

[in] FileNameInformation

Ponteiro para uma estrutura FLT_FILE_NAME_INFORMATION que contém informações de nome normalizadas retornadas por uma chamada anterior para FltGetFileNameInformation, FltGetFileNameInformationUnsafeou FltGetDestinationFileNameInformation para o arquivo.

[out] RetTunneledFileNameInformation

Ponteiro para uma variável alocada por chamador que recebe o endereço de uma estrutura recém-alocada que contém o nome do arquivo túnel. Se nenhum nome em túnel for encontrado, essa variável receberá NULL . Esse parâmetro é necessário e não pode ser NULL na entrada.

Valor de retorno

FltGetTunneledName retornará STATUS_SUCCESS se o nome em túnel for encontrado ou se não houver nenhum nome em túnel para o arquivo. Caso contrário, ele retorna um valor NTSTATUS, como o seguinte:

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName encontrou uma falha de alocação de pool. Este é um código de erro.

Observações

Sistemas de arquivos, como NTFS e FAT, usam um cache de túnel por volume para preservar brevemente nomes de arquivos e outros metadados para arquivos que estão sendo renomeados, vinculados ou excluídos. O túnel de nome de arquivo pode fazer com que o componente final nas informações de nome de arquivo normalizadas retornadas por uma chamada de pré-operação para FltGetFileNameInformation, FltGetFileNameInformationUnsafeou FltGetDestinationFileNameInformation.

Se um driver de 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 criação (IRP_MJ_CREATE), um link rígido (IRP_MJ_SET_INFORMATION com FILE_INFORMATION_CLASS definido como FileLinkInformation) ou uma operação de renomeação (IRP_MJ_SET_INFORMATION com FILE_INFORMATION_CLASS definido como FileRenameInformation), ele deve chamar FltGetTunneledName de sua rotina de retorno de chamada de postoperation (PFLT_POST_OPERATION_CALLBACK) para recuperar as informações corretas do nome do arquivo.

Somente informações de nome de arquivo normalizadas são afetadas pelo túnel. O Gerenciador de Filtros não pode garantir que o componente final seja normalizado até que a operação de criação, vínculo rígido ou renomeação tenha realmente ocorrido, pois o túnel pode fazer com que um nome curto seja alterado para um nome longo. Portanto, um driver de minifiltro deve chamar FltGetTunneledName de sua rotina de retorno de chamada de postoperation para determinar se as informações de nome de arquivo normalizadas recuperadas na rotina de retorno de chamada de pré-operação são válidas.

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

Os drivers de minifiltro que recuperam apenas informações de nome de arquivo curto ou aberto não devem chamar FltGetTunneledName.

Depois de chamar FltGetFileNameInformation, FltGetFileNameInformationUnsafeou FltGetDestinationFileNameInformation na rotina de retorno de chamada de pré-operação, O driver de minifiltro deve armazenar o ponteiro FileNameInformation retornado na estrutura CompletionContext da rotina de chamada de pré-operação para que o retorno de chamada de postoperation possa passar esse ponteiro no parâmetro FileNameInformation para FltGetTunneledName .

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)

Se nenhum nome em túnel for encontrado para o arquivo, o parâmetro RetTunneledFileNameInformation receberá NULL.

Após uma chamada bem-sucedida para FltGetTunneledName, o chamador é responsável por liberar os ponteiros RetTunneledFileNameInformation e FileNameInformation quando eles não forem mais necessários chamando FltReleaseFileNameInformation.

FltGetTunneledName só deve ser chamado da rotina de retorno de chamada de postoperação de um driver de minifiltro para IRP_MJ_CREATE ou IRP_MJ_SET_INFORMATION. Chamar FltGetTunneledName de uma rotina de retorno de chamada de postoperation para qualquer outro tipo de operação de E/S, ou chamá-la de uma rotina de retorno de chamada de pré-operação, é um erro de programação.

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

O túnel de arquivos permite a compatibilidade com programas que dependem de sistemas de arquivos para preservar as metadações de arquivo por um curto período de tempo; por exemplo, para o processo de salvamento seguro. O túnel preserva a associação entre o nome longo e curto (8.3) de um arquivo. Quando um nome de arquivo é removido de um diretório (renomear ou excluir), seu par de nomes curto e longo e tempo de criação são salvos em um cache de túnel, com chave pelo nome que foi removido. Quando um nome é adicionado a um diretório (renomear ou criar), o cache é pesquisado para determinar se há informações a serem restauradas. O cache é eficaz por instância de um diretório. Se um diretório for excluído, seu cache será removido.