chrome/common/extensions/api/document_scan.webidl

// Copyright 2026 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

dictionary ScanOptions {
  // The MIME types that are accepted by the caller.
  sequence<DOMString> mimeTypes;

  // The number of scanned images allowed. The default is 1.
  long maxImages;
};

dictionary ScanResults {
  // An array of data image URLs in a form that can be passed as the "src"
  // value to an image tag.
  required sequence<DOMString> dataUrls;

  // The MIME type of the <code>dataUrls</code>.
  required DOMString mimeType;
};

// An enum that indicates the result of each operation.
enum OperationResult {
  // An unknown or generic failure occurred.
  "UNKNOWN",

  // The operation succeeded.
  "SUCCESS",

  // The operation is not supported.
  "UNSUPPORTED",

  // The operation was cancelled.
  "CANCELLED",

  // The device is busy.
  "DEVICE_BUSY",

  // Either the data or an argument passed to the method is not valid.
  "INVALID",

  // The supplied value is the wrong data type for the underlying option.
  "WRONG_TYPE",

  // No more data is available.
  "EOF",

  // The document feeder is jammed.
  "ADF_JAMMED",

  // The document feeder is empty.
  "ADF_EMPTY",

  // The flatbed cover is open.
  "COVER_OPEN",

  // An error occurred while communicating with the device.
  "IO_ERROR",

  // The device requires authentication.
  "ACCESS_DENIED",

  // Not enough memory is available on the Chromebook to complete the
  // operation.
  "NO_MEMORY",

  // The device is not reachable.
  "UNREACHABLE",

  // The device is disconnected.
  "MISSING",

  // An error has occurred somewhere other than the calling application.
  "INTERNAL_ERROR"
};

// Indicates how the scanner is connected to the computer.
enum ConnectionType {
  "UNSPECIFIED",
  "USB",
  "NETWORK"
};

// Contains general information about a scanner. It is
// intended for filtering and constructing user-facing information. to
// configure a scan, use $(ref:StartScanOptions).
dictionary ScannerInfo {
  // The ID of a specific scanner.
  required DOMString scannerId;

  // A human-readable name for the scanner to display in the UI.
  required DOMString name;

  // The scanner manufacturer.
  required DOMString manufacturer;

  // The scanner model if it is available, or a generic description.
  required DOMString model;

  // For matching against other <code>ScannerInfo</code> entries that point
  // to the same physical device.
  required DOMString deviceUuid;

  // Indicates how the scanner is connected to the computer.
  required ConnectionType connectionType;

  // If true, the scanner connection's transport cannot be intercepted by a
  // passive listener, such as TLS or USB.
  required boolean secure;

  // An array of MIME types that can be requested for returned scans.
  required sequence<DOMString> imageFormats;

  // A human-readable description of the protocol or driver used to
  // access the scanner, such as Mopria, WSD, or epsonds. This is primarily
  // useful for allowing a user to choose between protocols if a device
  // supports multiple protocols.
  required DOMString protocolType;
};

// The data type of an option.
enum OptionType {
  // The option's data type is unknown. The <code>value</code> property
  // will be unset.
  "UNKNOWN",

  // The <code>value</code> property will be one of <code>true</code or
  // <code>false</code>.
  "BOOL",

  // A signed 32-bit integer. The <code>value</code> property will be long or
  // long[], depending on whether the option takes more than one value.
  "INT",

  // A double in the range -32768-32767.9999 with a resolution of 1/65535.
  // The <code>value</code> property will be double or double[] depending
  // on whether the option takes more than one value. Double values that
  // can't be exactly represented will be rounded to the available range
  // and precision.
  "FIXED",

  // A sequence of any bytes except NUL ('\0'). The <code>value</code>
  // property will be a DOMString.
  "STRING",

  // An option of this type has no value. Instead, setting an option of
  // this type causes an option-specific side effect in the scanner
  // driver. For example, a button-typed option could be used by a
  // scanner driver to provide a means to select default values or to
  // tell an automatic document feeder to advance to the next sheet of
  // paper.
  "BUTTON",

  // Grouping option. No value. This is included for compatibility, but
  // will not normally be returned in <code>ScannerOption</code> values. Use
  // <code>getOptionGroups()</code> to retrieve the list of groups with their
  // member options.
  "GROUP"
};

// Indicates the data type for $(ref:ScannerOption.unit).
enum OptionUnit {
  // The value is a unitless number. For example, it can be a threshold.
  "UNITLESS",

  // The value is a number of pixels, for example, scan dimensions.
  "PIXEL",

  // The value is the number of bits, for example, color depth.
  "BIT",

  // The value is measured in millimeters, for example, scan dimensions.
  "MM",

  // The value is measured in dots per inch, for example, resolution.
  "DPI",

  // The value is a percent, for example, brightness.
  "PERCENT",

  // The value is measured in microseconds, for example, exposure time.
  "MICROSECOND"
};

// The data type of constraint represented by an $(ref:OptionConstraint).
enum ConstraintType {
  // The constraint on a range of <code>OptionType.INT</code> values.
  // The <code>min</code>, <code>max</code>, and <code>quant</code> properties
  // of <code>OptionConstraint</code> will be <code>long</code>, and its
  // <code>list</code> propety will be unset.
  "INT_RANGE",

  // The constraint on a range of <code>OptionType.FIXED</code> values.
  // The <code>min</code>, <code>max</code>, and <code>quant</code> properties
  // of <code>OptionConstraint</code> will be <code>double</code>, and its
  // <code>list</code> property will be unset.
  "FIXED_RANGE",

  // The constraint on a specific list of <code>OptionType.INT</code>
  // values. The <code>OptionConstraint.list</code> property will contain
  // <code>long</code> values, and the other properties will be unset.
  "INT_LIST",

  // The constraint on a specific list of <code>OptionType.FIXED</code>
  // values. The <code>OptionConstraint.list</code> property will contain
  // <code>double</code> values, and the other properties will be unset.
  "FIXED_LIST",

  // The constraint on a specific list of <code>OptionType.STRING</code>
  // values. The <code>OptionConstraint.list</code> property will contain
  // <code>DOMString</code> values, and the other properties will be unset.
  "STRING_LIST"
};

// The specific values for the $(ref:ConstraintType) structure.
// An unconstrained value is represented by a lack of constraints;
// there is no separate <code>ConstraintType</code> value to indicate an
// unconstrained value.
dictionary OptionConstraint {
  required ConstraintType type;
  (long or double) min;
  (long or double) max;
  (long or double) quant;
  (sequence<double> or sequence<long> or sequence<DOMString>) list;
};

// How an option can be changed.
enum Configurability {
  // The option is read-only.
  "NOT_CONFIGURABLE",

  // The option can be set in software.
  "SOFTWARE_CONFIGURABLE",

  // The option can be set by the user toggling or pushing a button on
  // the scanner.
  "HARDWARE_CONFIGURABLE"
};

// A self-describing configurable scanner option and its current value.
dictionary ScannerOption {
  // The option name using lowercase ASCII letters, numbers, and dashes.
  // Diacritics are not allowed.
  required DOMString name;

  // A printable one-line title.
  required DOMString title;

  // A longer description of the option.
  required DOMString description;

  // The data type contained in the <code>value</code> property, which
  // is needed for setting this option.
  required OptionType type;

  // The unit of measurement for this option.
  required OptionUnit unit;

  // The current value of the option, if relevant. Note that the data
  // type of this property must match the data type specified in
  // <code>type</code>.
  (boolean or double or sequence<double> or long or sequence<long> or
   DOMString)? value;

  // Defines $(ref:OptionConstraint) on the current scanner option.
  OptionConstraint constraint;

  // Indicates that this option can be detected from software.
  required boolean isDetectable;

  // Indicates whether and how the option can be changed.
  required Configurability configurability;

  // Can be automatically set by the scanner driver.
  required boolean isAutoSettable;

  // Emulated by the scanner driver if true.
  required boolean isEmulated;

  // Indicates the option is active and can be set or retrieved. If false,
  // the <code>value</code> property will not be set.
  required boolean isActive;

  // Indicates that the UI should not display this option by default.
  required boolean isAdvanced;

  // Indicates that the option is used for internal configuration and
  // should never be displayed in the UI.
  required boolean isInternal;
};

// A set of criteria passed to <code>getScannerList()</code>. Only devices
// that match all of the criteria will be returned.
dictionary DeviceFilter {
  // Only return scanners that are directly attached to the computer.
  boolean local;

  // Only return scanners that use a secure transport, such as USB or TLS.
  boolean secure;
};

// Contains a list of option names. The groups and their contents are
// determined by the scanner driver and do not have any defined semantics
// or consistent membership. This structure is primarily intended
// for UI layout assistance; it does not affect individual option
// behaviors.
dictionary OptionGroup {
  // Provides a printable title, for example "Geometry options".
  required DOMString title;

  // An array of option names in driver-provided order.
  required sequence<DOMString> members;
};

// The response from $(ref:getScannerList).
dictionary GetScannerListResponse {
  // The enumeration result. Note that partial results could be
  // returned even if this indicates an error.
  required OperationResult result;

  // A possibly-empty list of scanners that match the provided
  // $(ref:DeviceFilter).
  required sequence<ScannerInfo> scanners;
};

// The response from $(ref:openScanner).
dictionary OpenScannerResponse {
  // The scanner ID passed to <code>openScanner()</code>.
  required DOMString scannerId;

  // The result of opening the scanner. If the value of this is
  // <code>SUCCESS</code>, the <code>scannerHandle</code> and
  // <code>options</code> properties will be populated.
  required OperationResult result;

  // If <code>result</code> is <code>SUCCESS</code>, a
  // handle to the scanner that can be used for further operations.
  DOMString? scannerHandle;

  // If <code>result</code> is <code>SUCCESS</code>,
  // provides a key-value mapping where the key is a device-specific
  // option and the value is an instance of $(ref:ScannerOption).
  object? options;
};

// The response from $(ref:getOptionGroups).
dictionary GetOptionGroupsResponse {
  // The same scanner handle as was passed to $(ref:getOptionGroups).
  required DOMString scannerHandle;

  // The result of getting the option groups. If the value of this is
  // <code>SUCCESS</code>, the <code>groups</code> property will be
  // populated.
  required OperationResult result;

  // If <code>result</code> is <code>SUCCESS</code>, provides a
  // list of option groups in the order supplied by the scanner driver.
  sequence<OptionGroup> groups;
};

// The response from <code>closeScanner()</code>.
dictionary CloseScannerResponse {
  // The same scanner handle as was passed to $(ref:closeScanner).
  required DOMString scannerHandle;

  // The result of closing the scanner. Even if this value is not
  // <code>SUCCESS</code>, the handle will be invalid and
  // should not be used for any further operations.
  required OperationResult result;
};

// Passed to $(ref:setOptions) to set an option to $(ref:ScannerOption) to
// a new value.
dictionary OptionSetting {
  // Indicates the name of the option to set.
  required DOMString name;

  // Indicates the data type of the option. The requested data type must
  // match the real data type of the underlying option.
  required OptionType type;

  // Indicates the value to set. Leave unset to request automatic setting for
  // options that have <code>autoSettable</code> enabled. The data type
  // supplied for <code>value</code> must match <code>type</code>.
  (boolean or double or sequence<double> or long or sequence<long> or
   DOMString)? value;
};

// The result of setting an individual option.  Each individual option
// supplied to <code>setOptions()</code> produces a separate result
// due to things like rounding and constraints.
dictionary SetOptionResult {
  // Indicates the name of the option that was set.
  required DOMString name;

  // Indicates the result of setting the option.
  required OperationResult result;
};

// The response from a call to $(ref:setOptions).
dictionary SetOptionsResponse {
  // Provides the scanner handle passed to <code>setOptions()</code>.
  required DOMString scannerHandle;

  // An array of results, one each for every passed-in
  // <code>OptionSetting</code>.
  required sequence<SetOptionResult> results;

  // An updated key-value mapping from option names to
  // $(ref:ScannerOption) values containing the new configuration after
  // attempting to set all supplied options. This has the same structure as
  // the <code>options</code> property in $(ref:OpenScannerResponse).
  //
  // This property will be set even if some options were not set successfully,
  // but will be unset if retrieving the updated configuration fails (for
  // example, if the scanner is disconnected in the middle of scanning).
  object? options;
};

// Specifies options for $(ref:startScan).
dictionary StartScanOptions {
  // Specifies the MIME type to return scanned data in.
  required DOMString format;

  // If a non-zero value is specified, limits the maximum scanned bytes
  // returned in a single $(ref:readScanData) response to that value.  The
  // smallest allowed value is 32768 (32 KB).  If this property is not
  // specified, the size of a returned chunk may be as large as the entire
  // scanned image.
  long maxReadSize;
};

// The response from <code>startScan()</code>.
dictionary StartScanResponse {
  // Provides the same scanner handle that was passed to
  // <code>startScan()</code>.
  required DOMString scannerHandle;

  // The result of starting a scan. If the value of this is
  // <code>SUCCESS</code>, the <code>job</code> property will be populated.
  required OperationResult result;

  // If <code>result</code> is <code>SUCCESS</code>, provides a
  // handle that can be used to read scan data or cancel the job.
  DOMString? job;
};

// The response from <code>cancelScan()</code>.
dictionary CancelScanResponse {
  // Provides the same job handle that was passed to
  // <code>cancelScan()</code>.
  required DOMString job;

  // The backend's cancel scan result. If the result is
  // <code>OperationResult.SUCCESS</code> or
  // <code>OperationResult.CANCELLED</code>, the scan has been cancelled and
  // the scanner is ready to start a new scan.  If the result is
  // <code>OperationResult.DEVICE_BUSY </code>, the scanner is still
  // processing the requested cancellation; the caller should wait a short
  // time and try the request again. Other result values indicate a permanent
  // error that should not be retried.
  required OperationResult result;
};

// The response from $(ref:readScanData).
dictionary ReadScanDataResponse {
  // Provides the job handle passed to <code>readScanData()</code>.
  required DOMString job;

  // The result of reading data. If its value is
  // <code>SUCCESS</code>, then <code>data</code> contains the
  // <em>next</em> (possibly zero-length) chunk of image data that is ready
  // for reading. If its value is <code>EOF</code>, the <code>data</code>
  // contains the <em>last</em> chunk of image data.
  required OperationResult result;

  // If <code>result</code> is <code>SUCCESS</code>, contains
  // the <em>next</em> chunk of scanned image data. If <code>result</code> is
  // <code>EOF</code>, contains the <em>last</em> chunk of
  // scanned image data.
  ArrayBuffer? data;

  // If <code>result</code> is <code>SUCCESS</code>, an estimate of
  // how much of the total scan data has been delivered so far, in the range
  // 0 to 100.
  long? estimatedCompletion;
};

// Use the <code>chrome.documentScan</code> API to discover and retrieve
// images from attached document scanners.
[platforms=("chromeos"),
 implemented_in="chrome/browser/extensions/api/document_scan/document_scan_api.h"]
interface DocumentScan {
  // Performs a document scan and returns a Promise that resolves
  // with a $(ref:ScanResults) object. If a callback is passed to
  // this function, the returned data is passed to it instead.
  // |options| : An object containing scan parameters.
  // |Returns| : Returns a Promise which resolves with the scan results.
  // |PromiseValue| : result
  static Promise<ScanResults> scan(ScanOptions options);

  // Gets the list of available scanners and returns a Promise that
  // resolves with a $(ref:GetScannerListResponse) object. If a callback
  // is passed to this function, returned data is passed to it instead.
  // |filter| : A $(ref:DeviceFilter) indicating which types of scanners
  // should be returned.
  // |Returns| : Returns a Promise which resolves with the result and list of
  // scanners.
  // |PromiseValue| : response
  static Promise<GetScannerListResponse> getScannerList(DeviceFilter filter);

  // Opens a scanner for exclusive access and returns a Promise that
  // resolves with an $(ref:OpenScannerResponse) object. If a callback
  // is passed to this function, returned data is passed to it instead.
  // |scannerId| : The ID of a scanner to be opened. This value is one
  // returned from a previous call to $(ref:getScannerList).
  // |Returns| : Returns a Promise which resolves with the result.
  // |PromiseValue| : response
  static Promise<OpenScannerResponse> openScanner(DOMString scannerId);

  // Gets the group names and member options from a scanner previously
  // opened by $(ref:openScanner). This method returns a Promise that
  // resolves with a $(ref:GetOptionGroupsResponse) object. If a callback
  // is passed to this function, returned data is passed to it instead.
  // |scannerHandle| : The handle of an open scanner returned from a call
  // to $(ref:openScanner).
  // |Returns| : Returns a Promise which resolves with the result.
  // |PromiseValue| : response
  static Promise<GetOptionGroupsResponse> getOptionGroups(
      DOMString scannerHandle);

  // Closes the scanner with the passed in handle and returns a Promise
  // that resolves with a $(ref:CloseScannerResponse) object. If a callback
  // is used, the object is passed to it instead. Even if the response is
  // not a success, the supplied handle becomes invalid and should not be
  // used for further operations.
  // |scannerHandle| : Specifies the handle of an open scanner that was
  // previously returned from a call to $(ref:openScanner).
  // |Returns| : Returns a Promise which resolves with the result.
  // |PromiseValue| : response
  static Promise<CloseScannerResponse> closeScanner(DOMString scannerHandle);

  // Sets options on the specified scanner and returns a Promise that
  // resolves with a $(ref:SetOptionsResponse) object containing the
  // result of trying to set every value in the order of the passed-in
  // $(ref:OptionSetting) object. If a callback is used, the object is
  // passed to it instead.
  // |scannerHandle| : The handle of the scanner to set options on. This
  // should be a value previously returned from a call to $(ref:openScanner).
  // |options| : A list of <code>OptionSetting</code> objects to be applied to
  // the scanner.
  // |Returns| : Returns a Promise which resolves with the result.
  // |PromiseValue| : response
  static Promise<SetOptionsResponse> setOptions(
      DOMString scannerHandle, sequence<OptionSetting> options);

  // Starts a scan on the specified scanner and returns a Promise that
  // resolves with a $(ref:StartScanResponse). If a callback is used,
  // the object is passed to it instead. If the call was successful, the
  // response includes a job handle that can be used in subsequent calls
  // to read scan data or cancel a scan.
  // |scannerHandle| : The handle of an open scanner. This should be a value
  // previously returned from a call to $(ref:openScanner).
  // |options| : A $(ref:StartScanOptions) object indicating the options to
  // be used for the scan. The <code>StartScanOptions.format</code> property
  // must match one of the entries returned in the scanner's
  // <code>ScannerInfo</code>.
  // |Returns| : Returns a Promise which resolves with the result.
  // |PromiseValue| : response
  static Promise<StartScanResponse> startScan(
      DOMString scannerHandle, StartScanOptions options);

  // Cancels a started scan and returns a Promise that resolves with a
  // $(ref:CancelScanResponse) object. If a callback is used, the object
  // is passed to it instead.
  // |job| : The handle of an active scan job previously returned from a
  // call to $(ref:startScan).
  // |Returns| : Returns a Promise which resolves with the result.
  // |PromiseValue| : response
  static Promise<CancelScanResponse> cancelScan(DOMString job);

  // Reads the next chunk of available image data from an active job handle,
  // and returns a Promise that resolves with a $(ref:ReadScanDataResponse)
  // object. If a callback is used, the object is passed to it instead.
  //
  // <aside class="note"><b>Note:</b>It is valid for a response result to be
  // <code>SUCCESS</code> with a zero-length <code>data</code>
  // member. This means the scanner is still working but does not yet have
  // additional data ready. The caller should wait a short time and try again.
  //
  // When the scan job completes, the response will have the result value of
  // <code>EOF</code>. This response may contain a final
  // non-zero <code>data</code> member.</aside>
  //
  // |job| : Active job handle previously returned from
  // $(ref:startScan).
  // |Returns| : Returns a Promise which resolves with the result.
  // |PromiseValue| : response
  static Promise<ReadScanDataResponse> readScanData(DOMString job);
};

partial interface Browser {
  static attribute DocumentScan documentScan;
};