NtQueryDirectoryFile 函式 （ntifs.h）
NtQueryDirectoryFile 例程會傳回指定之檔句柄所指定目錄中檔案的各種資訊。
語法
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
[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
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 來設定此參數。
[in] FileInformationClass
要傳回目錄中檔案的相關信息類型。 要傳回目錄中檔案的相關信息類型。 如需可能的值清單，請參閱 NtQueryDirectoryFileEx 的 FileInformationClass 參數。
[in] ReturnSingleEntry
如果只傳回單一專案，則設定為 true TRUE，否則 FALSE。 如果此參數 TRUE，NtQueryDirectoryFile 只會傳回找到的第一個專案。
[in, optional] FileName
呼叫端配置的 Unicode 字串的選擇性指標，其中包含檔案的名稱（如果使用通配符，則為使用通配符），FileHandle 所指定的目錄中。 這個參數是選擇性的，而且可以是 NULL。
如果 fileName 不是 NULL，則只有名稱符合 FileName 字串的檔案才會包含在目錄掃描中。 如果 fileName 為 NULL，則會包含所有檔案。
FileName 會當做搜尋表達式使用，並擷取至指定句柄 NtQueryDirectoryFile 的第一次呼叫。 NtQueryDirectoryFile 後續呼叫將會使用第一次呼叫中設定的搜尋表達式。 系統會忽略傳遞至後續呼叫 FileName 參數。
[in] RestartScan
如果掃描要從目錄中的第一個項目開始，則設定為 TRUE。 如果從上一個呼叫繼續掃描，請將 設定為 FALSE。
當針對特定句柄呼叫 NtQueryDirectoryFile 例程時，不論其值為何，RestartScan 參數都會被視為設為 true true。 在後續 NtQueryDirectoryFile 呼叫時，會接受 RestartScan 參數的值。
傳回值
NtQueryDirectoryFile例程會傳回STATUS_SUCCESS或適當的錯誤狀態。 可傳回的錯誤狀態值集合是檔案系統特定的。 NtQueryDirectoryFile也會傳回 IoStatusblockInformation 成員中實際寫入指定 FileInformation 緩衝區的位元組數目。 如需一些可能的錯誤碼清單，請參閱 NtQueryDirectoryFileEx。
言論
NtQueryDirectoryFile 例程會傳回由 FileHandle所表示之目錄中包含之檔案的相關信息。
如果提供，FileName 參數的值會決定目錄掃描中所有後續呼叫 NtQueryDirectoryFile 的專案，指定的 FileHandle。
如果至少有一個相符的專案，NtQueryDirectoryFile 會為每個專案建立 FILE_XXX_INFORMATION 結構，並將其儲存在緩衝區中。
假設找到至少一個相符的目錄項目，傳回資訊的項目數是下列專案中最小的：
- 如果 ReturnSingleEntry為 TRUE，且 fileName 為 NULL，則為一個專案。
- 如果 fileName 不是 NULL，則符合 FileName 字串的項目數目。 （請注意，如果字串不包含通配符，最多可以有一個相符的專案。
- 其資訊符合指定緩衝區的項目數。
- 目錄中所包含的項目數目。
在第一次呼叫 NtQueryDirectoryFile時，如果為找到的第一個專案所建立的結構太大而無法放入輸出緩衝區，則例程會將結構的固定部分寫入輸出緩衝區。 然後例程會寫入輸出緩衝區，如同符合的 FileName 字串。 （結構的固定部分包含所有字段，但最後 FileName 字串除外。在第一次呼叫時，I/O 系統可確保緩衝區夠大，足以保存適當 FILE_XXX_INFORMATION 結構的固定部分。發生這種情況時，NtQueryDirectoryFile 會傳回適當的狀態值，例如STATUS_BUFFER_OVERFLOW。
在每個呼叫中，NtQueryDirectoryFile 會傳回許多 FILE_XXX_INFORMATION 結構（每個目錄專案一個），完全可以包含在 fileInformation 所指向的緩衝區中。 在第一次呼叫時，只有在輸出緩衝區包含至少一個完整結構時，NtQueryDirectoryFile 才會傳回STATUS_SUCCESS。 在後續的呼叫中，如果輸出緩衝區不包含任何結構，NtQueryDirectoryFile 會傳回STATUS_SUCCESS，但會設定 IoStatusblock->Information = 0 來通知呼叫者此條件。 在此情況下，呼叫端應該配置較大的緩衝區，並再次呼叫 NtQueryDirectoryFile。 不會報告任何剩餘項目的相關信息。 因此，除了上述只傳回一個項目的情況下，NtQueryDirectoryFile 至少必須呼叫兩次，才能列舉整個目錄的內容。
呼叫 NtQueryDirectoryFile時，您可能會看到對與 NtQueryDirectoryFile 呼叫平行發生的目錄所做的變更。 此行為取決於基礎文件系統的實作。
NtQueryDirectoryFile 的最終呼叫會傳回空的輸出緩衝區，並報告適當的狀態值，例如STATUS_NO_MORE_FILES。
如果在相同目錄上呼叫 ntQueryDirectoryFile 多次，而其他作業會變更該目錄的內容，則視作業的時間而定，可能會或可能不會看到任何變更。
NtQueryDirectoryFile在文件系統不支援的 FILE_XXX_INFORMATION 結構的任何成員中傳回零。
NtQueryDirectoryFile 的呼叫者必須在 IRQL = PASSIVE_LEVEL，且 啟用特殊核心 APC。
如需其他檔案資訊查詢例程的相關信息，請參閱 File Objects。
注意
如果在使用者模式中呼叫 NtQueryDirectoryFile 函式，您應該使用名稱 “NtQueryDirectoryFile” 而不是 “ZwQueryDirectoryFile”。
針對核心模式驅動程式的呼叫，NtXXX 和 ZwXXX 版本的 Windows 原生系統服務例程，在處理和解譯輸入參數的方式上可能會有不同的行為。 如需 NtXXX 與 ZwXXX 例程版本之間的關聯性詳細資訊，請參閱 使用 Nt 和 Zw 版本的原生系統服務例程。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP |
| 目標平臺 | 普遍 |
| 標頭 | ntifs.h （include Ntifs.h） |
| 連結庫 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL （請參閱一節） |
| DDI 合規性規則 | HwStorPortProhibitedDDIs， PowerIrpDDis |