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

指向接收 RetInfoBuffer 指向的缓冲区大小的 ULONG 的指针。

[out] RetInfoBuffer

接收指向所请求 InfoClass 结构的指针。如果文件系统能够处理请求，但找不到请求的文件信息，则此参数设置为 NULL。

返回值

返回代码	描述
STATUS_SUCCESS	文件系统已成功返回请求的文件信息。
STATUS_NOT_FOUND	文件系统处理了请求，但文件中没有请求的信息，或者文件系统无法识别 InfoClass中的信息请求。调用方不应使用传统的文件系统 API 来请求信息。
STATUS_NOT_SUPPORTED	文件系统无法检索请求的信息。如果文件系统不支持信息请求或关联的 ECP，或者由于在文件预创建期间未调用 FltRequestFileInfoOnCreateCompletion，则会发生此错误。调用方应改用传统的文件系统 API 来重试请求信息。
STATUS_UNSUCCESSFUL	文件系统在尝试检索请求的信息时收到错误。调用方可以通过正常的文件系统 API 尝试请求信息，但这很可能失败。

言论

FltRequestFileInfoOnCreateCompletion 和 FltRetrieveFileInfoOnCreateCompletionEx 允许微型筛选器在创建文件时获取有关文件的信息，从而避免了稍后需要堆栈遍历的查询的性能成本。

在预创建中，微型筛选器调用 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，则上述任何筛选器都将看到更改。