fltSetStreamHandleContext 函数 (fltkernel.h)

项目
08/07/2023

FltSetStreamHandleContext 例程设置流句柄的上下文。

语法

NTSTATUS FLTAPI FltSetStreamHandleContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PFILE_OBJECT              FileObject,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

参数

[in] Instance

微筛选器驱动程序实例的不透明实例指针，该实例的上下文将在附加到流句柄的上下文列表中插入、从中删除或替换该实例。

[in] FileObject

指向文件流的文件对象的指针。此参数是必需的，不能为 NULL。

[in] Operation

指定要执行的操作的详细信息的标志。此参数必须是下列值之一：

值	含义
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	如果已为此实例设置了上下文，则 FltSetStreamHandleContext 会将它替换为 NewContext 中指定的上下文。否则，它会将 NewContext 插入流句柄的上下文列表中。
FLT_SET_CONTEXT_KEEP_IF_EXISTS	如果已为此实例设置了上下文，则 FltSetStreamHandleContext 将返回STATUS_FLT_CONTEXT_ALREADY_DEFINED，并且不会替换现有上下文或增加引用计数。如果尚未设置上下文，则例程会将 NewContext 插入到流句柄的上下文列表中，并递增引用计数。

[in] NewContext

指向要为流句柄设置的新上下文的指针。此参数是必需的，不能为 NULL。

[out, optional] OldContext

指向调用方分配的变量的指针，该变量接收实例参数的现有流句柄上下文的地址（如果已设置）。此参数是可选的，可以为 NULL。有关此参数的详细信息，请参阅以下“备注”部分。

返回值

FltSetStreamHandleContext 例程返回STATUS_SUCCESS或相应的 NTSTATUS 值，例如以下错误代码之一：

返回代码	说明
STATUS_FLT_CONTEXT_ALREADY_DEFINED	如果为 Operation 指定了 FLT_SET_CONTEXT_KEEP_IF_EXISTS，则此错误代码指示已将上下文附加到流句柄。
STATUS_FLT_CONTEXT_ALREADY_LINKED	NewContext 指向的上下文已链接到对象。换句话说，此错误代码指示由于之前成功调用 FltSetXxxContext 例程，NewContext 已在使用中。
STATUS_FLT_DELETING_OBJECT	指定的实例正在被拆掉。这是错误代码。
STATUS_INVALID_PARAMETER	传递的参数无效。例如， NewContext 参数不指向有效的流句柄上下文，或者为 Operation 指定了无效值。
STATUS_NOT_SUPPORTED	出现不受支持的情况，例如文件系统不支持此文件流的每个流上下文，或者调用方提供了 NULL FileObject。

注解

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

FltSetStreamHandleContext 例程在流句柄上添加、删除或替换微筛选器驱动程序实例的上下文。微筛选器驱动程序可以将每个微筛选器驱动程序实例的一个上下文附加到流句柄。

无法在未打开的 FileObject 上调用 FltSetStreamHandleContext。因此，无法从流的预创建回调调用 FltSetStreamHandleContext ，因为此时尚未打开该流。但是，微筛选器可以在预创建回调中分配和设置流句柄上下文，使用完成上下文参数将其传递给创建后回调，并在创建后回调的流上设置流句柄上下文。

引用计数

如果 FltSetStreamHandleContext 成功：

NewContext 上的引用计数递增。不再需要 NewContext 时，微筛选器必须调用 FltReleaseContext 来递减其引用计数。

否则，如果 FltSetStreamHandleContext 失败：

NewContext 上的引用计数保持不变。
如果 OldContext 不为 NULL 且不指向 NULL_CONTEXT则 OldContext 是指向当前与流句柄关联的上下文的引用指针。当不再需要上下文指针时，调用 FltSetStreamHandleContext 的筛选器也必须为 OldContext 调用 FltReleaseContext。

无论成功与否：

调用 FltSetStreamHandleContext 的筛选器必须调用 FltReleaseContext，以递减由 FltAllocateContext 递增的 NewContext 对象的引用计数。

有关详细信息，请参阅引用上下文。

其他上下文操作

有关详细信息，请参阅设置上下文和发布上下文：

若要确定给定文件是否支持流句柄上下文，请调用 FltSupportsStreamHandleContexts
若要分配新上下文，请调用 FltAllocateContext。
若要获取流句柄上下文，请调用 FltGetStreamHandleContext。
若要删除流句柄上下文，请调用 FltDeleteStreamHandleContext 或 FltDeleteContext。

要求

要求	值
最低受支持的客户端	适用于 SP4、Windows XP SP2、Windows Server 2003 SP1 和更高版本的操作系统的 Microsoft Windows 2000 更新汇总 1 中可用和支持。
目标平台	通用
标头	fltkernel.h (包括 Fltkernel.h)
Library	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL