PFLT_INSTANCE_TEARDOWN_CALLBACK

PFLT_INSTANCE_TEARDOWN_CALLBACK function pointer

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

Syntax


typedef VOID ( *PFLT_INSTANCE_TEARDOWN_CALLBACK)(
  _In_ PCFLT_RELATED_OBJECTS       FltObjects,
  _In_ FLT_INSTANCE_TEARDOWN_FLAGS Reason
);

Parameters

FltObjects [in]

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

Reason [in]

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

FlagMeaning

FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD

The minifilter driver is being unloaded.

FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR

An error, such as a memory allocation failure, occurred during instance setup.

FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD

The minifilter driver is being unloaded.

FLTFL_INSTANCE_TEARDOWN_MANUAL

The instance is being detached because a user-mode application has called FilterDetach or a kernel-mode component has called FltDetachVolume.

FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT

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.)

 

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

Target platform

Header

Fltkernel.h (include Fltkernel.h)

IRQL

See Remarks section.

See also

FilterDetach
FLT_REGISTRATION
FLT_RELATED_OBJECTS
FltCancelIo
FltCbdqDisable
FltCompletePendedPostOperation
FltCompletePendedPreOperation
FltDetachVolume
FltRegisterFilter
PFLT_INSTANCE_QUERY_TEARDOWN_CALLBACK
PFLT_INSTANCE_SETUP_CALLBACK

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft