Função FltGetTunneledName (fltkernel.h)

Artigo
08/07/2023

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, FltGetFileNameInformationUnsafe ou 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, FltGetFileNameInformationUnsafe ou FltGetDestinationFileNameInformation para o arquivo.

[out] RetTunneledFileNameInformation

Ponteiro para uma variável alocada pelo chamador que recebe o endereço de uma estrutura recém-alocada que contém o nome do arquivo em 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.

Retornar valor

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 retornará 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.

Comentários

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. O 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 driver de minifiltro recuperar informações de nome de arquivo normalizado 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 FileRenameInformation) ou a operação de renomeação (IRP_MJ_SET_INFORMATION com FILE_INFORMATION_CLASS definido como FileLinkInformation), ele deverá chamar FltGetTunneledName de sua rotina de retorno de chamada de operação de operação (PFLT_POST_OPERATION_CALLBACK) para recuperar as informações de nome de arquivo corretas para o arquivo.

Somente as informações de nome de arquivo normalizado 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, vinculação 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.

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

Depois de chamar FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou 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 retorno de chamada de pré-operação para que o retorno de chamada postoperation possa passar esse ponteiro no parâmetro FileNameInformation para FltGetTunneledName.

Observação

O túnel de nome de arquivo afeta apenas as operações de criação, vinculação 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 nome do arquivo seja encapsulado:

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 são mais necessários chamando FltReleaseFileNameInformation.

FltGetTunneledName só deve ser chamado da rotina de retorno de chamada postoperation 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 é efetivo por instância de um diretório. Se um diretório for excluído, seu cache será removido.