ZwQueryDirectoryFile 函式（ntifs.h）

發行項
12/21/2024

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

語法

NTSYSAPI NTSTATUS ZwQueryDirectoryFile(
  [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,
  [in]           FILE_INFORMATION_CLASS FileInformationClass,
  [in]           BOOLEAN                ReturnSingleEntry,
  [in, optional] PUNICODE_STRING        FileName,
  [in]           BOOLEAN                RestartScan
);

參數

[in] FileHandle

ZwCreateFile 或 ZwOpenFile 所傳回的句柄，代表所要求資訊的目錄。如果呼叫端為事件或 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。如果 ApcRoutineNULL，而且沒有與檔案對象相關聯的 I/O 完成物件，則必須 NULL。

[out] IoStatusBlock

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

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

要傳回目錄中檔案的相關信息類型。如需可能的值清單，請參閱 NtQueryDirectoryFileEx 的 FileInformationClass 參數。

[in] ReturnSingleEntry

如果只傳回單一專案，則設定為 true TRUE，否則 FALSE。如果此參數 TRUE，ZwQueryDirectoryFile 只會傳回找到的第一個專案。

[in, optional] FileName

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

如果 fileName 不是 NULL，則只會在目錄掃描中包含名稱符合 FileName 字串的檔案。
如果 fileName NULL，則如果 returnSingleEntry 為 FALSE，則會包含所有檔案;如果 returnSingleEntry TRUE，則會包含一個檔案。

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

[in] RestartScan

如果掃描要從目錄中的第一個項目開始，則設定為 TRUE。如果從上一個呼叫繼續掃描，請將設定為 FALSE。

當特定句柄呼叫 ZwQueryDirectoryFile 例程時，不論其值為何，RestartScan 參數都會被視為設定為 true TRUE。在後續 ZwQueryDirectoryFile 呼叫時，會接受 RestartScan 參數的值。

傳回值

ZwQueryDirectoryFile 例程會傳回STATUS_SUCCESS或適當的錯誤狀態。可傳回的錯誤狀態值集合是檔案系統特定的。 ZwQueryDirectoryFile 也會傳回 IoStatusBlockInformation 成員中實際寫入指定 之 fileInformation 緩衝區的位元組數目。如需一些可能的錯誤碼清單，請參閱 NtQueryDirectoryFileEx。

言論

ZwQueryDirectoryFile 例程會傳回由 fileHandle所代表之目錄中所含檔案的相關信息。

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

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

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

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

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

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

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

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

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

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

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

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

ZwQueryDirectoryFile 的呼叫者必須在 IRQL = PASSIVE_LEVEL 且啟用特殊核心 APC。

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

注意

如果在使用者模式中呼叫 ZwQueryDirectoryFile 函式，您應該使用名稱 “NtQueryDirectoryFile” 而不是 “ZwQueryDirectoryFile”。

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

要求

要求	價值
最低支援的用戶端	Windows XP。
目標平臺	普遍
標頭	ntifs.h （include Ntifs.h）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL （請參閱一節）
DDI 合規性規則	HwStorPortProhibitedDIs（storport），PowerIrpDDis（wdm）