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結構。 這個結構指定 64 位檔案識別碼,可唯一識別 NTFS 中的檔案。 在其他檔案系統上,此檔案識別碼不保證是唯一的。
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 或 desiredAccess 參數中指定的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 辨識,而且檔案系統絕對不會收到。 此值從 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會傳回完整路徑。

  • 如果 ObjectAttributes-RootDirectory > 控制碼是以檔案識別碼開啟, (使用 FILE_OPEN_BY_FILE_ID對 NtCreateFile的呼叫) ) ,然後 NtCreateFile 會相對於這個根目錄控制碼開啟該檔案, NtQueryInformationFile 會傳回相對路徑。

  • 不過,如果使用者有SeChangeNotifyPrivilege (Microsoft Windows SDK檔) 中所述,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 原生系統服務常式的NtXxxZwXxx版本會以處理和解譯輸入參數的方式,以不同的方式運作。 如需常式 NtXxxZwXxx版本之間關聯性的詳細資訊,請參閱使用原生系統服務常式的 Nt 和 Zw 版本

必要條件

   
最低支援的用戶端 從 Windows 2000 開始提供。
目標平臺 環球
標頭 ntifs.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 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