13.1.1 Setting Up an IoCompletion Routine

Every higher-level NT driver’s Dispatch routines are generally responsible for the following:

1. Checking the validity of parameters in their own I/O stack location of incoming IRPs and failing those requests with invalid parameters

2. Sending IRPs with valid parameters and those for which the Dispatch routine cannot determine the validity on to lower drivers with IoCallDriver 

   For more detailed information about higher-level drivers’ Dispatch routines, see Chapter 6.

Such a Dispatch routine can call IoSetCompletionRoutine with the entry point of a driver-supplied IoCompletion routine and with any IRP that it will pass on to lower drivers with IoCallDriver.

Such a Dispatch routine can specify whether the given IoCompletion routine will be called when lower drivers complete the given IRP with any one, two, or all of the following NTSTATUS values when it calls IoSetCompletionRoutine:

• STATUS_SUCCESS indicating that all lower-level drivers completed the requested operation successfully

• STATUS_CANCELLED indicating that the IRP was cancelled in a lower driver

• STATUS_XXX indicating that a lower driver encountered an error and failed the IRP

The purpose of an IoCompletion routine is to monitor what lower-level drivers did with a given IRP and/or to do any necessary cleanup processing for an IRP that the higher-level driver has passed on for processing by lower drivers.

For more information about NTSTATUS and I/O errors, see Chapter 16.

For specific information about any of the support routines mentioned in this chapter, see the Kernel-mode Driver Reference.