FltQueryDirectoryFileEx 函式 (fltkernel.h)

發行項
02/27/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_MJ_DIRECTORY_CONTROL IRP 時，才能設定此旗標;索引是在 IRP 中指定。指定位置的方式會因文件系統而異。
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	如果設定此旗標，任何執行目錄虛擬化或 Just-In-Time 擴充的文件系統篩選，都應該直接將要求傳遞至文件系統，並傳回目前在磁碟上的專案。並非所有文件系統都支援此旗標。
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	文件系統會維護每個 FileObject 目錄資料指標資訊。當多個線程使用相同的 FileObject 執行查詢時，每個 FileObject 結構的存取是單個線程，以防止數據指標狀態損毀。此旗標會告知文件系統不要更新每個 FileObject 資料指標狀態資訊，因此允許多個線程使用相同的句柄平行查詢。其行為就像是在每次呼叫上指定SL_RESTART_SCAN一樣。如果在下一次呼叫時指定通配符模式，作業將不會挑選最後一個查詢結束的位置。這允許真正的異步目錄查詢支援。如果在 TxF 交易內使用此旗標，作業將會失敗。並非所有文件系統都支援此旗標。

FileName

如果通配符是在 FileObject 所指定的目錄中) 使用通配符，則為呼叫端配置的UNICODE_STRING結構指標，其中包含檔案 (或多個檔名的 Unicode 字符串。這個參數是選擇性的，而且可以是 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 字串的項目數。 (請注意，如果字串不包含通配符，最多可以有一個相符的 entry.)
資訊符合 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且已啟用 ABC 時執行。如需詳細資訊，請參閱停用 APC。