INFO: I/O Request Packet (IRP) Cancellation
ID: Q120171
|
The information in this article applies to:
-
Microsoft Win32 Device Driver 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
Keywords :
Version : WINNT:3.1,3.5,3.51;
Platform : winnt
Issue type : kbinfo