PFLT_INSTANCE_TEARDOWN_CALLBACK回调函数（fltkernel.h）

项目
02/06/2025

微型筛选器驱动程序可以将两个类型为 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 例程。若要注册这些回调例程， minifilter 驱动程序在 InstanceTeardownStartCallback 和 InstanceTeardownCompleteCallback 作为注册参数 FltRegisterFilter传递的 FLT_REGISTRATION 结构的成员存储类型PFLT_INSTANCE_TEARDOWN_CALLBACK的两个例程的地址。

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

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

InstanceTeardownStartCallback 例程必须：

调用 FltCompletePendedPreOperation，该作在微型筛选器驱动程序的预作回调例程中插入的每个 I/O作，以完成作或将作的控制返回到筛选器管理器。
不写任何新的 I/O作。如果微型筛选器驱动程序使用回调数据队列，则必须调用 FltCbdqDisable 来禁用该队列。
调用 FltCompletePendedPostOperation，该作在微型筛选器驱动程序的作后回调例程中插入的每个 I/O作，以将作的控制返回到筛选器管理器。

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 例程。