fltAllocateExtraCreateParameterList 函数 (fltkernel.h)

项目
02/29/2024

FltAllocateExtraCreateParameterList 例程为额外的创建参数分配分页池内存 (ECP) 列表结构，并生成指向该结构的指针。

语法

NTSTATUS FLTAPI FltAllocateExtraCreateParameterList(
  [in]  PFLT_FILTER                  Filter,
  [in]  FSRTL_ALLOCATE_ECPLIST_FLAGS Flags,
  [out] PECP_LIST                    *EcpList
);

参数

[in] Filter

微筛选器驱动程序的不透明筛选器指针。此指针唯一标识微筛选器驱动程序，只要加载微筛选器驱动程序，它就保持不变。

[in] Flags

定义池分配选项。如果使用按位 OR 操作将 FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA 标志与 Flags 参数组合，则例程分配的任何池都将根据当前进程的内存配额收费。

[out] EcpList

接收指向已初始化的 ECP 列表结构的指针。如果例程未能分配足够的池， 则 *EcpList 将为 NULL ，并且例程将返回状态代码STATUS_INSUFFICIENT_RESOURCES。

返回值

FltAllocateExtraCreateParameterList 可以返回以下值之一：

返回代码	说明
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameterList 无法为 ECP 列表结构分配足够的内存。在这种情况下， EcpList 将为 NULL*。
STATUS_SUCCESS	已成功分配并初始化 ECP 列表结构。在这种情况下，将在 *EcpList 参数中返回指向已初始化列表结构的指针。

注解

操作系统是否自动释放 FltAllocateExtraCreateParameterList 分配的内存取决于何时调用 FltAllocateExtraCreateParameterList ，如以下情况所示：

调用方可以调用 FltAllocateExtraCreateParameterList 来分配ECP_LIST，并在调用方调用 FltCreateFileEx2 例程之前添加一个或多个 ECP 上下文结构。在这种情况下，操作系统不会释放任何 ECP 上下文结构。因此，调用方可以使用相同的 ECP 集对 FltCreateFileEx2 进行多次调用。调用方完成ECP_LIST后，调用方必须调用 FltFreeExtraCreateParameterList 例程来释放ECP_LIST。
文件系统筛选器驱动程序处理 IRP_MJ_CREATE 请求时，文件系统筛选器驱动程序可以调用 FltInsertExtraCreateParameter 将 ECP 附加到现有ECP_LIST。如果ECP_LIST不存在，则调用方必须调用 FltAllocateExtraCreateParameterList 来创建ECP_LIST。在这种情况下，创建操作完成后，I/O 管理器会自动清理ECP_LIST和 ECP 上下文结构。这允许筛选器驱动程序的 ECP 在重新分析点的处理过程中正确传播。此过程可能需要生成多个IRP_MJ_CREATE请求。

如果FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA标志与 Flags 参数一起使用，如上所述，则会分配一个普通的可分页池。否则，将使用内部查看列表分配可分页池。

ECP_LIST 结构

ECP_LIST是操作系统声明的不透明结构。 ECP_LIST包含 ECP) 条目 (额外创建参数的列表。

FltAllocateExtraCreateParameterList 例程必须用于为ECP_LIST结构分配内存。 FltAllocateExtraCreateParameterList 分配的内存不会由操作系统自动释放;它必须通过调用 FltFreeExtraCreateParameterList 例程显式解除分配。请注意，调用 FltFreeExtraCreateParameterList 时，将自动释放任何剩余的 ECP 列表元素。

PECP_LIST数据类型用于声明指向 ECP_LIST 类型的变量的指针。

语法

struct ECP_LIST {
  ;      // Reserved.
};

ECP_LIST 结构在 Ntifs.h 中声明， (包括 Ntifs.h) 。

要求

要求	值
最低受支持的客户端	此例程从 Windows Vista 开始可用。
目标平台	通用
标头	fltkernel.h (包括 Fltkernel.h)
Library	FltMgr.lib
IRQL	<= APC_LEVEL