ZwQueryDirectoryFile 函式 (ntifs.h)

發行項
02/27/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 所傳回的句柄，代表要求資訊之目錄的檔案物件。如果呼叫端為 Event 或 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 結構的指標。對於傳回數據的成功呼叫，會在結構的 Information 成員中傳回寫入 FileInformation 緩衝區的位元組數目。

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

[in] ReturnSingleEntry

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

[in, optional] FileName

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

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

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

[in] RestartScan

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

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

傳回值

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

備註

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

如果提供，FileName 會針對指定的 FileHandle 判斷目錄掃描中所包含的專案，以搜尋所有後續對 ZwQueryDirectoryFile 的呼叫。

如果至少有一個相符的專案， 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 時執行。

如需其他檔案資訊查詢例程的資訊，請參閱檔案物件。

注意

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

針對來自內核模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本會以處理和解譯輸入參數的方式，以不同的方式運作。如需 例程 NtXxx 和 ZwXxx 版本之間關聯性的詳細資訊，請參閱使用原生系統服務例程的 Nt 和 Zw 版本。

規格需求

需求	值
最低支援的用戶端	Windowsxp。
目標平台	Universal
標頭	ntifs.h (包含 Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅一节)
DDI 合規性規則	HwStorPortProhibitedDIS (storport) 、 PowerIrpDDis (wdm)