FltAttachVolumeAtAltitude 函数 (fltkernel.h)

FltAttachVolumeAtAltitude 是一个调试支持例程,用于将微筛选器驱动程序实例附加到指定高度的卷,覆盖微筛选器驱动程序的 INF 文件中的任何设置。

语法

NTSTATUS FLTAPI FltAttachVolumeAtAltitude(
  [in, out]       PFLT_FILTER      Filter,
  [in, out]       PFLT_VOLUME      Volume,
  [in]            PCUNICODE_STRING Altitude,
  [in, optional]  PCUNICODE_STRING InstanceName,
  [out, optional] PFLT_INSTANCE    *RetInstance
);

参数

[in, out] Filter

调用方不透明的筛选器指针。 此参数是必需的,不能为 NULL

[in, out] Volume

微筛选器驱动程序实例要附加到的卷的不透明卷指针。 此参数是必需的,不能为 NULL

[in] Altitude

指向包含实例海拔字符串 的UNICODE_STRING 结构的指针。 此参数是必需的,不能为 NULL。 (有关此参数的详细信息,请参阅以下“备注”部分。)

[in, optional] InstanceName

指向包含新实例的实例名称 的UNICODE_STRING 结构的指针。 此参数是可选的,可以为 NULL。 如果为 NULL则 FltAttachVolumeAtAltitude 从微筛选器驱动程序名称和 Altitude 指向的高度字符串生成实例名称。 如有必要,将截断生成的名称以INSTANCE_NAME_MAX_CHARS字符。

[out, optional] RetInstance

指向调用方分配的变量的指针,该变量接收新创建的实例的不透明实例指针。 此参数是可选的,可以为 NULL

返回值

FltAttachVolumeAtAltitude 返回STATUS_SUCCESS或相应的 NTSTATUS 值,如以下值之一:

返回代码 说明
STATUS_FLT_DELETING_OBJECT
指定的 “筛选器”“卷 ”正在被拆掉。 这是错误代码。
STATUS_FLT_FILTER_NOT_READY
微筛选器驱动程序尚未开始筛选。 有关详细信息,请参阅 FltStartFiltering。 这是错误代码。
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION
指定卷上的此高度上已存在一个实例。 这是错误代码。
STATUS_FLT_INSTANCE_NAME_COLLISION
指定的卷上已存在具有此名称的实例。 这是错误代码。
STATUS_INSUFFICIENT_RESOURCES
FltAttachVolumeAtAltitude 遇到池分配失败。 这是错误代码。
STATUS_INVALID_PARAMETER
海拔指向的UNICODE_STRING结构不包含有效的海拔字符串。 这是错误代码。

注解

微筛选器驱动程序应仅使用 FltAttachVolumeAtAltitude 进行调试。 它不应在微筛选器驱动程序的零售版本中调用此例程。

FltAttachVolumeAtAltitude 是 Win32 FilterAttachAtAltitude 函数的内核等效项。

术语“海拔”是指实例 (或应在卷的微筛选器驱动程序实例堆栈中占据) 的位置。 高度越高,实例离堆栈中基本文件系统的距离就越远。 在给定卷的给定高度上只能附加一个实例。

海拔由 海拔字符串指定,该字符串是一个宽字符数组,其中包含一个或多个从 0 到 9 的十进制数字;数组可以包含单个小数点。 例如,“100.123456”和“03333”是有效的海拔字符串。

字符串“03333”表示高于“100.123456”的海拔高度, (忽略前导和尾随零。) 换句话说,海拔高度为“03333”的实例比海拔高度为“100.123456”的实例离基本文件系统更远。 但是,仅当两个实例都附加到同一卷时,此比较才有意义。

InstanceName 参数中指定的实例名称在整个系统中必须是唯一的。

FltAttachVolumeAtAltitude 返回 *RetInstance 中新实例的不透明实例指针。 此指针值唯一标识微筛选器驱动程序实例,并且只要实例附加到卷,它就保持不变。

FltAttachVolumeAtAltitude 添加对 *RetInstance 中返回的不透明实例指针的断开引用。 当不再需要此指针时,调用方必须通过调用 FltObjectDereference 释放它。 因此,每次成功调用 FltAttachVolumeAtAltitude 都必须与后续对 FltObjectDereference 的调用相匹配。

若要比较附加到同一卷的两个微筛选器驱动程序实例的高度,请调用 FltCompareInstanceAltitudes

若要从卷中分离微筛选器驱动程序实例,请调用 FltDetachVolume

要求

要求
目标平台 通用
标头 fltkernel.h (包括 Fltkernel.h)
Library FltMgr.lib
IRQL PASSIVE_LEVEL

另请参阅

FilterAttachAtAltitude

FltAttachVolume

FltCompareInstanceAltitudes

FltDetachVolume

FltGetVolumeInstanceFromName

FltObjectDereference

FltStartFiltering

UNICODE_STRING