FltSetFileContext 函数（fltkernel.h）

项目
02/06/2025

FltSetFileContext 例程设置文件的上下文。

语法

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

参数

[in] Instance

指向调用方微型筛选器驱动程序实例的不透明指针。此参数是必需的，不能 NULL。

[in] FileObject

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

[in] Operation

一个标志，指定要执行的 FltSetFileContext 的作类型。此参数必须是以下标志之一：

旗	意义
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	如果已为 FileObject 参数指向的文件设置上下文，FltSetFileContext 会将该上下文替换为 NewContext中指定的上下文。否则，它将 NewContext 插入到文件的上下文列表中。
FLT_SET_CONTEXT_KEEP_IF_EXISTS	如果已为 FileObject 指向的文件设置了上下文，FltSetFileContext 将返回STATUS_FLT_CONTEXT_ALREADY_DEFINED，并且不会替换现有上下文或递增引用计数。如果尚未设置上下文，则例程会将 NewContext 中指定的上下文插入到文件的上下文列表中，并递增引用计数。

[in] NewContext

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

[out] OldContext

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

返回值

FltSetFileContext 例程返回STATUS_SUCCESS或适当的 NTSTATUS 值，例如以下值之一：

返回代码	描述
STATUS_FLT_CONTEXT_ALREADY_DEFINED	如果为 Operation 参数指定了FLT_SET_CONTEXT_KEEP_IF_EXISTS，则此错误代码指示上下文已附加到该文件。
STATUS_FLT_CONTEXT_ALREADY_LINKED	NewContext 参数指向的上下文已链接到对象。换句话说，此错误代码指示由于 FltSetXxx上下文例程成功调用，NewContext 已使用。
STATUS_FLT_DELETING_OBJECT	Instance 参数中指定的实例正在被拆毁。这是一个错误代码。
STATUS_INVALID_PARAMETER	传递了无效参数。例如，NewContext 参数不指向有效的文件上下文，或者为 Operation 参数指定了无效值。这是一个错误代码。
STATUS_NOT_SUPPORTED	此文件不支持文件上下文。这是一个错误代码。

言论

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

微型筛选器驱动程序调用 FltSetFileContext 来设置或替换文件中自己的文件上下文。微型筛选器驱动程序只能将每个微型筛选器驱动程序实例的一个上下文附加到该文件。

无法对未打开 FileObject调用 FltSetFileContext。因此 ，无法从文件的预创建回调调用 fltSetFileContext，因为该文件在该点尚未打开。但是，微型筛选器驱动程序可以在预创建回调中分配和设置文件上下文，使用完成上下文参数将其传递给创建后回调，并在创建后回调中与该流对应的文件上设置文件上下文。

引用计数

如果 FltSetFileContext 成功：

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

否则，如果 FltSetFileContext 失败：

NewContext 的引用计数保持不变。
如果 OldContext 未 NULL，并且不指向 NULL_CONTEXT 则 OldContext 是当前与该文件关联的上下文的引用指针。调用 FltSetFileContext 的筛选器 最终必须为 OldContext 调用 FltReleaseContext，以及不再需要上下文指针时。

无论成功如何：

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

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

其他上下文作

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

若要分配新上下文，请调用 FltAllocateContext。
若要获取文件上下文，请调用 FltGetFileContext。
若要删除文件上下文，请调用 FltDeleteFileContext 或 FltDeleteContext。
若要确定给定文件是否支持文件上下文，请调用 FltSupportsFileContexts 或 FltSupportsFileContextsEx。

要求

要求	价值
最低支持的客户端	从 Windows Vista 开始可用和支持。
目标平台	普遍
标头	fltkernel.h （包括 Fltkernel.h）
库	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL