ImageScanner.ScanFilesToFolderAsync Method

Definition

Namespace:

Windows.Devices.Scanners

Starts a scan job with the specified scan source and writes one or multiple images to one multi-page file like TIFF, XPS, and PDF; or one or multiple single-page files like DIB, PNG, JPG, and TIFF to the specified folder location. Returns the progress of the scan.

public:
 virtual IAsyncOperationWithProgress<ImageScannerScanResult ^, unsigned int> ^ ScanFilesToFolderAsync(ImageScannerScanSource scanSource, StorageFolder ^ storageFolder) = ScanFilesToFolderAsync;

/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperationWithProgress<ImageScannerScanResult, uint32_t> ScanFilesToFolderAsync(ImageScannerScanSource const& scanSource, StorageFolder const& storageFolder);

[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperationWithProgress<ImageScannerScanResult,uint> ScanFilesToFolderAsync(ImageScannerScanSource scanSource, StorageFolder storageFolder);

function scanFilesToFolderAsync(scanSource, storageFolder)

Public Function ScanFilesToFolderAsync (scanSource As ImageScannerScanSource, storageFolder As StorageFolder) As IAsyncOperationWithProgress(Of ImageScannerScanResult, UInteger)

Parameters

scanSource

ImageScannerScanSource

The image scan source.

storageFolder

StorageFolder

The target folder location of the scanned file.

Returns

IAsyncOperationWithProgress<ImageScannerScanResult,UInt32>

Windows.Foundation.IAsyncOperationWithProgress<Windows.Devices.Scanners.ImageScannerScanResult,unsigned int>

IAsyncOperationWithProgress<ImageScannerScanResult,uint32_t>

The list of scanned image files from ImageScannerScanResult and the progress of the WIA scan job from UInt32, which indicates how many files were transferred to the target folder.

Attributes

RemoteAsyncAttribute

Remarks

The files are named using temporary names, with a standard file extension that depends on the file format type.

Note

In UWP app, when this method is invoked, the app must be visible and running in the foreground.

When the app cancels the async call, it initiates a cancellation request of the current scan job. There is no guarantee that if the app cancels the async call that the scan job will be canceled. If the cancellation goes through, the scanner may stop for these reasons:

• It takes a few seconds before the scanner stops scanning.
• It stops only when it runs out of paper (for a feeder acquisition).
• It completes running the scan head to the end of the bed and then fully returns the scan head to its parked location (for a flatbed acquisition).

Internally the async cancelation will flag the current WIA 2.0 scan job as canceled from within the app. If the WIA device makes the next callback to the WIA service the job cancellation may or may not be successfully communicated to the WIA driver. But, even if the WIA driver receives the cancel request from one of its callbacks there is no guarantee that the driver can successfully stop the scanner from scanning, immediately or after any predictable period of time.

Here's the list of WIA specific HRESULT error codes as well as standard COM HRESULT error codes this function returns.

Note

(the API will call WinRTOriginateError and/or OriginateErrorWithResourceString (all specific WIA errors will have localizable error descriptions) for the WIA specific failure HRESULTs):

WIA_ERROR_GENERAL_ERROR	WIA_ERROR_PAPER_JAM	WIA_ERROR_PAPER_EMPTY
WIA_ERROR_PAPER_PROBLEM	WIA_ERROR_OFFLINE	WIA_ERROR_BUSY
WIA_ERROR_WARMING_UP	WIA_ERROR_USER_INTERVENTION	WIA_ERROR_ITEM_DELETED
WIA_ERROR_DEVICE_COMMUNICATION	WIA_ERROR_INVALID_COMMAND	WIA_ERROR_INCORRECT_HARDWARE_SETTING
WIA_ERROR_DEVICE_LOCKED	WIA_ERROR_EXCEPTION_IN_DRIVER	WIA_ERROR_INVALID_DRIVER_RESPONSE
WIA_ERROR_COVER_OPEN	WIA_ERROR_LAMP_OFF	WIA_ERROR_MULTI_FEED

There are two special cases:

• The WIA’s HRESULT of S_FALSE will be translated to a canceled async call (AsyncStatus.Canceled).
• The WIA’s WIA_ERROR_PAPER_EMPTY will be translated by this API to a successful return (AsyncStatus.Completed) with an empty list of files (IVectorView.Size set to 0). To prevent orphan files, this method deletes any remaining orphan files used to transfer images upon failure, before the failure occurred. The method will save the transfer files as temporary files and keep them until the scan job completes. The app must instruct the user to rescan the document.