FltGetFileNameInformationUnsafe 函数（fltkernel.h）

项目
02/06/2025

FltGetFileNameInformationUnsafe 例程返回打开的文件或目录的名称信息。

语法

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

参数

[in] FileObject

指向文件或目录的文件对象的指针。文件对象当前必须处于打开状态。此参数是必需的，不能设置为 NULL。

[in, optional] Instance

调用方实例指针。此参数可以设置为 NULL。

[in] NameOptions

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

下表描述了名称格式标志值。只能指定其中一个标志。有关这些格式的详细信息，请参阅 FLT_FILE_NAME_INFORMATION。

价值	意义
FLT_FILE_NAME_NORMALIZED	FileNameInformation 参数接收包含文件的规范化名称的结构的地址。
FLT_FILE_NAME_OPENED	FileNameInformation 参数接收包含文件打开时使用的名称的结构的地址。
FLT_FILE_NAME_SHORT	FileNameInformation 参数接收包含文件的短（8.3）名称的结构的地址。短名称由最多 8 个字符组成，后跟一个句点，最多 3 个字符。文件的短名称不包括卷名称、目录路径或流名称。

下表描述了查询方法标志值。只能指定其中一个标志。

价值	意义
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe 查询筛选器管理器的名称缓存以获取文件名信息。如果在缓存中找不到该名称，FltGetFileNameInformationUnsafe 查询文件系统并缓存结果。
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe 查询筛选器管理器的名称缓存以获取文件名信息。 FltGetFileNameInformationUnsafe 不查询文件系统。
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe 查询文件系统以获取文件名信息。 FltGetFileNameInformationUnsafe 不查询筛选器管理器的名称缓存，也不会缓存文件系统查询的结果。
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformationUnsafe 查询筛选器管理器的名称缓存以获取文件名信息。如果在缓存中找不到该名称，并且目前可以安全执行此作，FltGetFileNameInformationUnsafe 查询文件系统以获取文件名信息并缓存结果。

[out] FileNameInformation

指向调用方分配的变量的指针，该变量接收系统分配FLT_FILE_NAME_INFORMATION结构的地址。 FltGetFileNameInformationUnsafe 从分页池分配此结构。不再需要此信息时，调用方必须通过调用 FltReleaseFileNameInformation释放结构。此参数是必需的，不能设置为 NULL。

返回值

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

返回代码	描述
STATUS_FLT_INVALID_NAME_REQUEST	FileObject 参数指向的文件对象当前未打开。这是一个错误代码。
STATUS_INVALID_PARAMETER	FileNameInformation 参数传递了无效值。这是一个错误代码。

言论

提供了 FltGetFileNameInformationUnsafe 例程，以便可以在该文件对象的 I/O作上下文之外查询文件对象的名称;否则，必须调用 FltGetFileNameInformation。

与 FltGetFileNameInformation 例程不同，FltGetFileNameInformationUnsafe 不会保护调用方免受以下类型的情况的影响，其中查询文件系统的名称信息可能会导致除FLT_FILE_NAME_QUERY_CACHE_ONLY以外的查询方法的死锁：

在分页 I/O 路径中。
当当前线程的 TopLevelIrp 字段未 NULL时。有关详细信息，请参阅 IoGetTopLevelIrp。
完成 IRP_MJ_CLEANUP作后;也就是说，在清理后、预关闭或关闭后路径（目标文件对象设置了FO_CLEANUP_COMPLETE标志）。
对于以下任一作，在预作（PFLT_PRE_OPERATION_CALLBACK）或作后（PFLT_POST_OPERATION_CALLBACK）回调例程中：
- IRP_MJ_ACQUIRE_FOR_CC_FLUSH
- IRP_MJ_ACQUIRE_FOR_MOD_WRITE
- IRP_MJ_RELEASE_FOR_CC_FLUSH
- IRP_MJ_RELEASE_FOR_MOD_WRITE
- IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION
在IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION的后作回调例程中。
禁用所有 APC 时;也就是说，KeAreAllApcsDisabled 返回 TRUE 时。

对于 Windows Vista/Server 2008 及更高版本，如果微筛选器尚没有筛选器实例（例如在其 DriverEntry 例程中），则可以将 NULL 用于实例参数。这允许 DriverEntry 例程访问文件名信息。除了这种情况，实例参数的 NULL 值保留供系统使用。

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

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