fltAttachVolume 函数 (fltkernel.h)

项目
02/29/2024

FltAttachVolume 创建新的微筛选器驱动程序实例，并将其附加到给定卷。

语法

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

参数

[in, out] Filter

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

[in, out] Volume

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

[in, optional] InstanceName

指向包含新实例的实例名称的UNICODE_STRING 结构的指针。此参数是可选的，可以为 NULL。如果为 NULL， 则 FltAttachVolume 会尝试从注册表中读取微筛选器驱动程序的默认实例名称。 (有关此参数的详细信息，请参阅以下“备注”部分。)

[out] RetInstance

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

返回值

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

返回代码	说明
STATUS_FLT_DELETING_OBJECT	指定的 “筛选器” 或 “卷 ”正在被拆掉。这是错误代码。
STATUS_FLT_FILTER_NOT_READY	微筛选器驱动程序尚未开始筛选。有关详细信息，请参阅 FltStartFiltering。这是错误代码。
STATUS_FLT_INSTANCE_NAME_COLLISION	指定的卷上已存在具有此名称的实例。
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolume 遇到池分配失败。这是错误代码。
STATUS_OBJECT_NAME_COLLISION	已在从注册表中读取的实例属性中指定的高度附加了另一个实例。这是错误代码。

注解

如果调用方为 InstanceName 指定非 NULL 值，则 FltAttachVolume 将读取微筛选器驱动程序指定的任何实例属性，这些属性存储在注册表的 HKLM\CurrentControlSet\Services\ServiceName\Instances\Instances\InstanceName 下，其中 ServiceName 是微筛选器驱动程序的服务名称。此服务名称在微筛选器驱动程序的 INF 文件的 DefaultInstall.Services 部分中的 AddService 指令中指定。 (有关筛选器驱动程序 INF 文件的详细信息，请参阅安装文件系统筛选器驱动程序。)

如果调用方未指定 InstanceName 的值， 则 FltAttachVolume 将使用注册表中存储在 HKLM\CurrentControlSet\Services\ServiceName\Instances\DefaultInstance 下的名称作为注册表路径的 InstanceName 部分。

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

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

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

若要将微筛选器驱动程序实例附加到给定高度的卷，请调用 FltAttachVolumeAtAltitude。

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

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