FltGetDestinationFileNameInformation 函数 (fltkernel.h)

项目
12/05/2023

FltGetDestinationFileNameInformation 例程查询目标的父目录的文件名，然后为正在重命名或正在为其创建 NTFS 硬链接的文件或目录构造完整的目标路径名称。

语法

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
);

参数

[in] Instance

附加到文件所在的卷的微筛选器驱动程序实例的不透明实例指针。

[in] FileObject

指向文件的文件对象的指针。此参数是必需的，不能为 NULL。

[in, optional] RootDirectory

对于链接操作： 如果要在链接到的文件所在的同一目录中创建链接，或者 如果 FileName 包含要创建的链接的完整路径名，则此参数为 NULL。否则，它是要在其中创建链接的目录的句柄。

对于重命名操作： 如果文件未移动到其他目录，或者 FileName 包含完整路径名，则此参数为 NULL。否则，它是重命名后文件所在的目录的句柄。

[in] FileName

对于链接操作： 指向宽字符字符串的指针，该字符串包含要分配给新创建的链接的名称。

对于重命名操作： 指向包含文件新名称的宽字符字符串的指针。

[in] FileNameLength

FileName 指向的宽字符字符串的长度（以字节为单位）。

[in] NameOptions

一个FLT_FILE_NAME_OPTIONS值，其中包含指定要返回的名称信息格式的标志、筛选器管理器要使用的查询方法以及其他文件名标志。此参数是必需的，不能为 NULL。

下面是名称格式标志值。只能指定一个名称格式标志。 (请注意，FLT_FILE_NAME_SHORT不是此参数的有效标志值。)

名称格式标志值	含义
FLT_FILE_NAME_NORMALIZED	FileName 参数接收文件的规范化目标名称。
FLT_FILE_NAME_OPENED	FileName 参数根据打开文件时使用的名称接收文件的目标名称。此文件名未规范化。

下面是查询方法标志值。只能指定一个查询方法标志。

查询方法标志值	含义
FLT_FILE_NAME_QUERY_DEFAULT	如果当前无法安全地查询文件系统中的目标文件名，则 FltGetDestinationFileNameInformation 不执行任何操作。否则， FltGetDestinationFileNameInformation 在筛选器管理器的名称缓存中查询目标父目录的文件名信息，然后追加目标名称。如果在缓存中找不到结果名称， FltGetDestinationFileNameInformation 会查询文件系统并缓存结果。
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetDestinationFileNameInformation 在筛选器管理器的名称缓存中查询目标父目录的文件名信息，然后追加目标名称。它不会查询文件系统。
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetDestinationFileNameInformation 在文件系统中查询目标父目录的文件名信息，然后追加目标名称。它不会查询筛选器管理器的名称缓存，也不会缓存文件系统查询的结果。
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetDestinationFileNameInformation 在筛选器管理器的名称缓存中查询目标父目录的文件名信息，然后追加目标名称。如果在缓存中找不到该名称，并且当前是安全的，则 FltGetDestinationFileNameInformation 会查询文件系统以获取文件名信息并缓存结果。

下面是文件名标志值。可以指定这些标志的任意组合。 (请注意，FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE不是此参数的相关标志，因为 FltGetDestinationFileNameInformation 未在创建后回调中使用 )

文件名标志值	含义
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation 将名称请求定向到调用筛选器实例完成。
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation 不缓存检索到的文件名。名称提供程序微筛选器在执行中间查询以生成名称时使用此标志。

[out] RetFileNameInformation

指向调用方分配的变量的指针，该变量接收包含文件名信息的系统分配 FLT_FILE_NAME_INFORMATION 结构的地址。 FltGetDestinationFileNameInformation 从分页池分配此结构。此参数是必需的，不能为 NULL。

返回值

FltGetDestinationFileNameInformation 返回STATUS_SUCCESS或相应的 NTSTATUS 值，如以下值之一：

返回代码	说明
STATUS_FLT_INVALID_NAME_REQUEST	返回此值的原因之一是： (1) FltGetDestinationFileNameInformation 如果当前线程的 TopLevelIrp 字段不是 NULL，则无法获取文件名信息，因为生成的文件系统递归可能导致死锁或堆栈溢出。 (为 NameOptions 参数中的名称格式标志指定了 2 ) FLT_FILE_NAME_SHORT。
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation 遇到池分配失败。这是错误代码。
STATUS_INVALID_PARAMETER	为 NameOptions 参数指定了无效值。这是错误代码。
STATUS_MOUNT_POINT_NOT_RESOLVED	目标路径名称包含一个装入点，该装入点解析为文件所在的卷以外的卷。 (由于重命名或硬链接创建操作只能在卷内执行，而不能跨卷执行，因此操作将失败。) 这是错误代码。

注解

微筛选器通常在重命名或硬链接创建操作的预操作回调例程中调用 FltGetDestinationFileNameInformation，这意味着目标文件名很可能不存在。 “目标”名称为：

对于文件重命名，如果重命名成功，该文件将具有的名称。例如，将 name1 重命名为 name2 时， name2 是目标名称。
对于硬链接创建操作，将名称添加到文件系统。例如，将硬链接 名称 2 添加到名为 name1 的现有文件时， name2 是目标名称。

FltGetDestinationFileNameInformation 以规范化或“打开的文件”格式返回目标文件名信息。有关这些格式的详细信息，请参阅 FLT_FILE_NAME_INFORMATION 结构。

为 FileObject 参数传递的文件对象指针必须是操作FLT_RELATED_OBJECTS结构的 FileObject 成员或操作的 Data-Iopb-TargetFileObject>> 指针，其中 Data 是操作 (FLT_CALLBACK_DATA) 的回调数据结构。文件对象指针不能是 Data-Iopb-Parameters.SetFileInformation.FileObject>> 成员，因为此字段不会跨文件系统统一使用。

如果用户使用文件 ID 打开了文件，但没有整个路径的遍历权限， 则 FltGetDestinationFileNameInformation 仅返回用户具有权限的路径部分。

重命名或硬链接创建操作只能在卷内执行，不能跨卷执行。因此，如果目标路径名称包含解析为文件所在卷以外的卷的装入点，则此类操作将失败。有关重命名操作的详细信息，请参阅 FILE_RENAME_INFORMATION 结构。有关硬链接创建操作的详细信息，请参阅 FILE_LINK_INFORMATION 结构。

成功调用 FltGetDestinationFileNameInformation 后，调用方负责通过调用 FltReleaseFileNameInformation 不再需要指针时释放在 RetFileNameInformation 参数中返回的指针。

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

在创建、硬链接和重命名操作中，文件名隧道可能会导致规范化文件名信息中微筛选器驱动程序在预操作回调例程中检索的最终组件失效。如果微筛选器驱动程序通过调用例程（如 FltGetDestinationFileNameInformation）来检索预操作回调 (PFLT_PRE_OPERATION_CALLBACK) 例程中的规范化文件名信息，则必须从其操作后回调例程调用 FltGetTunneledName 以检索文件的正确文件名信息。

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

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

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