FltGetDestinationFileNameInformation 函数（fltkernel.h）

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

言论

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

对于文件重命名，如果重命名成功，该文件将具有的名称。例如，将 name1 重命名为 name2时，name2 是目标名称。
对于硬链接创建作，要添加到文件系统的名称。例如，将硬链接 name2 添加到名为 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后，调用方负责释放在 RetFileNameInformation 参数中返回的指针，而无需调用 FltReleaseFileNameInformation。

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

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

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

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

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