NtQueryDirectoryFileEx 函式（ntifs.h）

發行項
02/07/2025

NtQueryDirectoryFileEx 例程會傳回指定之檔句柄所指定目錄中檔案的各種資訊。

語法

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

參數

[in] FileHandle

NtCreateFile 所傳回的句柄， 或 NtOpenFile，代表要求資訊之目錄的檔案物件。如果呼叫端為事件或 ApcRoutine指定非 NULL 值，則必須針對異步 I/O 開啟檔案物件。

[in, optional] Event

呼叫端所建立事件的選擇性句柄。如果提供此參數，呼叫端會進入等候狀態，直到要求作業完成，且指定的事件設定為 Signaled 狀態。這個參數是選擇性的，而且可以是 NULL。如果呼叫端將等候 FileHandle 設定為 Signaled 狀態，它必須是 NULL。

[in, optional] ApcRoutine

當要求的作業完成時，要呼叫的選擇性、呼叫端提供的 APC 例程位址。這個參數是選擇性的，而且可以是 NULL。如果有與檔案對象相關聯的 I/O 完成物件，此參數必須是 NULL。

[in, optional] ApcContext

如果呼叫端提供 APC 或 I/O 完成物件與檔案對象相關聯，則為由呼叫端決定之內容區域的選擇性指標。當作業完成時，如果已指定此內容，或包含在 I/O 管理員張貼至相關聯 I/O 完成物件的完成訊息中，就會將此內容傳遞至 APC。

這個參數是選擇性的，而且可以是 NULL。如果 ApcRoutine 為 NULL，而且沒有與檔案對象相關聯的 I/O 完成物件，它必須是 NULL。

[out] IoStatusBlock

IO_STATUS_BLOCK 結構的指標，可接收最終完成狀態和作業的相關信息。對於傳回數據的成功呼叫，會將寫入 FileInformation 緩衝區的位元元組數目傳回至結構的 Information 成員中。

[out] FileInformation

接收檔案所需信息的輸出緩衝區指標。緩衝區中傳回的信息結構是由 fileInformationClass 參數所定義。

[in] Length

FileInformation 所指向之緩衝區的大小，以位元組為單位，。呼叫端應該根據指定的 fileInformationClass 來設定此參數。

FileInformationClass

要傳回目錄中檔案的相關信息類型。要傳回目錄中檔案的相關信息類型。 FileInformationClass 可以是下列其中一個 FILE_INFORMATION_CLASS 值。

價值	意義
FileDirectoryInformation （1）	傳回每個檔案的 FILE_DIRECTORY_INFORMATION 結構。
FileFullDirectoryInformation （2）	傳回每個檔案的 FILE_FULL_DIR_INFORMATION 結構。
FileBothDirectoryInformation （3）	傳回每個檔案的 FILE_BOTH_DIR_INFORMATION 結構。
FileNamesInformation （12）	傳回每個檔案的 FILE_NAMES_INFORMATION 結構。
FileObjectIdInformation （29）	針對磁碟區上具有物件標識碼的每個檔案，傳回 FILE_OBJECTID_INFORMATION 結構。此資訊類別僅適用於 NTFS 磁碟區上的特殊目錄 “\$Extend\$ObjId：$O：$INDEX_ALLOCATION”。
FileQuotaInformation （32）	針對已套用配額的磁碟區上每個用戶，傳回單一 FILE_QUOTA_INFORMATION 結構。此資訊類別僅適用於 NTFS 磁碟區上的特殊目錄 “\$Extend\$Quota：$Q：$INDEX_ALLOCATION”。
FileReparsePointInformation （33）	針對磁碟區上具有重新分析點的每個檔案，傳回單一 FILE_REPARSE_POINT_INFORMATION 結構。此資訊類別僅適用於 NTFS 和 ReFS 磁碟區上的特殊目錄 “\$Extend\$Reparse：$R：$INDEX_ALLOCATION”。
FileIdBothDirectoryInformation （37）	傳回每個檔案的 FILE_ID_BOTH_DIR_INFORMATION 結構。
FileIdFullDirectoryInformation （38）	傳回每個檔案的 FILE_ID_FULL_DIR_INFORMATION 結構。
FileIdGlobalTxDirectoryInformation （50）	傳回每個檔案的 FILE_ID_GLOBAL_TX_DIR_INFORMATION 結構。
FileIdExtdDirectoryInformation （60）	傳回每個檔案的 FILE_ID_EXTD_DIR_INFORMATION 結構。
FileIdExtdBothDirectoryInformation （63）	傳回每個檔案的 FILE_ID_EXTD_BOTH_DIR_INFORMATION 結構。

[in] QueryFlags

SL_QUERY_DIRECTORY_MASK中包含的一或多個旗標。下表指定了可能的值。

價值	意義
SL_RESTART_SCAN （0x00000001）	掃描會從目錄中的第一個項目開始。如果未設定此旗標，掃描會從最後一個查詢結束的位置繼續。
SL_RETURN_SINGLE_ENTRY （0x00000002）	通常，傳回緩衝區會封裝成符合的相符目錄專案。如果設定此旗標，檔案系統一次只會傳回一個目錄專案。這可讓作業更有效率。
SL_INDEX_SPECIFIED （0x00000004）	掃描應該從目錄中的指定索引位置開始。只有在您產生自己的IRP_MJ_DIRECTORY_CONTROL IRP 時，才能設定此旗標;索引是在 IRP 中指定。指定位置的方式會因文件系統而異。
SL_RETURN_ON_DISK_ENTRIES_ONLY （0x00000008）	任何執行目錄虛擬化或 Just-In-Time 擴充的文件系統篩選，都應該將要求傳遞至文件系統，並傳回目前在磁碟上的專案。並非所有文件系統都支援此旗標。
SL_NO_CURSOR_UPDATE_QUERY（0x00000010）	文件系統會維護每個 FileObject 目錄資料指標資訊。當多個線程使用相同的 FileObject 執行查詢時，每個 FileObject 結構的存取都是單個線程，以防止數據指標狀態損毀。此旗標會告知文件系統不要更新每個 FileObject 資料指標狀態資訊，因此允許多個線程使用相同的句柄平行查詢。其行為就像是在每次呼叫上指定SL_RESTART_SCAN一樣。如果在下一次呼叫上指定通配符模式，則作業將不會挑選最後一個查詢結束的位置。這允許真正的異步目錄查詢支援。如果在 TxF 交易內使用此旗標，作業將會失敗。並非所有文件系統都支援此旗標。

[in, optional] FileName

呼叫端配置的 Unicode 字串的選擇性指標，其中包含檔案的名稱（如果使用通配符，則為使用通配符），FileHandle 所指定的目錄中。此參數是選擇性的：

如果 fileName 不是 NULL，則只有名稱符合 FileName 字串的檔案才會包含在目錄掃描中。
如果 fileName 為 NULL：
- 如果未在 queryFlags 中設定SL_RETURN_SINGLE_ENTRY，則會包含所有檔案。
- 如果已設定SL_RETURN_SINGLE_ENTRY，則只會包含一個檔案。

FileName 會當做搜尋表示式使用，並擷取至指定句柄 NtQueryDirectoryFileEx 的第一次呼叫。後續呼叫 NtQueryDirectoryFileEx 會使用第一次呼叫中設定的搜尋表達式。系統會忽略傳遞至後續呼叫 FileName 參數。

傳回值

NtQueryDirectoryFileEx 會傳回STATUS_SUCCESS或適當的錯誤狀態。可傳回的錯誤狀態值集合是檔案系統特定的。 NtQueryDirectoryFileEx 也會傳回 IoStatusBlockInformation 成員中實際寫入指定 FileInformation 緩衝區的位元組數目。可能的錯誤碼和原因如下：

傳回碼	意義
STATUS_BUFFER_OVERFLOW	輸出緩衝區不夠大，無法傳回完整檔名。
STATUS_BUFFER_TOO_SMALL	輸出緩衝區不夠大，至少足以容納 FileInformationClass所識別的基底結構。
STATUS_INVALID_INFO_CLASS	指定了無效 FileInformationClass，或資訊類別只適用於特殊條件（例如，僅適用於特殊目錄）。
STATUS_INVALID_PARAMETER	其中一個參數對文件系統無效。

言論

NtQueryDirectoryFileEx 會傳回 fileHandle 所表示目錄中所含檔案的相關信息。

如果提供，FileName 會決定目錄中包含的專案，以掃描所有後續呼叫 ntQueryDirectoryFileEx 指定的 FileHandle。

如果至少有一個相符的專案，NtQueryDirectoryFileEx 會為每個專案建立 FILE_XXX_INFORMATION 結構，並將其儲存在緩衝區中。

假設找到至少一個相符的目錄項目，傳回資訊的項目數是下列最小：

如果在 queryFlags 中設定 SL_RETURN_SINGLE_ENTRY一個專案，且 fileName 為 NULL，則為一個專案。
如果 fileName 不是 NULL，則符合 FileName 字串的項目數目。如果字串不包含通配符，則最多可以有一個相符的專案。
其資訊符合指定緩衝區的項目數。
目錄中所包含的項目數目。

在第一次呼叫 NtQueryDirectoryFileEx時，如果為找到的第一個專案所建立的結構太大而無法放入輸出緩衝區中，此例程會執行下列動作：

寫入結構的固定部分，以 FileInformation的輸出緩衝區。固定部分包含除 fileName 字串的最終 以外的所有欄位。在第一次呼叫時，I/O 系統可確保緩衝區夠大，足以保存適當 FILE_XXX_INFORMATION 結構的固定部分。
將寫入輸出緩衝區，如同符合的 FileName 字串。
傳回適當的狀態值，例如STATUS_BUFFER_OVERFLOW。

在每個呼叫中，NtQueryDirectoryFileEx 會傳回多達 FILE_XXX_INFORMATION 結構（每個目錄專案一個），完全可以包含在 fileInformation 所指向的緩衝區中：

在第一次呼叫時，只有在輸出緩衝區包含至少一個完整結構時，NtQueryDirectoryFileEx 才會傳回STATUS_SUCCESS。
在後續的呼叫中，如果輸出緩衝區不包含任何結構，NtQueryDirectoryFileEx 會傳回STATUS_SUCCESS，但會設定 IoStatusBlock->Information = 0 來通知呼叫者此條件。在此情況下，呼叫端應該配置較大的緩衝區，並再次呼叫 NtQueryDirectoryFileEx。不會報告任何剩餘項目的相關信息。因此，除了上述只傳回一個項目的情況下，NtQueryDirectoryFileEx 至少必須呼叫兩次，才能列舉整個目錄的內容。

呼叫 NtQueryDirectoryFileEx時，您可能會看到與 ntQueryDirectoryFileEx 呼叫平行發生的目錄變更。此行為取決於基礎文件系統的實作。

NtQueryDirectoryFileEx 的最終呼叫 會傳回空的輸出緩衝區，並報告適當的狀態值，例如STATUS_NO_MORE_FILES。

如果在相同目錄上呼叫 NtQueryDirectoryFileEx 多次，而其他一些作業會變更該目錄的內容，則視作業的時間而定，可能會或可能不會看到任何變更。

NtQueryDirectoryFileEx 傳回文件系統不支援之 FILE_XXX_INFORMATION 結構的任何成員中的零。

NtQueryDirectoryFileEx 的呼叫端必須在 IRQL = PASSIVE_LEVEL，且啟用特殊核心 APC。

如需其他檔案資訊查詢例程的相關信息，請參閱 File Objects。

注意

如果在核心模式中呼叫 NtQueryDirectoryFileEx 函式，您應該使用名稱 “ZwQueryDirectoryFileEx” 而不是 “NtQueryDirectoryFileEx”。

對於內核模式驅動程式的呼叫，NtXxx 和 ZwXxx 版本的 Windows 原生系統服務例程，在處理和解譯輸入參數的方式上可能會有不同的行為。如需 nt NtXxx 與 ZwXxx 例程之間關聯性的詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

要求

要求	價值
最低支援的用戶端	Windows 10 版本 1709
標頭	ntifs.h
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL （請參閱一節）