Writing IRP Dispatch Routines
Note
For optimal reliability and performance, use file system minifilter drivers with Filter Manager support instead of legacy file system filter drivers. To port your legacy driver to a minifilter driver, see Guidelines for Porting Legacy Filter Drivers.
File system filter drivers use dispatch routines that are similar to those used in device drivers. A dispatch routine handles one or more types of IRPs. (The type of an IRP is determined by its major function code.) The driver's DriverEntry routine registers dispatch routine entry points by storing them in the driver object's dispatch table. When an IRP is sent to the driver, the I/O subsystem calls the appropriate dispatch routine based on the IRP's major function code.
Every IRP dispatch routine is defined as follows:
NTSTATUS
(*PDRIVER_DISPATCH) (
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
);
File system filter driver dispatch routines are most often called at IRQL PASSIVE_LEVEL, in the context of the thread that originated the I/O request, which is commonly a user-mode application thread. However, there are some exceptions to this rule. For example, page faults cause read and write dispatch routines to be called at IRQL APC_LEVEL. These exceptions are summarized in a table in Dispatch Routine IRQL and Thread Context. Unfortunately, it is not currently possible to prevent drivers in the filter chain from calling IoCallDriver at IRQL > PASSIVE_LEVEL (for example, by failing to release a spinlock or fast mutex). Nevertheless, it is strongly recommended that filter dispatch routines always call IoCallDriver at the same IRQL at which they were called.
Dispatch routines can be made pageable, provided that they meet the criteria described in the Making Drivers Pageable section of the Kernel-Mode Driver Architecture Design Guide.
If a file system filter driver has a control device object (CDO), its dispatch routines must be able to detect and handle cases where the IRP's target device object is the CDO rather than a volume device object (VDO) for a mounted volume. For more information about the CDO, see The Filter Driver's Control Device Object.
This section discusses the following topics:
Passing the IRP Down to Lower-Level Drivers
Returning Status from Dispatch Routines
Example: Passing the IRP Down Without Setting a Completion Routine