PFLT_INSTANCE_TEARDOWN_CALLBACK回调函数 (fltkernel.h)

项目
08/07/2023

微筛选器驱动程序可以将 PFLT_INSTANCE_TEARDOWN_CALLBACK 类型的两个例程注册为微筛选器驱动程序的 InstanceTeardownStartCallback 和 InstanceTeardownCompleteCallback 例程。

语法

PFLT_INSTANCE_TEARDOWN_CALLBACK PfltInstanceTeardownCallback;

void PfltInstanceTeardownCallback(
  [in] PCFLT_RELATED_OBJECTS FltObjects,
  [in] FLT_INSTANCE_TEARDOWN_FLAGS Reason
)
{...}

参数

[in] FltObjects

指向 FLT_RELATED_OBJECTS 结构的指针，该结构包含与当前 I/O 操作相关的对象的不透明指针。

[in] Reason

指示为何要关闭微筛选器驱动程序实例的标志。下列类型作之一：

标志	含义
FLTFL_INSTANCE_TEARDOWN_MANUAL (0x00000001)	由于用户模式应用程序调用了 FilterDetach ，或者内核模式组件调用了 FltDetachVolume，因此实例被分离。
FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD (0x00000002)	正在卸载微筛选器驱动程序。
FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD (0x00000004)	正在卸载微筛选器驱动程序。
FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT (0x00000008)	如果设置，则会卸载卷。 (或已卸载卷。或者卷装载操作失败。或者正在关闭微筛选器驱动程序实例或卷。或者文件系统已将自身注销为活动文件系统。)
FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR (0x00000010)	系统遇到意外的内部错误。

返回值

无

备注

当微筛选器驱动程序通过从其 DriverEntry 例程调用 FltRegisterFilter 来注册自身时，它可以将两个类型为 PFLT_INSTANCE_TEARDOWN_CALLBACK 的例程注册为微筛选器驱动程序的 InstanceTeardownStartCallback 和 InstanceTeardownCompleteCallback 例程。为了注册这些回调例程，微筛选器驱动程序将PFLT_INSTANCE_TEARDOWN_CALLBACK类型的两个例程的地址存储在FLT_REGISTRATION结构的InstanceTeardownStartCallback 和 InstanceTeardownCompleteCallback 成员中，微筛选器驱动程序将其作为 FltRegisterFilter 的 Registration 参数传递。

InstanceTeardownStartCallback 和 InstanceTeardownCompleteCallback 例程是可选的，可以为 NULL。如果微筛选器驱动程序为 InstanceTeardownStartCallback 或 InstanceTeardownCompleteCallback 例程指定 NULL，则实例仍会断开。

当筛选器管理器开始拆解微筛选器驱动程序实例以允许微筛选器驱动程序完成任何笔式 I/O 操作并保存状态信息时，将调用 InstanceTeardownStartCallback 例程。

InstanceTeardownStartCallback 例程必须：

为微筛选器驱动程序的预操作回调例程中插入的每个 I/O 操作调用 FltCompletePendedPreOperation ，以完成操作或将操作控制权返回给筛选器管理器。
未写入任何新的 I/O 操作。如果微筛选器驱动程序使用回调数据队列，则必须调用 FltCbdqDisable 才能禁用它。
为微筛选器驱动程序的后操作回调例程中插入的每个 I/O 操作调用 FltCompletePendedPostOperation ，以将操作的控制权返回给筛选器管理器。

InstanceTeardownStartCallback 例程可以选择执行以下操作，以允许微筛选器驱动程序尽快卸载：

关闭任何打开的文件。
确保工作线程仅执行完成未完成工作项处理所需的最低要求。
调用 FltCancelIo 以取消微筛选器驱动程序启动的任何 I/O 操作。
停止将新工作项排队。

调用微筛选器驱动程序的 InstanceTeardownStartCallback 例程后，将不会为任何新的 I/O 操作调用微筛选器驱动程序的预操作和操作后回调例程。但是，对于在启动实例拆解之前启动的 I/O 操作，可能会调用它们。

当拆解过程完成时，将调用 InstanceTeardownCompleteCallback 例程，以允许微筛选器驱动程序关闭打开的文件并执行任何其他必要的清理处理。

InstanceTeardownCompleteCallback 例程必须关闭由微筛选器驱动程序打开的任何文件。

只有在完成或清空所有未完成的 I/O 操作后，筛选器管理器才调用微筛选器驱动程序的 InstanceTeardownCompleteCallback 例程。

警告

如果满足以下任何条件，则不会调用 InstanceTeardownCompleteCallback 例程：

存在未完成的 I/O 操作。
有微筛选器驱动程序启动的任何未完成的 I/O 操作。

如果由于正在卸载微筛选器驱动程序而删除微筛选器驱动程序实例，则卸载操作似乎会挂起，直到 InstanceTeardownCompleteCallback 例程返回为止。若要调试此类问题，应在微筛选器驱动程序上启用驱动程序验证程序。 “筛选器验证程序 I/O 验证 ”选项可帮助确定阻止微筛选器驱动程序卸载的可能原因，例如未发布的引用。有关详细信息，请参阅筛选器验证程序。

请注意，通过调用 FltObjectReference) 引用实例 (不会阻止调用 InstanceTeardownCompleteCallback 例程。

筛选器管理器在 IRQL PASSIVE_LEVEL调用 InstanceTeardownStartCallback 和 InstanceTeardownCompleteCallback 例程。