FltAllocateContext 函数（fltkernel.h）

项目
02/06/2025

FltAllocateContext 例程为指定的上下文类型分配上下文结构。

语法

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

参数

[in] Filter

调用方不透明筛选器指针。此参数是必需的，不能 NULL。

[in] ContextType

指示要分配的上下文类型的 FLT_CONTEXT_TYPE 值。 ContextType 可以是下列项之一：

价值	意义
FLT_VOLUME_CONTEXT（0x0001）	分配卷上下文。
FLT_INSTANCE_CONTEXT（0x0002）	分配实例上下文。
FLT_FILE_CONTEXT （0x0004）	分配文件上下文。
FLT_STREAM_CONTEXT（0x0008）	分配流上下文。
FLT_STREAMHANDLE_CONTEXT（0x0010）	分配流句柄上下文。
FLT_TRANSACTION_CONTEXT（0x0020）	分配事务上下文。
FLT_SECTION_CONTEXT（0x0040）	分配节上下文。从 Windows 8 开始可用。

[in] ContextSize

由微型筛选器驱动程序定义的上下文部分的大小（以字节为单位）。必须大于零且小于或等于 MAXUSHORT;对于固定大小上下文，必须小于或等于 FLT_CONTEXT_REGISTRATION 结构中指定的大小。微型筛选器使用此上下文部分来维护特定于自身的上下文信息。 FltMgr 将上下文结构的这一部分视为不透明。此参数是必需的，不能为零。

[in] PoolType

要分配的池的类型。此参数是必需的，必须满足以下条件之一。有关每种类型的详细说明，请参阅 POOL_TYPE。有关详细信息，请参阅“备注”。

价值	意义
NonPagedPool	不可分页的系统内存。如果FLT_VOLUME_CONTEXT ContextType，则必须 NonPagedPoolPoolType。
PagedPool	可分页的系统内存。
NonPagedPoolNx	无执行（NX）非分页池。

[out] ReturnedContext

指向接收新分配上下文地址的调用方分配变量的指针。调用方负责调用 FltReleaseContext，以便在不再需要此上下文时释放此上下文。

返回值

FltAllocateContext 返回 STATUS_SUCCESS 或相应的 NTSTATUS 值，例如以下值之一：

返回代码	描述
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	筛选器注册时未提供指定类型的上下文的分配信息。或者，对于固定大小的上下文，所请求的 ContextSize 大于指定 ContextType的 FLT_CONTEXT_REGISTRATION 结构中指定的大小。
STATUS_FLT_DELETING_OBJECT	Filter 参数中指定的微型筛选器驱动程序正在被拆毁。这是一个错误代码。
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext 遇到池分配失败。这是一个错误代码。
STATUS_INVALID_BUFFER_SIZE	ContextSize 不能大于 MAXUSHORT。这是一个错误代码。
STATUS_INVALID_PARAMETER	为 ContextType 或 ContextSize 参数指定了无效值。这是一个错误代码。
STATUS_NOT_SUPPORTED	文件系统不支持每个流上下文。这是一个错误代码。

言论

有关上下文的详细信息，请参阅关于小型筛选器上下文。

FltAllocateContext 从指定池中分配指定类型的上下文。从 Windows 11 开始，ReturnedContext 指向的内存是否为零取决于如下所示：

对于可变大小的上下文，内存保证为零。
内存内容是针对由调用方提供的回调函数分配的固定大小的上下文定义的实现。
否则，由于外观列表行为，无法假定为固定大小的上下文将内存归零。也就是说，如果从 lookaside 列表返回的条目是以前释放到查找列表的内存而不是新的分配，则它可能不会为零。

在 Windows 11 之前，返回的上下文的内容不会为零。

PoolType 设置为无效值可能会导致意外行为，例如导致旁观列表被绕过，从而导致外观列表的性能优势丢失。对于具有 ContextAllocateCallback 回调函数的上下文，由于 poolType 无效而导致的行为依赖于实现。

分配上下文后，可以通过将 returnedContext 指针传递给下表中的相应 set-context 例程来设置该对象。

上下文类型	Set-Context 例程
FLT_FILE_CONTEXT	FltSetFileContext （从 Windows Vista 开始）
FLT_INSTANCE_CONTEXT	FltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan（从 Windows 8 开始）
FLT_STREAM_CONTEXT	FltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltSetTransactionContext（从 Windows Vista 开始）
FLT_VOLUME_CONTEXT	FltSetVolumeContext

当微型筛选器驱动程序从其 DriverEntry 例程调用 FltRegisterFilter 时，它必须注册它使用的每个上下文类型。有关详细信息，请参阅 FLT_CONTEXT_REGISTRATION 结构的参考条目，以及注册上下文类型。

FltAllocateContext 不会初始化特定于微型筛选器驱动程序的上下文结构部分的内容。

若要获取对象的上下文，请从下表中调用 FltGetContexts 或适当的 get-context 例程。

上下文类型	Get-Context 例程
FLT_FILE_CONTEXT	FltGetFileContext （从 Windows Vista 开始）
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext（从 Windows 8 开始）
FLT_STREAM_CONTEXT	FltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext（从 Windows Vista 开始）
FLT_VOLUME_CONTEXT	FltGetVolumeContext

上下文是引用计数的，在 FltAllocateContext成功返回时，ReturnedContext 所指向的上下文已初始化为引用计数为 1。当上下文的引用计数达到零时，会自动释放上下文。若要递增上下文的引用计数，请调用 FltReferenceContext。

若要递减上下文的引用计数，请调用 FltReleaseContext。

由于上下文是引用计数的，因此通常不需要删除它们。若要显式删除上下文，请从下表中调用 FltDeleteContext 或适当的 delete-context 例程。

上下文类型	Delete-Context 例程
FLT_FILE_CONTEXT	FltDeleteFileContext（从 Windows Vista 开始）
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan（从 Windows 8 开始）
FLT_STREAM_CONTEXT	FltDeleteStreamContext
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext （从 Windows Vista 开始）
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext