PFLT_INSTANCE_TEARDOWN_CALLBACK callback function (fltkernel.h)

Article
10/27/2021

A minifilter driver can register two routines of type PFLT_INSTANCE_TEARDOWN_CALLBACK as the minifilter driver's InstanceTeardownStartCallback and InstanceTeardownCompleteCallback routines.

Syntax

PFLT_INSTANCE_TEARDOWN_CALLBACK PfltInstanceTeardownCallback;

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

Parameters

[in] FltObjects

Pointer to a FLT_RELATED_OBJECTS structure that contains opaque pointers for the objects related to the current I/O operation.

[in] Reason

Flag that indicates why the minifilter driver instance is being torn down. One of the following:

Flag	Meaning
FLTFL_INSTANCE_TEARDOWN_MANUAL (0x00000001)	The instance is being detached because a user-mode application has called FilterDetach or a kernel-mode component has called FltDetachVolume.
FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD (0x00000002)	The minifilter driver is being unloaded.
FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD (0x00000004)	The minifilter driver is being unloaded.
FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT (0x00000008)	If set, the volume is being dismounted. (Or the volume has already been dismounted. Or the volume mount operation failed. Or the minifilter driver instance or the volume is being torn down. Or the file system unregistered itself as an active file system.)
FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR (0x00000010)	The system experienced an unexpected internal error.

Return value

None

Remarks

When a minifilter driver registers itself by calling FltRegisterFilter from its DriverEntry routine, it can register two routines of type PFLT_INSTANCE_TEARDOWN_CALLBACK as the minifilter driver's InstanceTeardownStartCallback and InstanceTeardownCompleteCallback routines. To register these callback routines, the minifilter driver stores the addresses of the two routines of type PFLT_INSTANCE_TEARDOWN_CALLBACK in the InstanceTeardownStartCallback and InstanceTeardownCompleteCallback members of the FLT_REGISTRATION structure that the minifilter driver passes as the Registration parameter of FltRegisterFilter.

The InstanceTeardownStartCallback and InstanceTeardownCompleteCallback routines are optional and can be NULL. If the minifilter driver specifies NULL for the InstanceTeardownStartCallback or InstanceTeardownCompleteCallback routine, the instance is still torn down.

The InstanceTeardownStartCallback routine is called when the filter manager starts tearing down a minifilter driver instance to allow the minifilter driver to complete any pended I/O operations and save state information.

The InstanceTeardownStartCallback routine must:

Call FltCompletePendedPreOperation for each I/O operation that was pended in the minifilter driver's preoperation callback routine to complete the operation or return control of the operation to the filter manager.
Not pend any new I/O operations. If the minifilter driver uses a callback data queue, it must call FltCbdqDisable to disable it.
Call FltCompletePendedPostOperation for each I/O operation that was pended in the minifilter driver's postoperation callback routine to return control of the operation to the filter manager.

The InstanceTeardownStartCallback routine can optionally do the following to allow the minifilter driver to unload as quickly as possible:

Close any opened files.
Ensure that worker threads perform only the minimum necessary to complete processing of outstanding work items.
Call FltCancelIo to cancel any I/O operations that were initiated by the minifilter driver.
Stop queuing new work items.

Once the minifilter driver's InstanceTeardownStartCallback routine is called, the minifilter driver's preoperation and postoperation callback routines are not called for any new I/O operations. However, they may be called for I/O operations that were started before instance teardown was initiated.

The InstanceTeardownCompleteCallback routine is called when the teardown process is complete to allow the minifilter driver to close open files and perform any other necessary cleanup processing.

The InstanceTeardownCompleteCallback routine must close any files that were opened by the minifilter driver.

The filter manager calls the minifilter driver's InstanceTeardownCompleteCallback routine only after all outstanding I/O operations have been completed or drained.

Warning

The InstanceTeardownCompleteCallback routine will not be called if any of the following conditions are true:

There are outstanding pended I/O operations.
There are any outstanding I/O operations that were initiated by the minifilter driver.

If the minifilter driver instance is being torn down because the minifilter driver is being unloaded, the unload operation appears to hang until the InstanceTeardownCompleteCallback routine returns. To debug these kinds of problems, you should enable the Driver Verifier on your minifilter driver. The Filter Verifier I/O Verification option can help identify possible causes, such as unreleased references, that would prevent the minifilter driver from unloading. For more information, see Filter Verifier.

Note that referencing the instance (by calling FltObjectReference) does not prevent the InstanceTeardownCompleteCallback routine from being called.

The filter manager calls the InstanceTeardownStartCallback and InstanceTeardownCompleteCallback routines at IRQL PASSIVE_LEVEL.

Requirements

Requirement	Value
Target Platform	Desktop
Header	fltkernel.h (include Fltkernel.h)
IRQL	See Remarks section.