Edit

Share via

Cancellation of data transfers in Windows Vista

  • Article

Important

This article contains information that applies to obsolete Windows operating systems.

In Windows Vista, there is a new interface, IWiaTransfer (which is described in the Windows SDK documentation) that applications use to perform stream-based data transfers. This interface, in addition to the new transfer methods, contains a Cancel method that an application can use to cancel data transfers, including multi-item transfers. With this method, you can asynchronously cancel a data transfer. We recommended that you use this procedure to cancel a data transfer. However, a Windows Vista application can also return S_FALSE from its callback routine to cancel a transfer.

Thus, there are two ways for a WIA application in Windows Vista to cancel a transfer:

  • Return S_FALSE from its callback routine.

  • Call IWiaTransfer::Cancel.

A Windows Vista driver can be notified in two different ways that the application has canceled the transfer:

  • The driver receives a call to its IWiaMiniDrv::drvNotifyPnPEvent with a WIA_EVENT_CANCEL_IO event. We recommend that all kernel-mode read or write operations use OVERLAPPED I/O. Only with this procedure can you guarantee immediate cancellation.

  • S_FALSE is returned from two callback functions: IWiaMiniDrvTransferCallback::GetNextStream and IWiaMiniDrvTransferCallback::SendMessage.

When an application calls IWiaTransfer::Cancel, the IWiaMiniDrv::drvNotifyPnPEvent method should be called into the driver with WIA_EVENT_CANCEL_IO. In addition, the IWiaMiniDrvTransferCallback::GetNextStream and IWiaMiniDrvTransferCallback::SendMessage callback functions must always return S_FALSE after the transfer has been canceled.

If IWiaTransferCallback::GetNextStream returns WIA_STATUS_SKIP_ITEM during a multi-item transfer, an application is skipping (that is, not transferring) the current item. A return value of S_FALSE still means that the whole transfer should be canceled.

The IWiaTransfer and IWiaTransferCallback interfaces are described in the Microsoft Windows SDK documentation.

IWiaMiniDrvTransferCallback