FltGetTunneledName 函数 (fltkernel.h)

项目
02/26/2024

FltGetTunneledName 例程检索文件的隧道名称，给定先前调用 FltGetFileNameInformation、FltGetFileNameInformation 或 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、FltGetFileNameInformation 或 FltGetDestinationFileNameInformation 的预操作调用返回的规范化文件名信息中的最终组件失效。

如果微筛选器驱动程序在预操作回调例程中检索规范化文件名信息， (PFLT_PRE_OPERATION_CALLBACK) 创建 (IRP_MJ_CREATE) ，则硬链接 (IRP_MJ_SET_INFORMATION，FILE_INFORMATION_CLASS 设置为 FileRenameInformation) ，或重命名操作 (IRP_MJ_SET_INFORMATION，FILE_INFORMATION_CLASS设置为 FileLinkInformation) ，它必须从其操作后回调例程 (调用 FltGetTunneledNamePFLT_POST_OPERATION_CALLBACK) 以检索文件的正确文件名信息。

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

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

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

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

注意

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

以下配对操作可能会导致文件名通过隧道传输：

删除 (名称) /create (name)
删除 (名称) /rename (source，name)
重命名 (名称、 newname) /create (name)
重命名 (名称、 newname) /rename (source、 name)

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

成功调用 FltGetTunneledName 后，调用方负责通过调用 FltReleaseFileNameInformation 不再需要 RetTunneledFileNameInformation 和 FileNameInformation 指针时释放它们。

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

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

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