fltSetVolumeContext 函数 (fltkernel.h)
FltSetVolumeContext 设置卷的上下文。
语法
NTSTATUS FLTAPI FltSetVolumeContext(
[in] PFLT_VOLUME Volume,
[in] FLT_SET_CONTEXT_OPERATION Operation,
[in] PFLT_CONTEXT NewContext,
[out, optional] PFLT_CONTEXT *OldContext
);
参数
[in] Volume
卷的不透明卷指针。
[in] Operation
指定要执行的操作的详细信息的标志。 此参数必须是下列值之一:
标志 | 含义 |
---|---|
FLT_SET_CONTEXT_REPLACE_IF_EXISTS | 如果已为 Volume 设置上下文, 则 FltSetVolumeContext 会将它替换为 NewContext>。 否则,它会将 NewContext 插入到卷的上下文列表中。 |
FLT_SET_CONTEXT_KEEP_IF_EXISTS | 如果已为此卷设置了上下文, 则 FltSetVolumeContext 将返回STATUS_FLT_CONTEXT_ALREADY_DEFINED,并且不会替换现有上下文或增加引用计数。 如果尚未设置上下文,则例程会将 NewContext 插入到卷的上下文列表中,并增加引用计数。 |
[in] NewContext
指向要为卷设置的新上下文的指针。 此参数是必需的,不能为 NULL。
[out, optional] OldContext
指向调用方分配的变量的指针,该变量接收 Volume 的现有卷上下文的地址。 此参数是可选的,可以为 NULL。 有关此参数的详细信息,请参阅以下“备注”部分。
返回值
FltSetVolumeContext 返回STATUS_SUCCESS或相应的 NTSTATUS 值,例如以下值之一:
返回代码 | 说明 |
---|---|
STATUS_FLT_CONTEXT_ALREADY_DEFINED | 如果为 操作指定了 FLT_SET_CONTEXT_KEEP_IF_EXISTS,则此错误代码指示已将上下文附加到卷。 |
STATUS_FLT_CONTEXT_ALREADY_LINKED | NewContext 参数指向的上下文已链接到 对象。 换句话说,此错误代码指示由于之前成功调用 FltSetXxxContext 例程,NewContext 已在使用中。 |
STATUS_FLT_DELETING_OBJECT | 指定的 卷 正在被拆掉。 这是错误代码。 |
STATUS_INVALID_PARAMETER | 传递的参数无效。 例如, NewContext 参数不指向有效的卷上下文,或者为 Operation 指定了无效值。 这是错误代码。 |
注解
有关上下文的详细信息,请参阅 关于微筛选器上下文。
微筛选器驱动程序调用 FltSetVolumeContext 将上下文附加到卷,或者删除或替换现有卷上下文。 微筛选器驱动程序只能将一个上下文附加到卷。
引用计数
如果 FltSetVolumeContext 成功:
- NewContext 上的引用计数递增。 不再需要 NewContext 时,微筛选器必须调用 FltReleaseContext 来递减其引用计数。
否则,如果 FltSetVolumeContext 失败:
- NewContext 上的引用计数保持不变。
- 如果 OldContext 不为 NULL 且不指向 NULL_CONTEXT则 OldContext 是指向当前与卷关联的上下文的引用指针。 当不再需要上下文指针时,调用 FltSetVolumeContext 的筛选器也必须为 OldContext 调用 FltReleaseContext。
无论成功与否:
- 调用 FltSetVolumeContext 的筛选器必须调用 FltReleaseContext,以递减由 FltAllocateContext 递增的 NewContext 对象的引用计数。
有关详细信息,请参阅 引用上下文。
其他上下文操作
若要分配新上下文,请调用 FltAllocateContext。
若要获取卷上下文,请调用 FltGetVolumeContext。
若要删除卷上下文,请调用 FltDeleteVolumeContext 或 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 |