FltGetTunneledName 函数（fltkernel.h）

项目
10/30/2024

FltGetTunneledName 例程检索文件的隧道名称，给定对 FltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation的规范化名称。

语法

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

参数

[in] CallbackData

指向 I/O 操作的回调数据结构的指针（FLT_CALLBACK_DATA）。此参数是必需的，不能 NULL。

[in] FileNameInformation

指向 FLT_FILE_NAME_INFORMATION 结构的指针，该结构包含上一次调用 FltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation 返回的规范化名称信息。

[out] RetTunneledFileNameInformation

指向调用方分配的变量的指针，该变量接收包含隧道文件名的新分配结构的地址。如果未找到隧道名称，此变量将接收 NULL。此参数是必需的，不能在输入时 NULL。

返回值

FltGetTunneledName 在找到隧道名称或文件没有隧道名称时返回STATUS_SUCCESS。否则，它将返回 NTSTATUS 值，例如：

返回代码	描述
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName 遇到池分配失败。这是一个错误代码。

言论

文件系统（如 NTFS 和 FAT）使用每卷隧道缓存来简要保留要重命名、链接到或删除的文件的文件名和其他元数据。文件名隧道可能导致规范化文件名信息中的最终组件通过预操作调用 FltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation 返回。

如果微型筛选器驱动程序检索创建（PFLT_PRE_OPERATION_CALLBACKIRP_MJ_CREATE）、硬 IRP_MJ_SET_INFORMATION链接（FILE_INFORMATION_CLASS 设置为 FileLinkInformation）中的规范化文件名信息，或重命名操作 IRP_MJ_SET_INFORMATION（FILE_INFORMATION_CLASS设置为 FileRenameInformation），它必须从其操作后回调例程（PFLT_POST_OPERATION_CALLBACK）调用 FltGetTunneledName，才能检索文件的正确文件名信息。

仅规范化文件名信息受隧道影响。筛选器管理器无法确保最终组件在创建、硬链接或重命名操作发生后才进行规范化，因为隧道可能会导致短名称更改为长名称。因此，微型筛选器驱动程序必须从其操作后回调例程调用 FltGetTunneledName，以确定在预操作回调例程中检索的规范化文件名信息是否有效。

有关规范化文件名信息的详细信息，请参阅 FLT_FILE_NAME_INFORMATION。

仅检索短文件名或打开的文件名信息的微型筛选器驱动程序不应调用 FltGetTunneledName。

调用 FltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation 预操作回调例程中，微型筛选器驱动程序必须在预操作回调例程的 CompletionContext 结构中存储返回的 FileNameInformation 指针，以便后操作回调可以将此指针传递给 FileNameInformation 参数以 FltGetTunneledName。

注意

文件名隧道仅影响以这种方式创建、硬链接和重命名操作。它不会影响其他 I/O 操作，例如读取和写入。

以下配对操作可能会导致文件名名称隧道：

delete（名称）/create（名称）
delete（名称）/rename（源，名称）
rename（名称，newname）/create（名称）
rename（名称，newname）/rename（源，名称）

如果找不到文件的隧道名称，则 RetTunneledFileNameInformation 参数接收 NULL。

成功调用 FltGetTunneledName后，调用方负责发布 RetTunneledFileNameInformation，并在不再需要 fileNameInformation 指针时调用 FltReleaseFileNameInformation。

FltGetTunneledName 只能从微型筛选器驱动程序的操作后回调例程中调用IRP_MJ_CREATE或IRP_MJ_SET_INFORMATION。从任何其他类型的 I/O 操作或从预操作回调例程调用 FltGetTunneledName 是编程错误。

调用方不得修改在 RetTunneledFileNameInformation 参数中返回的结构的内容，因为此结构由筛选器管理器缓存，以便所有微型筛选器驱动程序都可以使用它。

文件隧道使与依赖于文件系统的程序兼容，以在短时间内保留文件元信息;例如，对于安全保存过程。隧道保留文件的长和短（8.3）名称之间的关联。从目录中删除文件名时（重命名或删除），其短名称对和长名称对和创建时间保存在隧道缓存中，由删除的名称进行键键。将名称添加到目录（重命名或创建）时，将搜索缓存以确定是否有要还原的信息。缓存在每个目录实例中有效。如果删除了目录，则会删除其缓存。