FltGetVolumeInstanceFromName 函数 (fltkernel.h)

项目
08/07/2023

FltGetVolumeInstanceFromName 例程返回给定卷上给定微筛选器驱动程序实例的不透明实例指针。

语法

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

参数

[in, optional] Filter

拥有实例的微筛选器驱动程序的不透明筛选器指针。此参数是可选的，可以为 NULL。

[in] Volume

实例附加到的卷的不透明指针。必须是有效的卷句柄。此参数是必需的，不能为 NULL。 (将此参数设置为无效值会导致系统在选中的 build 上执行 ASSERT。)

[in, optional] InstanceName

指向调用方分配的UNICODE_STRING 结构的指针，该结构包含卷上实例的实例名称。 (这是创建实例时传递给 FltAttachVolume 或 FltAttachVolumeAtAltitude 的 InstanceName 值。) 此参数是可选的，可以为 NULL。如果为 NULL， 则 FltGetVolumeInstanceFromName 返回找到的最高匹配实例。

[out] RetInstance

指向调用方分配的变量的指针，该变量接收与 Filter、 Volume 和 InstanceName 的值匹配的实例的不透明实例指针。此参数是必需的，不能为 NULL。

返回值

FltGetVolumeInstanceFromName 返回STATUS_SUCCESS或相应的 NTSTATUS 值，如以下值之一：

返回代码	说明
STATUS_FLT_DELETING_OBJECT	实例正在被拆毁。这是错误代码。
STATUS_FLT_INSTANCE_NOT_FOUND	找不到匹配的实例。这是错误代码。

注解

FltGetVolumeInstanceFromName 搜索附加到 Volume 参数中指定的卷的微筛选器驱动程序实例的列表，从最顶层的实例开始。。如果多个实例与 Filter、 Volume 和 InstanceName 参数的给定值匹配， 则 FltGetVolumeInstanceFromName 将返回找到的最高匹配实例。

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

海拔由 海拔字符串指定，该字符串是计数的 Unicode 字符串，由 0 到 9 之间的一个或多个十进制数字组成，可以包含单个小数点。例如，“100.123456”和“03333”是有效的海拔字符串。

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

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