Writing a FilterUnloadCallback Routine for a Minifilter Driver

A file system minifilter driver can optionally register a PFLT_FILTER_UNLOAD_CALLBACK-typed routine as the minifilter driver's
FilterUnloadCallback routine. This callback routine is also referred to as the minifilter driver's
unload routine.

文件过滤驱动可以可选的注册一个PFLT_FILTER_UNLOAD_CALLBACK类型函数作为过滤驱动的卸载回调函数，这个回调函数也可以被认为是过滤驱动的卸载函数。

Minifilter drivers are not required to register a FilterUnloadCallback routine. However, we strongly recommend that a minifilter driver registers this callback routine, because if a minifilter driver does not register a
FilterUnloadCallback routine, the driver cannot be unloaded.

过滤驱动可以不注册FilterUnloadCallback 回调函数，但是如果不注册的话，过滤驱动不能被卸载。

To register this callback routine, the minifilter driver stores the address of a PFLT_FILTER_UNLOAD_CALLBACK-typed routine in the
FilterUnloadCallback member of the FLT_REGISTRATION structure that the minifilter driver passes as a parameter to
FltRegisterFilter in its DriverEntry routine.

为了注册这个卸载回调函数，过滤驱动将函数指针保存在FLT_REGISTRATION结构体的FilterUnloadCallback 成员。

The filter manager calls a minifilter driver's FilterUnloadCallback routine before unloading the minifilter driver in one of the following ways:

过滤管理器在以下情况下调用过滤驱动的FilterUnloadCallback 回调函数。

Non-mandatory unload. This type of unload occurs when a user-mode application has called
FilterUnload or a kernel-mode driver has called FltUnloadFilter. It also occurs when you type
fltmc unload at the command prompt.
非强制卸载：这种类型的卸载发生在用户程序调用FilterUnload函数或者驱动程序调用FltUnloadFilter函数，另外还有在命令行中执行fltmc unload也会触发这种卸载。
Mandatory unload. This type of unload occurs when you issue a service stop request by typing
sc stop or net stop at the command prompt. (For more information about the
sc stop and net stop commands, click Help and Support on the Start menu.) It also occurs when a user-mode application calls the Microsoft Win32
ControlService function, passing the SERVICE_CONTROL_STOP control code as the
dwControl parameter. (For more information about Win32 service functions, see the Microsoft Windows SDK documentation.)

强制卸载：当停止过滤驱动服务时触发这种卸载。

For a non-mandatory unload, if the minifilter driver's FilterUnloadCallback routine returns an error or warning NTSTATUS value, such as STATUS_FLT_DO_NOT_DETACH, the filter manager does not unload the minifilter driver.

对于非强制卸载，如果过滤驱动的FilterUnloadCallback 返回错误或者警告状态码，例如STATUS_FLT_DO_NOT_DETACH，过滤管理器不会卸载过滤驱动。

For a mandatory unload, the filter manager unloads the minifilter driver after the minifilter driver's
FilterUnloadCallback routine is called, even if the FilterUnloadCallback routine returns an error or warning NTSTATUS value, such as STATUS_FLT_DO_NOT_DETACH.

对于强制卸载，过滤管理器在调用完FilterUnloadCallback 回调函数后卸载过滤驱动，即使FilterUnloadCallback
返回错误或者警告状态码。

To disable mandatory unloading for a minifilter driver, the minifilter driver sets the FLTFL_REGISTRATION_DO_NOT_SUPPORT_SERVICE_STOP flag in the
Flags member of the FLT_REGISTRATION structure that the minifilter driver passes as a parameter to
FltRegisterFilter in its DriverEntry routine. When this flag is set, the filter manager normally processes non-mandatory unload requests. However, mandatory unload requests will fail. The filter manager does not call the minifilter
driver's FilterUnloadCallback routine for failed unload requests.

为了禁用强制卸载，过滤驱动再调用FltRegisterFilter 注册过滤驱动时，可以设置FLT_REGISTRATION结构体成员Flags为FLTFL_REGISTRATION_DO_NOT_SUPPORT_SERVICE_STOP。如果这个标志位被设置，过滤驱动管理器只会处理non-mandatory 卸载请求，而强制卸载请求将失败。过滤管理器对于失败的卸载请求不会调用FilterUnloadCallback回调函数。

Note that if a minifilter driver's DriverEntry routine returns a warning or error NTSTATUS value, the
FilterUnloadCallback routine is not called; the filter manager simply unloads the minifilter driver.

如果DriverEntry返回了错误或者警告状态码，FilterUnloadCallback 回调函数不会被调用，过滤管理器只是简单的卸载驱动。

The FilterUnloadCallback routine is not called at system shutdown time. A minifilter driver that must perform shutdown processing should register a preoperation callback routine for IRP_MJ_SHUTDOWN operations.

系统关机时，FilterUnloadCallback 回调不会被调用。必须处理关机动作的过滤驱动应该为IRP_MJ_SHUTDOWN注册preoperation callback。

The FilterUnloadCallback routine is defined as follows:

FilterUnloadCallback 回调函数原型如下：

typedef NTSTATUS

(*PFLT_FILTER_UNLOAD_CALLBACK) (

FLT_FILTER_UNLOAD_FLAGS Flags

);

The FilterUnloadCallback routine has one input parameter, Flags, which can be NULL or FLTFL_FILTER_UNLOAD_MANDATORY. The filter manager sets this parameter to FLTFL_FILTER_UNLOAD_MANDATORY to indicate that the unload operation is mandatory.
For more information about this parameter, see PFLT_FILTER_UNLOAD_CALLBACK.

FilterUnloadCallback 函数有一个输入参数，Flags，它的值可以是NULL或者FLTFL_FILTER_UNLOAD_MANDATORY，过滤驱动管理器设置它为FLTFL_FILTER_UNLOAD_MANDATORY已表明这是一个强制卸载操作。

A minifilter driver's FilterUnloadCallback routine must perform the following steps:

Close any open kernel-mode communication server port handles. 关闭驱动通信服务端口句柄。
Call FltUnregisterFilter to unregister the minifilter driver. 调用FltUnregisterFilter 反注册过滤驱动。
Perform any needed global cleanup. 执行其它的清除操作。
Return an appropriate NTSTATUS value. 返回合适的状态码。

If the minifilter driver previously opened a kernel-mode communication server port by calling
FltCreateCommunicationPort, it must close the port by calling
FltCloseCommunicationPort. To prevent the system from hanging during the unload process, the minifilter driver's
FilterUnloadCallback routine must close this port before calling
FltUnregisterFilter.

如果过滤驱动之前调用FltCreateCommunicationPort打开了内核通信服务器端口，它必须调用FltCloseCommunicationPort。为了防止驱动在卸载过程中挂住，FilterUnloadCallback 回调函数必须在调用FltUnregisterFilter前关闭这个端口。

If a user-mode application has an open connection to the communication server port, any client port for that connection will remain open after
FltCloseCommunicationPort returns. However, the filter manager will close any client ports when the minifilter driver is unloaded.

如果用户程序已连接上了通信服务器端口，客户端口即使在内核调用FltCloseCommunicationPort情况下处于打开状态。但是过滤驱动管理器在驱动卸载后关闭所有的客户端端口。

A minifilter driver's FilterUnloadCallback routine must call
FltUnregisterFilter to unregister the minifilter driver. Calling
FltUnregisterFilter causes the following things to happen:

过滤驱动的FilterUnloadCallback 回调函数必须调用FltUnregisterFilter 反注册过滤驱动，调用FltUnregisterFilter 后将执行以下动作。

The minifilter driver's callback routines are unregistered. 过滤驱动的回调函数被反注册
The minifilter driver's instances are torn down, and the minifilter driver's
InstanceTeardownStartCallback and InstanceTeardownCompleteCallback routines are called for each minifilter driver instance. 过滤驱动实例被拆卸，驱动的InstanceTeardownStartCallback 和InstanceTeardownCompleteCallback 将会为每一个实例调用。
If the minifilter driver set any contexts on volumes, instances, streams, or stream handles, these contexts are deleted. If the minifilter driver has registered a
CleanupContext callback routine for a given context type, the filter manager calls the
CleanupContext routine before deleting the context. 如果过滤驱动设置过卷、实例、流、流句柄上下文，这些上下文将会被删除。如果过滤驱动为这些上下文类型注册过清理函数，过滤管理器将会在删除上下文之前调用此回调函数。

If there are outstanding rundown references on the minifilter driver's opaque filter pointer,
FltUnregisterFilter enters a wait state until they are removed. Outstanding rundown references usually happen because the minifilter driver has called
FltQueueGenericWorkItem to insert a work item into a system work queue, and the work item has not yet been dequeued and processed. (The filter manager adds the rundown reference when the minifilter driver calls
FltQueueGenericWorkItem and removes it when the minifilter driver's work routine returns.)

如果过滤驱动过滤指针额外的引用，FltUnregisterFilter 进入等待状态直到这些引用移除，额外的引用通常是由于调用FltQueueGenericWorkItem 向系统工作队列插入一个工作项引起的，而这个工作项还在队列中未被处理。

Outstanding rundown references can also happen if the minifilter driver has called any routines that add a rundown reference to the minifilter driver's opaque filter pointer, such as
FltObjectReference or FltGetFilterFromInstance, but did not subsequently call
FltObjectDereference.

额外的指针引用还可能发生在过滤驱动调用了FltObjectReference 或者FltGetFilterFromInstance，但是没有调用FltObjectDereference。

A minifilter driver's FilterUnloadCallback routine must perform any needed global cleanup. The following list includes examples of global cleanup tasks that a minifilter driver might perform:

过滤驱动必须执行任何必须的全局性清理，可能包括以下：

Call ExDeleteResourceLite to delete a global resource variable that was initialized by a previous call to
ExInitializeResourceLite.
调用ExDeleteResourceLite 删除全局的resource变量。
Call ExFreePool or ExFreePoolWithTag to free global memory that was allocated by a previous call to a routine such as
ExAllocatePoolWithTag.
调用 ExFreePool or ExFreePoolWithTag 释放内存
Call ExDeleteNPagedLookasideList or ExDeletePagedLookasideList to delete a lookaside list that was allocated by a previous call to
ExInitializeNPagedLookasideList or ExInitializePagedLookasideList, respectively.

删除lookaside结构体。
Call PsRemoveCreateThreadNotifyRoutine or PsRemoveLoadImageNotifyRoutine to unregister a global callback routine that was registered by a previous call to
PsSetCreateThreadNotifyRoutine or PsSetLoadImageNotifyRoutine, respectively.
移除系统通知调用

A minifilter driver's FilterUnloadCallback routine normally returns STATUS_SUCCESS.

To refuse an unload operation that is not mandatory, the minifilter driver should return an appropriate warning or error NTSTATUS value such as STATUS_FLT_DO_NOT_DETACH. For more information about mandatory unload operations, see
Writing a FilterUnloadCallback Routine and PFLT_FILTER_UNLOAD_CALLBACK.

If the FilterUnloadCallback routine returns a warning or error NTSTATUS value and the unload operation is not mandatory, the minifilter driver will not be unloaded.

过滤驱动的FilterUnloadCallback 通常返回STATUS_SUCCESS。如果要拒绝非强制卸载，此回调函数应返回错误或者警告状态码，例如STATUS_FLT_DO_NOT_DETACH。