FltGetFileNameInformationUnsafe 函数 (fltkernel.h)

项目
02/29/2024

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 例程中），则可以将其用于 NULLInstance 参数。这允许 DriverEntry 例程访问文件名信息。除这种情况外， NULL 实例参数的值保留供系统使用。

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

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