NtQueryInformationFile 函数 (ntifs.h)

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

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

[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 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标志打开文件。 此值从版本 1803 Windows 10开始可用。
FileStorageReserveIdInformation (74) FILE_STORAGE_RESERVE_ID_INFORMATION结构。
FileCaseSensitiveInformationForceAccessCheck (75) FILE_CASE_SENSITIVE_INFORMATION结构。 调用方必须已使用 DesiredAccess 参数中指定的FILE_READ_ATTRIBUTES标志打开文件。 这是 FileCaseSensitiveInformation 操作的特殊版本,用于强制 IOManager 对内核模式驱动程序执行访问检查,类似于适用于用户模式调用者的检查。 此操作仅由 IOManager 识别,文件系统不应收到它。 此值从版本 1803 Windows 10开始可用。
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 将返回完整路径。

  • 如果在调用 NtCreateFile 时使用FILE_OPEN_BY_FILE_ID标志) 的文件 ID (打开 ObjectAttributes-RootDirectory> 句柄,则 NtQueryInformationFile 随后由 NtCreateFile 相对于此根目录句柄打开该文件。

  • 但是,如果用户在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 例程的 NtXxxZwXxx 版本在处理和解释输入参数的方式可能有所不同。 有关例程 的 NtXxxZwXxx 版本之间的关系的详细信息,请参阅 使用本机系统服务例程的 Nt 和 Zw 版本

要求

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

另请参阅

FILE_ACCESS_INFORMATION

FILE_ALIGNMENT_INFORMATION

FILE_ALL_INFORMATION

FILE_ATTRIBUTE_TAG_INFORMATION

FILE_BASIC_INFORMATION

FILE_EA_INFORMATION

FILE_INTERNAL_INFORMATION

FILE_IO_PRIORITY_HINT_INFORMATION

FILE_IS_REMOTE_DEVICE_INFORMATION

FILE_MODE_INFORMATION

FILE_NAME_INFORMATION

FILE_NETWORK_OPEN_INFORMATION

FILE_POSITION_INFORMATION

FILE_STANDARD_INFORMATION

使用本机系统服务例程的 Nt 和 Zw 版本

NtCreateFile

NtQueryInformationByName

NtSetInformationFile