browser.documentScan

Description

The Document Scan API is designed to allow apps and extensions to view the content of paper documents on an attached document scanner.

Permissions

Availability

Concepts and usage

This API supports two means of scanning documents. If your use case can work with any scanner and doesn't require control of the configuration, use the scan() method. More complicated use cases require a combination of methods, which are only supported in Chrome 124 and later.

Simple scanning

For simple use cases, meaning those that can work with any scanner and don't require control of configuration, call scan(). This method takes a ScanOptions object and returns a Promise that resolves with a ScanResults object. The capabilities of this option are limited to the number of scans and the MIME types that will be accepted by the caller. Scans are returned as URLs for display in an <img> tag for a user interface.

Complex scanning

Complex scans are accomplished in three phases as described in this section. This outline does not describe every method argument or every property returned in a response. It is only intended to give you a general guide to writing scanner code.

Discovery

1. Call getScannerList(). Available scanners are returned in a Promise that resolves with a GetScannerListResponse.

   • The response object contains an array of ScannerInfo objects.
   • The array may contain multiple entries for a single scanner if that scanner supports multiple protocols or connection methods.

2. Select a scanner from the returned array and save the value of its scannerId property.

   Use the properties of individual ScannerInfo objects to distinguish among multiple objects for the same scanner. Objects from the same scanner will have the same value for the deviceUuid property. ScannerInfo also contains an imageFormats property containing an array of supported image types.

Scanner configuration

1. Call openScanner(), passing in the saved scanner ID. It returns a Promise that resolves with an OpenScannerResponse. The response object contains:

   • A scannerHandle property, which you'll need to save.

   • An options property containing scanner-specific properties, which you'll need to set. See Retrieve scanner options for more information.

2. (Optional) If you need the user to provide values for scanner options, construct a user interface. You will need the scanner options provided by the previous step, and you'll need to retrieve option groups provided by the scanner. See Construct a user interface for more information.

3. Construct an array of OptionSetting objects using programmatic or user-provided values. See Set scanner options for more information.

4. Pass the array of OptionSetting objects to setOptions() to set options for the scanner. It returns a Promise that resolves with a SetOptionsResponse. This object contains an updated version of the scanner options retrieved in step 1 of scanner configuration.

   Since changing one option can alter constraints on another option, you may need to repeat these steps several times.

Scanning

1. Construct a StartScanOptions object and pass it to startScan(). It returns a Promise that resolves with a StartScanResponse. Its job property is a handle that you will use to either read scan data or cancel the scan.

2. Pass the job handle to readScanData(). It returns a Promise that resolves with a ReadScanDataResponse object. If data was read successfully, its result property equals SUCCESS and its data property contains an ArrayBuffer with part of the scan. Note that estimatedCompletion contains an estimated percentage of the total data that has been delivered so far.

3. Repeat the previous step until the result property equals EOF or an error.

When the end of the scan is reached, call closeScanner() with the scanner handle saved in step 3. It returns a Promise that resolves with a CloseScannerResponse. Calling cancelScan() at any time after the job is created will end scanning.

Response objects

All methods return a Promise that resolves with a response object of some kind. Most of these contain a result property whose value is a member of OperationResult. Some properties of response objects won't contain values unless the value of result has a specific value. These relationships are described in the reference for each response object.

For example,