fltAllocateContext 函数 (fltkernel.h)

项目
03/19/2024

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 结构中指定的 Size。微筛选器使用上下文的这一部分来维护特定于自身的上下文信息。 FltMgr 将上下文结构的这一部分视为不透明。此参数是必需的，不能为零。

[in] PoolType

要分配的池的类型。此参数是必需的，必须是以下参数之一。有关每种类型的详细说明，请参阅 POOL_TYPE 。有关更多信息，请参见备注。

值	含义
NonPagedPool	不可分页的系统内存。如果FLT_VOLUME_CONTEXT ContextType，PoolType 必须为 NonPagedPool。
PagedPool	可分页的系统内存。
NonPagedPoolNx	无执行 (NX) 非分页池。

[out] ReturnedContext

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

返回值

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

返回代码	说明
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	在筛选器注册时，未提供指定类型的上下文的分配信息。或者，对于固定大小的上下文，请求的 ContextSize 大于指定 ContextType的 FLT_CONTEXT_REGISTRATION 结构中指定的 Size。
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 list 返回的条目是以前释放到 lookaside 列表而不是全新分配的内存，则它可能不会归零。

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

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

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

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

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

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

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

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

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

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

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

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