FltRetrieveFileInfoOnCreateCompletionEx 函式 (fltkernel.h)

發行項
05/23/2024

FltRetrieveFileInfoOnCreateCompletionEx 會在檔案建立完成時查詢指定的檔案資訊。

語法

NTSTATUS FLTAPI FltRetrieveFileInfoOnCreateCompletionEx(
  [in]  PFLT_FILTER        Filter,
  [in]  PFLT_CALLBACK_DATA Data,
  [in]  ULONG              InfoClass,
  [out] PULONG             RetInfoSize,
  [out] PVOID              *RetInfoBuffer
);

參數

[in] Filter

不透明篩選指標，可唯一識別迷你篩選驅動程式。它是由 FltRegisterFilter 傳回，只要載入迷你篩選驅動程式，它就會維持不變。

[in] Data

表示 I/O 作業 之FLT_CALLBACK_DATA 回呼數據的指標。

[in] InfoClass

旗標，指出要傳回的檔案信息類型。請注意，無法合併旗標。可以是下列值之一：

旗標	意義
QoCFileStatInformation (0x00000001)	檔系統會在 QUERY_ON_CREATE_FILE_STAT_INFORMATION 結構中傳回檔案統計數據資訊。
QoCFileLxInformation (0x00000002)	文件系統會在 QUERY_ON_CREATE_FILE_LX_INFORMATION 結構中傳回類似 Linux 的擴充資訊。
QoCFileEaInformation (0x00000004)	檔系統會在 QUERY_ON_CREATE_EA_INFORMATION結構中傳回 EA) (擴充屬性。
QoCFileUsnInformation (0x00000008)	檔系統會在 QUERY_ON_CREATE_USN_INFORMATION 結構中傳回 USN 資訊。
QoCFileSecurityInformation (0x00000010)	檔系統會在 QUERY_ON_CREATE_SECURITY_INFORMATION 結構中傳回檔案安全性資訊。

[out] RetInfoSize

ULONG 的指標，該 ULONG 會接收 RetInfoBuffer 指向的緩衝區大小，以位元組為單位。

[out] RetInfoBuffer

接收所要求 InfoClass 結構的指標。如果文件系統能夠處理要求，但找不到要求的檔案資訊，此參數會設定為 NULL。

傳回值

傳回碼	Description
STATUS_SUCCESS	檔系統已成功傳回要求的檔案資訊。
STATUS_NOT_FOUND	文件系統已處理要求，但要求的資訊不存在於檔案上，或文件系統無法辨識 InfoClass 中的資訊要求。呼叫端不應該使用傳統文件系統 API 來要求資訊。
STATUS_NOT_SUPPORTED	文件系統無法擷取要求的資訊。當文件系統不支持資訊要求或相關聯的 ECP，或因為檔案預先建立期間未呼叫 FltRequestFileInfoOnCreateCompletion 時，就會發生此錯誤。呼叫端應該改用傳統的文件系統 API 來重試要求資訊。
STATUS_UNSUCCESSFUL	文件系統在嘗試擷取要求的資訊時收到錯誤。呼叫端可以嘗試透過一般文件系統 API 來要求資訊，但這可能會失敗。

備註

FltRequestFileInfoOnCreateCompletion 和 FltRetrieveFileInfoOnCreateCompletionEx 允許 minifilter 在檔案建立期間取得檔案的相關信息，因此避免稍後需要堆棧周遊的查詢效能成本。

在預先建立中，minifilter 會呼叫 FltRequestFileInfoOnCreateCompletion 與可識別要求資訊的輸入 InfoClassFlags 組合。
文件系統會配置適當的結構 (s) ，並在處理建立時填入要求的資訊。
在建立后，minifilter 會呼叫 FltRetrieveFileInfoOnCreateCompletionEx ，以取得在預先建立呼叫中要求的資訊。如果迷你篩選要求多個資訊類型，則必須針對每個資訊類型呼叫 FltRetrieveFileInfoOnCreateCompletionEx 一次。例如：


// Pre-create:
NTSTATUS status;
status = FltRequestFileInfoOnCreateCompletion( Filter,
                                               CallbackData,
                                               QoCFileStatInformation
                                                | QoCFileLxInformation
                                                | QoCFileEaInformation 
                                                | QoCFileUsnInformation );

// Post-create:
NTSTATUS status;
ULONG fileStatSize, fileLxSize, fileEaSize;
QUERY_ON_CREATE_FILE_STAT_INFORMATION* fileStatInfo;
QUERY_ON_CREATE_FILE_LX_INFORMATION* fileLxInfo;
QUERY_ON_CREATE_EA_INFORMATION* fileEaInfo;
QUERY_ON_CREATE_USN_INFORMATION* fileUsnInfo;
QUERY_ON_CREATE_SECURITY_INFORMATION* fileSecurityInfo;

status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileStatInformation,
                                                  &fileStatSize,
                                                  &fileStatInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileLxInformation,
                                                  &fileLxSize,
                                                  &fileLxInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileEaInformation, 
                                                  &fileEaSize, 
                                                  &fileEaInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileUsnInformation, 
                                                  &fileUsnInfo, 
                                                  &fileUsnInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileSecurityInformation,
                                                  &fileSecurityInfo,
                                                  &fileSecurityInfo);

FltRetrieveFileInfoOnCreateCompletionEx 傳回之後，迷你篩選程式就可以寫入 RetInfoBuffer 指向的緩衝區。在迷你篩選程式上方的任何篩選都會在修改的信息類型上呼叫 FltRetrieveFileInfoOnCreateCompletionEx 時看到變更。