INFO: I/O Request Packet (IRP) Cancellation

• Microsoft Win32 Device Development Kit (DDK) for Windows NT, versions 3.1, 3.5, 3.51

SUMMARY

Under certain circumstances, before an I/O Request Packet (IRP) can be completed by a driver, you may want to have the I/O manager notify the driver that the IRP is being canceled. Although currently there is not a Win32 API expressly for canceling I/O requests, the cancellation can happen in the following situations:

• A user-mode service attempts to cancel an IRP.
• When a thread is terminated with IRPs pending, the I/O manager attempts to cancel all the pending IRPs that belong to the thread.
• A driver attempts to cancel an IRP that it has originated and issued to a lower-level driver. The function a driver uses to cancel an IRP is IoCancelIrp(). A driver cannot cancel an IRP that it has received from the I/O manager or higher-level drivers.

MORE INFORMATION

For an IRP to be canceled, the IRP must be cancelable. The I/O manager considers an IRP to be cancelable when the CancelRoutine field in the IRP contains a non-NULL address. By calling this address, the I/O manager notifies the owning driver that an IRP is being canceled. To set up a cancel routine for an IRP (or in other words, make the IRP cancelable), a driver calls the IoSetCancelRoutine() function. A driver can declare an IRP cancelable only when the driver owns the IRP (that is, after the driver has received the IRP and before it completes the IRP or passes the IRP to another driver via IoCallDriver()). Before completing the IRP or passing it on, the driver must set the cancel routine address to NULL, also using IoSetCancelRoutine().

You do not have to make a driver set up cancel routines for all the IRPs it receives. However, it is strongly recommended that you have a driver set up cancel routines for IRPs that are not processed immediately.

Technically, an IRP can still be completed normally after it has been canceled. However, a cancellation notice should not be ignored when it is delivered to a driver. The only time a driver can let a canceled IRP be completed normally is when the completion can be done immediately. Otherwise, the driver should complete the IRP with STATUS_CANCELLED within the cancel routine.

Regardless of whether an IRP is canceled, a driver should always complete an IRP with whatever status that is appropriate.

As mentioned earlier, when a thread is terminated with I/O requests pending, the I/O manager tries to cancel all the pending requests. The cancel routine is called for each IRP associated with the thread if the IRP exists. After this, the I/O manager delays the thread execution to give the drivers some time to complete the IRPs. If the driver does not set up cancel routines as it should, the total delay for all the IRPs can be more than 5 minutes; if the IRPs cannot be completed in time, the I/O manager considers that the driver has timed out, and a message box is displayed on the screen naming the driver that has timed out. After that, any pending IRPs are dissociated from the terminating thread.

REFERENCES

Windows NT DDK Help: cancel routines

Version           : WINNT:3.1,3.5,3.51;
Platform          : winnt
Issue type        : kbinfo