FltQueryDirectoryFileEx 函式（fltkernel.h）

發行項
07/16/2024

FltQueryDirectoryFileEx 會傳回指定檔案物件所指定目錄中檔案的各種資訊。

語法

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

參數

Instance

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

FileObject

代表所查詢目錄之檔案物件的指標。

FileInformation

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

Length

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

FileInformationClass

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

QueryFlags

SL_QUERY_DIRECTORY_MASK中包含的一或多個旗標。下表指定了可能的值。

價值	意義
SL_RESTART_SCAN （0x00000001）	如果設定此旗標，掃描會從目錄中的第一個項目開始。如果未設定此旗標，掃描會從最後一個查詢結束的位置繼續。
SL_RETURN_SINGLE_ENTRY （0x00000002）	通常，傳回緩衝區會封裝成符合的相符目錄專案。如果設定此旗標，檔案系統一次只會傳回一個目錄專案。這可讓作業更有效率。
SL_INDEX_SPECIFIED （0x00000004）	如果設定此旗標，掃描應該從目錄中的指定索引位置開始。只有在您產生自己的 IRP IRP_MJ_DIRECTORY_CONTROL時，才能設定此旗標;索引是在 IRP 中指定。指定位置的方式會因文件系統而異。
SL_RETURN_ON_DISK_ENTRIES_ONLY （0x00000008）	如果已設定此旗標，則執行目錄虛擬化或 Just-In-Time 擴充的任何文件系統篩選應該只要將要求傳遞至文件系統，並傳回目前在磁碟上的專案。並非所有文件系統都支援此旗標。
SL_NO_CURSOR_UPDATE_QUERY（0x00000010）	文件系統會維護每個FileObject 目錄數據指標資訊。當多個線程使用相同的 FileObject進行查詢時，會以單個線程方式存取 per-FileObject 結構，以防止數據指標狀態損毀。此旗標會指示文件系統不要更新每個FileObject 數據指標狀態資訊，因此允許多個線程使用相同的句柄平行查詢。其行為就像是在每次呼叫上指定SL_RESTART_SCAN一樣。如果在下一次呼叫上指定通配符模式，則作業將不會挑選最後一個查詢結束的位置。這允許真正的異步目錄查詢支援。如果在 TxF 交易內使用此旗標，作業將會失敗。並非所有文件系統都支援此旗標。

FileName

呼叫端配置的 UNICODE_STRING 結構的指標，其中包含檔案名稱的 Unicode 字串，如果已使用通配符，則會在 fileObject 所指定的目錄中。這個參數是選擇性的，而且可以 NULL。如果 fileName NULL，則會包含所有檔案。

如果 fileName 不是 NULL，則只會在目錄掃描中包含名稱符合 FileName 字串的檔案。如果已設定 QueryFlagsResetScan 旗標，則會忽略 fileName 的值。

LengthReturned

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

傳回值

FltQueryDirectoryFileEx 會傳回STATUS_SUCCESS或適當的錯誤碼。可傳回的錯誤狀態值集合是檔案系統特定的。

言論

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

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

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

如果 QueryFlags 中設定了SL_RETURN_SINGLE_ENTRY旗標，且 fileName NULL中設定一個專案。
如果 fileName 未 NULL，則符合 fileName 字串的項目數目。（請注意，如果字串不包含通配符，最多可以有一個相符的專案。
資訊符合 FileInformation 所指向之緩衝區的項目數，。
目錄中所包含的項目數目。

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

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

FltQueryDirectoryFileEx 的最終呼叫 會傳回空的輸出緩衝區，並報告STATUS_NO_MORE_FILES的非錯誤狀態值。

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

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

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