Edit

Share via

WIA Error Handler Cancellation of Modeless Dialogs

  • Article

Much of the complexity in the error handler revolves around how cancellation and dismissal of modeless dialog boxes are handled.

In particular, the WIA proxy code ensures that a lower-level error handler (in other words a handler other than that application's error handler) gets the chance to communicate a cancel request back from a modeless dialog to the driver; this ensures that a lower level handler gets a chance to dismiss its modeless dialog box.

In order to allow an error handler to cancel a data transfer operation from a modeless dialog, a driver should keep sending WIA_TRANSFER_MSG_DEVICE_STATUS messages with the same hrErrorStatus code, possibly updating the lPercentComplete parameter to allow an error handler UI to show progress. For example, if a driver can give an estimate of how long "warming up" really takes, it can send a number of device messages with hrErrorStatus set to WIA_STATUS_WARMING_UP. This will allow the error handler to show a progress dialog as well as giving the user a chance to cancel the transfer from this dialog box. The lPercentComplete parameter passed into IWiaErrorHandler::ReportStatus is the exact same lPercentComplete parameter that the driver sets in the IWiaTransferCallback::WiaTransferParams method. For an example of this, see the Extended WIA Monster Driver on the WDK CD.

To allow an error handler to dismiss a modeless dialog, Microsoft introduced the device status code WIA_STATUS_CLEAR. This message is sent by the WIA proxy to the error handler that is currently displaying a modeless UI when the WIA proxy receives a different device message from the one that is currently being displayed. The proxy also sends the WIA_STATUS_CLEAR message when:

The driver sends out the WIA_TRANSFER_MESSAGE_STATUS message,

during calls to the IWiaTransferCallback::GetNextStream method

at the end of stream/transfer (if there is currently an error handler displaying a modeless UI).

Drivers should not send the WIA_STATUS_CLEAR message themselves.

The IWiaTransferCallback interface is described in the Microsoft Windows SDK documentation.