ZwQueryInformationFile 函式 (wdm.h)

發行項
02/27/2024

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結構。這個結構指定 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 可減少取得檔案相關信息所需的查詢數目。
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 會傳回該完整路徑。
如果 ObjectAttributes-RootDirectory> 句柄是在對 ZwCreateFile 的呼叫中以名稱開啟，且後續由 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 版本。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅一节)
DDI 合規性規則	HwStorPortProhibitedDIS (storport) 、 PowerIrpDDis (wdm)