FltAttachVolumeAtAltitude 函数（fltkernel.h）

项目
02/06/2025

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 从微型筛选器驱动程序名称和海拔指向的高度字符串生成实例名称。如有必要，将截断生成的名称以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。