Rules for IRP dispatching and completion routines

By the members of ntdev and ntfsd | published: 01-may-03 | modified: 01-may-03

IRP dispatching and handling

• If a dispatch routine returns status_pending, the IRP passed into
  Dispatch routine must be marked pending with iomarkirppending ().
• If an IRP is marked pending with iomarkirppending () in a dispatch routine,
  That dispatch routine must return status_pending.
• If an IRP is to be marked pending, iomarkirppending must be called before
  The IRP is accessible from any context in which it might be completed.
• If you complete the IRP in the dispatch routine, you must:
• Fill IRP-> iostatus. Status with the IRP's completion status (this may not be status_pending)
• Fill IRP-> iostatus. Information with the number of bytes read or written by the request if the request is being completed with a success status (for data transfer operations and IOCTLs), and
• Call iocompleterequest ().

On return from the dispatch routine, you must return the same status that you filled into IRP-> iostatus. Status. Note that in some cases IRP-> iostatus. Information can hold a pointer.

• Once you call iocompleterequest (), you no longer "own" The IRP, and must not refer to any of its contents.
• IRP-> iostatus. status must be filled before calling iocompleterequest. in some cases, you can use IRP-> iostatus as a temporary storage before this, assuming you do not pass the IRP to another driver. however, this does not apply to IRPs for irp_mj_pnp, because these IRPs arrive from the PnP Manager with a default status already filled into the iostatus. status field.
• Because of special logic in the I/O manager's completion handling code, drivers can also pass an IRP to another by "Return iocalldriver (...) "without setting a completion routine in the IRP. in this case, iomarkirppending must not be called.
• The following sequence is also valid, though slower. It is necessary as
  Workaround for filtering some buggy drivers like CDFs in NT v4.0 ):

  Iomarkirppending (IRP );
  (Void) iocalldriver (bottomdeviceobject, IRP );
  Return status_pending;

I/O completion routines

• There are only three valid return codes from an I/O completion routine:
  Status_more_processing_required, STATUS_SUCCESS, and
  Status_continue_completion (which is identical to STATUS_SUCCESS, see ntddk. h)
• Status_more_processing_required means that iocompleterequest returns to its caller immediately. No further completion routines are called, and IRP is not returned to the I/O manager.
• If and only if the completion routine returns STATUS_SUCCESS (or
  Status_continue_completion), then it must do the following:

  If (IRP-> pendingreturned ){
  Iomarkirppending (IRP );
  }

• If you set a completion routine into an IRP that's passed into your driver, and if that completion routine returns status_more_processing_required, your dispatch routine for that IRP must either return status_pending or it must block until the completion routine has run (for example, waiting on an event
  That is set from within the Completion routine ).