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。

返回值

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

注解

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

在预创建中，微筛选器使用标识所请求信息的输入 InfoClassFlags 组合对 FltRequestFileInfoOnCreateCompletion 进行一次调用。
文件系统 () 分配适当的结构，并在处理创建时填充请求的信息（如果支持）。
在创建后，微筛选器调用 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 ，则会看到这些更改。