FltRetrieveFileInfoOnCreateCompletionEx 函式（fltkernel.h）

發行項
12/21/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 的指標，接收 RetInfoBuffer 指向的緩衝區大小，以位元組為單位。

[out] RetInfoBuffer

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

傳回值

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

言論

FltRequestFileInfoOnCreateCompletion 和 FltRetrieveFileInfoOnCreateCompletionEx 允許小型篩選程式在檔案建立期間取得檔案的相關信息，從而避免稍後需要堆棧周遊的查詢效能成本。

在預先建立中，minifilter 會呼叫 FltRequestFileInfoOnCreateCompletion 搭配輸入 InfoClassFlags 來識別要求的資訊。
文件系統會配置適當的結構，並在處理建立時填入所要求的資訊。
在建立后，迷你篩選程式會呼叫 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，則上述任何篩選都會看到變更。