FltQueryDirectoryFile 函式（fltkernel.h）

發行項
12/21/2024

FltQueryDirectoryFile 例程會傳回指定檔案物件所指定目錄中檔案的各種資訊。使用 FltQueryDirectoryFileEx，以取得更高的查詢控制。

語法

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

參數

[in] Instance

起始 I/O 之篩選驅動程序實例的不透明指標。

[in] FileObject

表示要掃描之目錄之檔案物件的指標。

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

[in] ReturnSingleEntry

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

[in, optional] FileName

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

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

[in] RestartScan

如果掃描要從目錄中的第一個項目開始，則設定為 TRUE。如果從上一個呼叫繼續掃描，請將設定為 FALSE。呼叫者第一次呼叫 fltQueryDirectoryFile 時，呼叫者必須將此參數設定為 TRUE。

[out, optional] LengthReturned

接收實際寫入指定 FileInformation 緩衝區的位元組數目。

傳回值

FltQueryDirectoryFile 會傳回STATUS_SUCCESS或適當的錯誤狀態。請注意，可以傳回的錯誤狀態值集合是文件系統特定的。

言論

FltQueryDirectoryFile 會傳回由 FileObject 所表示之目錄中所含檔案的相關信息。

第一次呼叫 FltQueryDirectoryFile 會根據 ReturnSingleEntry、FileName和 RestartScan的值，決定要包含在目錄中掃描所有後續呼叫的專案集。如果至少有一個相符的專案，FltQueryDirectoryFile 會針對每個專案建立FILE_XXX_INFORMATION 結構（請參閱上表），並將結構儲存至緩衝區。

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

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

在第一次呼叫 fltQueryDirectoryFile 時，如果為第一個專案建立的結構太大而無法放入輸出緩衝區，則只會傳回結構的固定部分。固定部分是由結構的所有欄位所組成，但最後 FileName 字串除外。在第一次呼叫時，I/O 系統可確保緩衝區夠大，足以保存適當FILE_XXX_INFORMATION 結構的固定部分。發生這種情況時，FltQueryDirectoryFile 會傳回適當的狀態值，例如STATUS_BUFFER_OVERFLOW。此外，在第一次呼叫 fltQueryDirectoryFile 時，如果 FileObject 目錄中沒有 符合 fileName 參數的檔案，FltQueryDirectoryFile 會傳回適當的狀態值，例如 STATUS_NO_SUCH_FILE。

在每次呼叫時，FltQueryDirectoryFile 會傳回許多FILE_XXX_INFORMATION 結構（每個目錄專案一個），完全可以包含在 fileInformation 所指向的緩衝區中。只要輸出緩衝區包含至少一個完整結構，傳回的狀態值就會STATUS_SUCCESS。不會報告任何剩餘項目的相關信息。因此，除了上述只傳回一個項目的情況下，FltQueryDirectoryFile 至少必須呼叫兩次，以列舉整個目錄的內容（例如，當 fileName 參數包含一或多個通配符或 NULL時）。

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

注意

相同目錄中多次呼叫 FltQueryDirectoryFile 時，可能會傳回資訊的項目數目小於預期。這是因為第一次呼叫 fltQueryDirectoryFile 時，目錄掃描中要包含的專案集已修正。在後續的呼叫中，FltQueryDirectoryFile 會從此相同列舉中離開的位置繼續目錄掃描。不過，在呼叫 FltQueryDirectoryFile之間，實際的目錄專案可以變更，使其不再與原始列舉同步。

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

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

FltQueryDirectoryFile 的呼叫者必須在 IRQL = PASSIVE_LEVEL 且已啟用 APC 時執行。如需詳細資訊，請參閱停用 APC。

要求

要求	價值
最低支援的用戶端	Windows Vista
目標平臺	普遍
標頭	fltkernel.h （包括 Fltkernel.h）
連結庫	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL （請參閱一節）