fltQueryDirectoryFile 函式 (fltkernel.h)

發行項
02/26/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 ，否則為 FALSE 。如果此參數為 TRUE，FltQueryDirectoryFile 只會傳回找到的第一個專案。

[in, optional] FileName

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

如果 FileName 不是 NULL，則只有名稱符合 FileName 字串的檔案會包含在目錄掃描中。如果 FileName 為 NULL，則會包含所有檔案。如果 RestartScan 為 FALSE， 則會忽略 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 字串的項目數。 (請注意，如果字串不包含通配符，最多可以有一個相符的 entry.)
資訊符合指定緩衝區的項目數。
目錄中所包含的項目數目。

在第一次呼叫 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結構。

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

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

規格需求

需求	值
最低支援的用戶端	Windows Vista
目標平台	Universal
標頭	fltkernel.h (包含 Fltkernel.h)
程式庫	FltMgr.lib
Dll	Fltmgr.sys
IRQL	PASSIVE_LEVEL (请参阅一节)