ZwQueryInformationFile 函数 (wdm.h)

项目
08/08/2023

ZwQueryInformationFile 例程返回有关文件对象的各种信息。

语法

NTSYSAPI NTSTATUS ZwQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

参数

[in] FileHandle

文件对象的句柄。句柄是通过成功调用 ZwCreateFile 或 ZwOpenFile 创建的。

[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 可以减少获取有关文件的信息所需的查询数。
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标志打开文件。
FileIsRemoteDeviceInformation (51)	FILE_IS_REMOTE_DEVICE_INFORMATION结构。只要文件处于打开状态，调用方就可以查询此信息，而对 DesiredAccess 没有任何特定要求。
FileKnownFolderInformation (76)	FILE_KNOWN_FOLDER_INFORMATION结构。从 Windows Server 2022 开始可用。

返回值

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

注解

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

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

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

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

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

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

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

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅备注部分)
DDI 符合性规则	HwStorPortProhibitedDDI (storport) 、 PowerIrpDDis (wdm)