Edit

Loading and Unloading

  • Article
  • 3 minutes to read

About Loading and Unloading

A minifilter driver can be loaded at any time while the system is running. If a minifilter driver's INF file specifies a driver start type of SERVICE_BOOT_START, SERVICE_SYSTEM_START, or SERVICE_AUTO_START, the minifilter driver is loaded according to existing load order group definitions for file system filter drivers, to support interoperability with legacy filter drivers. While the system is running, a minifilter driver can be loaded through a service start request (sc start, net start, or the service APIs), or through an explicit load request (fltmc load, FltLoadFilter, or FilterLoad).

A minifilter driver's DriverEntry routine is called when the minifilter driver is loaded, so the minifilter driver can perform initialization that will apply to all instances of the minifilter driver. Within its DriverEntry routine, the minifilter driver calls FltRegisterFilter to register callback routines with the filter manager and FltStartFiltering to notify the filter manager that the minifilter driver is ready to start attaching to volumes and filtering I/O requests.

Minifilter driver instances are defined in the INF file used to install the minifilter driver. A minifilter driver's INF file must define a default instance, and it can define additional instances. These definitions apply across all volumes. Each instance definition includes the instance name, its altitude, and flags that indicate whether the instance can be attached automatically, manually, or both. The default instance is used to order minifilter drivers so that the filter manager calls the minifilter driver's mount and instance setup callback routines in the correct order. The default instance is also used with explicit attachment requests when the caller doesn't specify an instance name.

The filter manager automatically notifies a minifilter driver about an available volume by calling its InstanceSetupCallback routine on the first create operation after the volume is mounted. This can occur before FltStartFiltering returns, when the filter manager enumerates existing volumes at system startup. It can also occur during runtime, when a volume is mounted or as a result of an explicit attachment request (fltmc attach, FltAttachVolume, or FilterAttach).

A minifilter driver instance is torn down when the minifilter driver is unloaded, the volume the instance is attached to is being dismounted, or as a result of an explicit detach request (fltmc detach, FltDetachVolume, or FilterDetach). If the minifilter driver registers an InstanceQueryTeardownCallback routine, it can fail an explicit detach request by calling FilterDetach or FltDetachVolume. The teardown proceeds as follows:

  • If the minifilter driver registered an InstanceTeardownStartCallback callback routine, the filter manager calls it at the beginning of the teardown process. In this routine, the minifilter driver should complete all pending operations, cancel or complete other work such as I/O requests generated by the minifilter driver, and stop queuing new work items.

  • During instance teardown, any currently executing preoperation or postoperation callback routines continue normal processing, any I/O request that is waiting for a postoperation callback can be "drained" or canceled, and any I/O requests generated by the minifilter driver continue normal processing until they are complete.

  • If the minifilter driver registered an InstanceTeardownCompleteCallback routine, the filter manager calls this routine after all outstanding I/O operations have been completed. In this routine, the minifilter driver closes any files that are still open.

  • After all outstanding references to the instance are released, the filter manager deletes remaining contexts and the instance is completely torn down.

While the system is running, a minifilter driver can be unloaded through a service stop request (sc stop, net stop, or the service APIs), or through an explicit unload request (fltmc unload, FltUnloadFilter, or FilterUnload).

A minifilter driver's FilterUnloadCallback routine is called when the minifilter driver is unloaded. This routine closes any open communication server ports, calls FltUnregisterFilter, and performs any needed cleanup. Registering this routine is optional. However, if the minifilter driver does not register a FilterUnloadCallback routine, the minifilter driver cannot be unloaded. For more information about this routine, see Writing a FilterUnloadCallback Routine.

Filter Manager Routines for Loading and Unloading Minifilter Drivers

The filter manager provides the following support routines for explicit load and unload requests, which can be issued from user mode or kernel mode:

The following routines are used to register and unregister callback routines for instance setup and teardown:

Minifilter Driver Callback Routines for Instance Setup, Teardown, and Unload

The following minifilter driver callback routines are stored as members of the FLT_REGISTRATION structure that is passed as a parameter to FltRegisterFilter:

Callback Routine Member Name Callback Routine Type
InstanceSetupCallback PFLT_INSTANCE_SETUP_CALLBACK
InstanceQueryTeardownCallback PFLT_INSTANCE_QUERY_TEARDOWN_CALLBACK
InstanceTeardownStartCallback PFLT_INSTANCE_TEARDOWN_CALLBACK
InstanceTeardownCompleteCallback PFLT_INSTANCE_TEARDOWN_CALLBACK
FilterUnloadCallback PFLT_FILTER_UNLOAD_CALLBACK