共用方式為

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 針對檔案物件所傳回的句柄，代表要求資訊之目錄。 如果呼叫端為 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，NtQueryDirectoryFile 只會傳回找到的第一個專案。

[in, optional] FileName

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

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

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

[in] RestartScan

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

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

傳回值

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

備註

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

如果提供，FileName 參數的值會決定目錄中針對指定 FileHandle 對 NtQueryDirectoryFile 的所有後續呼叫所包含的專案。

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

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

  • 如果 ReturnSingleEntry 為 TRUE ，且 FileName 為 NULL，則為一個專案。
  • 如果 FileName 不是 NULL，則為符合 FileName 字串的項目數。 (請注意，如果字串不包含通配符，最多可以有一個相符的 entry.)
  • 資訊符合指定緩衝區的項目數。
  • 目錄中所包含的項目數目。

在第一次呼叫 NtQueryDirectoryFile 時，如果為找到的第一個專案所建立的結構太大而無法放入輸出緩衝區，則例程會將結構的固定部分寫入輸出緩衝區。 然後，例程會寫入輸出緩衝區，如同符合的 FileName 字串。 (結構的固定部分是由最後的 FileName 字串以外的所有欄位所組成。在第一次呼叫時，而不是在後續呼叫時，I/O 系統會確保緩衝區夠大，足以保存適當FILE_XXX的固定部分_INFORMATION structure.) 發生這種情況時，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 時執行。

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

注意

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

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

規格需求

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

另請參閱

FILE_BOTH_DIR_INFORMATION

FILE_DIRECTORY_INFORMATION

FILE_FULL_DIR_INFORMATION

FILE_ID_BOTH_DIR_INFORMATION

FILE_ID_FULL_DIR_INFORMATION

FILE_NAMES_INFORMATION

FILE_OBJECTID_INFORMATION

FILE_REPARSE_POINT_INFORMATION

IO_STATUS_BLOCK

UNICODE_STRING

NtCreateFile

NtOpenFile