NtQueryInformationFile 函数 (ntifs.h)

项目
07/11/2023

NtQueryInformationFile 例程返回有关文件对象的各种信息。另请参阅 NtQueryInformationByName，它可以更有效地用于一些文件信息类。

语法

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

参数

[in] FileHandle

文件对象的句柄。句柄是通过成功调用 NtCreateFile 或 NtOpenFile 或等效文件创建或打开例程创建的。

[out] IoStatusBlock

指向接收最终完成状态和操作相关信息的 IO_STATUS_BLOCK 结构的指针。 Information 成员接收此例程实际写入 FileInformation 缓冲区的字节数。

[out] FileInformation

指向调用方分配的缓冲区的指针，例程将请求的有关文件对象的信息写入其中。 FileInformationClass 参数指定调用方请求的信息类型。

[in] Length

FileInformation 指向的缓冲区的大小（以字节为单位）。

[in] FileInformationClass

指定要在 FileInformation 指向的缓冲区中返回的有关文件的信息类型。设备和中间驱动程序可以指定以下任一FILE_INFORMATION_CLASS 值 (从低到高列出枚举值) ：

FILE_INFORMATION_CLASS值	返回的信息类型
FileBasicInformation (4)	FILE_BASIC_INFORMATION结构。调用方必须已使用 DesiredAccess 参数中指定的FILE_READ_ATTRIBUTES标志打开文件。
FileStandardInformation (5)	FILE_STANDARD_INFORMATION结构。只要文件处于打开状态，调用方就可以查询此信息，而对 DesiredAccess 没有任何特定要求。
FileInternalInformation (6)	FILE_INTERNAL_INFORMATION结构。此结构指定唯一标识 NTFS 中的文件的 64 位文件 ID。在其他文件系统上，此文件 ID 不保证是唯一的。
FileEaInformation (7)	FILE_EA_INFORMATION结构。此结构指定与文件关联的扩展属性块的大小。
FileAccessInformation (8)	FILE_ACCESS_INFORMATION结构。此结构包含访问掩码。有关访问掩码的详细信息，请参阅 ACCESS_MASK。
FileNameInformation (9)	FILE_NAME_INFORMATION结构。结构可以包含文件的完整路径，也可以只包含文件的一部分。只要文件处于打开状态，调用方就可以查询此信息，而对 DesiredAccess 没有任何特定要求。有关文件名语法的详细信息，请参阅本主题后面的“备注”部分。
FilePositionInformation (14)	FILE_POSITION_INFORMATION结构。调用方必须已使用 DesiredAccess 参数中指定的 DesiredAccess FILE_READ_DATA 或 FILE_WRITE_DATA 标志以及 CreateOptions 参数中指定的FILE_SYNCHRONOUS_IO_ALERT或FILE_SYNCHRONOUS_IO_NONALERT标志打开文件。
FileModeInformation (16)	FILE_MODE_INFORMATION结构。此结构包含一组标志，这些标志指定访问文件的模式。这些标志是可在 IoCreateFile 例程的 CreateOptions 参数中指定的选项的子集。
FileAlignmentInformation (17)	FILE_ALIGNMENT_INFORMATION结构。只要文件处于打开状态，调用方就可以查询此信息，而对 DesiredAccess 没有任何特定要求。如果文件是使用 CreateOptions 参数中指定的FILE_NO_INTERMEDIATE_BUFFERING标志打开的，则此信息非常有用。
FileAllInformation (18)	FILE_ALL_INFORMATION结构。通过将多个文件信息结构合并到单个结构中， FILE_ALL_INFORMATION 可以减少获取有关文件的信息所需的查询数。
FileAlternateNameInformation (21)	一种FILE_ALL_INFORMATION结构，用于返回文件的备用名称信息， (其 8.3 格式名称) 。
FileStreamInformation (22)	FILE_STREAM_INFORMATION 结构的缓冲区，用于枚举文件或目录的数据流。
FileCompressionInformation (28)	一个FILE_COMPRESSION_INFORMATION结构，用于返回文件的压缩信息。
FileNetworkOpenInformation (34)	FILE_NETWORK_OPEN_INFORMATION结构。调用方必须已使用 DesiredAccess 参数中指定的FILE_READ_ATTRIBUTES标志打开文件。
FileAttributeTagInformation (35)	FILE_ATTRIBUTE_TAG_INFORMATION结构。调用方必须已使用 DesiredAccess 参数中指定的FILE_READ_ATTRIBUTES标志打开文件。
FileIoPriorityHintInformation (43)	FILE_IO_PRIORITY_HINT_INFORMATION结构。调用方必须已使用 DesiredAccess 参数中指定的FILE_READ_DATA标志打开文件。
FileSfioReserveInformation (44)	FILE_SFIO_RESERVE_INFORMATION结构。
FileHardLinkInformation (46)	FILE_LINKS_INFORMATION结构。
FileNormalizedNameInformation (48)	一个FILE_NAME_INFORMATION结构，在其中返回文件的规范化名称。
FileIsRemoteDeviceInformation (51)	FILE_IS_REMOTE_DEVICE_INFORMATION结构。只要文件处于打开状态，调用方就可以查询此信息，而对 DesiredAccess 没有任何特定要求。
FileStandardLinkInformation (54)	FILE_STANDARD_LINK_INFORMATION结构。
FileIdInformation (59)	FILE_ID_INFORMATION结构。
FileDesiredStorageClassInformation (67)	FILE_DESIRED_STORAGE_CLASS_INFORMATION结构。
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	FILE_CASE_SENSITIVE_INFORMATION结构。调用方必须已使用 DesiredAccess 参数中指定的FILE_READ_ATTRIBUTES标志打开文件。此值从 Windows 10 版本 1803 开始可用。
FileStorageReserveIdInformation (74)	FILE_STORAGE_RESERVE_ID_INFORMATION结构。
FileCaseSensitiveInformationForceAccessCheck (75)	FILE_CASE_SENSITIVE_INFORMATION结构。调用方必须已使用 DesiredAccess 参数中指定的FILE_READ_ATTRIBUTES标志打开文件。这是 FileCaseSensitiveInformation 操作的特殊版本，用于强制 IOManager 对内核模式驱动程序执行访问检查，类似于适用于用户模式调用者的检查。此操作仅由 IOManager 识别，文件系统永远不应收到它。此值从 Windows 10 版本 1803 开始可用。
FileKnownFolderInformation (76)	FILE_KNOWN_FOLDER_INFORMATION 结构。从 Windows Server 2022 开始可用。

返回值

NtQueryInformationFile 返回STATUS_SUCCESS或相应的 NTSTATUS 错误代码。

注解

NtQueryInformationFile 返回有关指定文件对象的信息。请注意，它在特定设备或文件系统不支持的 FILE_XXX_INFORMATION 结构的任何成员中返回零。

当 FileInformationClass = FileNameInformation 时，文件名在 FILE_NAME_INFORMATION 结构中返回。文件名的精确语法取决于多种因素：

如果通过提交 NtCreateFile 的完整路径打开了文件， 则 NtQueryInformationFile 将返回该完整路径。
如果在调用 NtCreateFile 时按名称打开 ObjectAttributes-RootDirectory> 句柄，并且随后 NtCreateFile 相对于此根目录句柄打开了文件，则 NtQueryInformationFile 返回完整路径。
如果 ObjectAttributes-RootDirectory> 句柄由文件 ID (在对 NtCreateFile 的调用中使用FILE_OPEN_BY_FILE_ID标志) 打开，并且随后 NtCreateFile 相对于此根目录句柄打开了该文件，则 NtQueryInformationFile 将返回相对路径。
但是，如果用户具有 Microsoft Windows SDK 文档) 中描述的 SeChangeNotifyPrivilege (，则 NtQueryInformationFile 在所有情况下都返回完整路径。
如果仅返回相对路径，则文件名字符串不会以反斜杠开头。
如果返回完整路径和文件名，则字符串将以单个反斜杠开头，而不考虑其位置。因此，文件 C：\dir1\dir2\filename.ext 将显示为 \dir1\dir2\filename.ext，而文件 \server\share\dir1\dir2\filename.ext 将显示为 \server\share\dir1\dir2\filename.ext。

如果 NtQueryInformationFile 因缓冲区溢出而失败，实现 FileNameInformation 的驱动程序应返回缓冲区中容纳的文件名的 WCHAR 字符数，并指定FILE_NAME_INFORMATION结构的 FileNameLength 参数中所需的完整长度。应使用文件名长度重新发出查询，以便检索完整文件名。不遵循此模式的驱动程序可能需要逐步增加长度，直到检索完整文件名。有关使用文件的详细信息，请参阅在驱动程序中使用文件。

NtQueryInformationFile 的调用方必须在 IRQL = PASSIVE_LEVEL 运行，并且启用了特殊内核 APC。

注意

如果在用户模式下调用此函数，则应使用名称“NtQueryInformationFile”而不是“ZwQueryInformationFile”。

对于来自内核模式驱动程序的调用，Windows Native System Services 例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求	值
最低受支持的客户端	Windows 2000。
目标平台	通用
标头	ntifs.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅“备注”部分)
DDI 符合性规则	HwStorPortProhibitedDDI、PowerIrpDDis