通过

FltSetStreamHandleContext 函数 （fltkernel.h）

  • 项目

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 如果为 作指定了FLT_SET_CONTEXT_KEEP_IF_EXISTS，则此错误代码指示已将上下文附加到流句柄。
STATUS_FLT_CONTEXT_ALREADY_LINKED NewContext 指向的上下文已链接到对象。 换句话说，此错误代码指示由于 FltSetXxx上下文 例程的成功调用，NewContext 已使用。
STATUS_FLT_DELETING_OBJECT 指定的 实例 正在被拆毁。 这是一个错误代码。
STATUS_INVALID_PARAMETER 传递了无效参数。 例如，NewContext 参数不指向有效的流句柄上下文，或者为 作指定了无效值。
STATUS_NOT_SUPPORTED 出现不支持的情况，例如文件系统不支持此文件流的按流上下文，或者调用方提供了 NULL FileObject。

言论

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

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

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

引用计数

如果 FltSetStreamHandleContext 成功：

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

否则，如果 FltSetStreamHandleContext 失败：

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

无论成功如何：

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

其他上下文作

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

要求

要求 价值
最低支持的客户端 sp4、Windows XP SP2、Windows Server 2003 SP1 和更高版本的作系统Microsoft Windows 2000 更新汇总 1 中可用和支持。
目标平台 普遍
标头 fltkernel.h （包括 Fltkernel.h）
库 Fltmgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

另请参阅

FltAllocateContext

FltDeleteContext

FltDeleteStreamHandleContext

FltGetStreamHandleContext

FltReleaseContext