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

// Use the <code>chrome.documentScan</code> API to discover and retrieve
// images from attached paper document scanners.
[platforms=("chromeos", "lacros"),
implemented_in="chrome/browser/extensions/api/document_scan/document_scan_api.h"]
namespace documentScan {
  dictionary ScanOptions {
    // The MIME types that are accepted by the caller.
    DOMString[]? mimeTypes;

    // The number of scanned images allowed (defaults to 1).
    long? maxImages;
  };

  dictionary ScanResults {
    // The data image URLs in a form that can be passed as the "src" value to
    // an image tag.
    DOMString[] dataUrls;

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

  // OperationResult is an enum that indicates the result of each operation
  // performed by the backend.  It contains the same causes as SANE_Status plus
  // additional statuses that come from the IPC layers and image conversion
  // stages.
  [nodoc] enum OperationResult {
    // An unknown or generic failure occurred.
    UNKNOWN,

    // Operation succeeded.
    SUCCESS,

    // The operation is not supported.
    UNSUPPORTED,

    // The operation was cancelled.
    CANCELLED,

    // The device is busy.
    DEVICE_BUSY,

    // Data or argument is invalid.
    INVALID,

    // Value is the wrong 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 was available to complete the operation.
    NO_MEMORY,

    // The device was not reachable.
    UNREACHABLE,

    // The device was disconnected.
    MISSING,

    // An internal error occurred.
    INTERNAL_ERROR
  };

  // How the scanner is connected to the computer.
  [nodoc] enum ConnectionType {
    UNSPECIFIED,
    USB,
    NETWORK
  };

  // ScannerInfo contains general information about a scanner device.  It is
  // intended for filtering and constructing user-facing information, not for
  // configuring a scan.
  [nodoc] dictionary ScannerInfo {
    // For connecting with <code>openScanner</code>.
    DOMString scannerId;

    // Printable name for displaying in the UI.
    DOMString name;

    // Scanner manufacturer.
    DOMString manufacturer;

    // Scanner model if available, or a generic description.
    DOMString model;

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

    // How the scanner is connected to the computer.
    ConnectionType connectionType;

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

    // MIME types that can be requested for returned scans.
    DOMString[] imageFormats;
  };

  // The type of an option.  This is the same set of types as SANE_Value_Type.
  [nodoc] enum OptionType {
    // Unknown option type.  <code>value</code> will be unset.
    UNKNOWN,

    // true/false only.  <code>value</code> will be a boolean.
    BOOL,

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

    // Double in the range -32768-32767.9999 with a resolution of 1/65535.
    // <code>value</code> will be double or double[] depending on whether the
    // option takes more than one value.
    FIXED,

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

    // Hardware button or toggle.  No value.
    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
  };

  // The unit of measurement for an option.  This is the same set of units as
  // SANE_Unit.
  [nodoc] enum OptionUnit {
    // Value is a unitless number, e.g. threshold.
    UNITLESS,

    // Value is a number of pixels, e.g., scan dimensions.
    PIXEL,

    // Value is the number of bits, e.g., color depth.
    BIT,

    // Value is measured in millimeters, e.g., scan dimensions.
    MM,

    // Value is measured in dots per inch, e.g., resolution.
    DPI,

    // Value is a percent, e.g., brightness.
    PERCENT,

    // Value is measured in microseconds, e.g., exposure time.
    MICROSECOND
  };

  // The type of constraint represented by an OptionConstraint.
  [nodoc] enum ConstraintType {
    // Constraint represents a range of <code>OptionType.INT</code> values.
    // <code>min</code>, <code>max</code>, and <code>quant</code> will be
    // <code>long</code>, and <code>list</code> will be unset.
    INT_RANGE,

    // Constraint represents a range of <code>OptionType.FIXED</code> values.
    // <code>min</code>, <code>max</code>, and <code>quant</code> will be
    // <code>double</code>, and <code>list</code> will be unset.
    FIXED_RANGE,

    // Constraint represents a specific list of <code>OptionType.INT</code>
    // values.  <code>list</code> will contain <code>long</code> values, and
    // the other fields will be unset.
    INT_LIST,

    // Constraint represents a specific list of <code>OptionType.FIXED</code>
    // values.  <code>list</code> will contain <code>double</code> values, and
    // the other fields will be unset.
    FIXED_LIST,

    // Constraint represents a specific list of <code>OptionType.STRING</code>
    // values.  <code>list</code> will contain <code>DOMString</code> values,
    // and the other fields will be unset.
    STRING_LIST
  };

  // <code>OptionConstraint</code> represents the same set of value constraints
  // as SANE_Constraint_Type, with the exception that an unconstrained value is
  // represented by a lack of constraint rather than a special
  // SANE_CONSTRAINT_NONE value.
  [nodoc] dictionary OptionConstraint {
      ConstraintType type;
      (long or double)? min;
      (long or double)? max;
      (long or double)? quant;
      (double[] or long[] or DOMString[])? list;
  };

  // How an option can be changed.
  [nodoc] enum Configurability {
      // Option is read-only and cannot be changed.
      NOT_CONFIGURABLE,

      // Option can be set in software.
      SOFTWARE_CONFIGURABLE,

      // Option can be set by the user toggling/pushing a hardware button.
      HARDWARE_CONFIGURABLE
  };

  // A self-describing configurable scanner option and current value, in the
  // same style as SANE's SANE_Option_Descriptor and sane_control_option().
  [nodoc] dictionary ScannerOption {
    // Option name using lowercase a-z, numbers, and dashes.
    DOMString name;

    // Printable one-line title.
    DOMString title;

    // Longer description of the option.
    DOMString description;

    // The type that <code>value</code> will contain and that is needed for
    // setting this option.
    OptionType type;

    // Unit of measurement for this option.
    OptionUnit unit;

    // Current value of the option if relevant. Note the type passed here must
    // match the type specified in <code>type</code>.
    (boolean or double or double[] or long or long[] or DOMString)? value;

    // Constraint on possible values.
    OptionConstraint? constraint;

    // Can be detected from software.
    boolean isDetectable;

    // Whether/how the option can be changed.
    Configurability configurability;

    // Can be automatically set by the backend.
    boolean isAutoSettable;

    // Emulated by the backend if true.
    boolean isEmulated;

    // Option is active and can be set/retrieved.  If false, the
    // <code>value</code> field will not be set.
    boolean isActive;

    // UI should not display this option by default.
    boolean isAdvanced;

    // Option is used for internal configuration and should never be displayed
    // in the UI.
    boolean isInternal;
  };

  // A set of criteria passed to <code>getScannerList()</code>.  Only devices
  // that match all of the criteria will be returned.
  [nodoc] 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;
  };

  // OptionGroup is a group containing a list of option names.  The groups and
  // their contents are determined by the backend and do not have any defined
  // semantics or consistent membership.  This structure is primarily intended
  // for UI layout assistance; it does not affect the individual option
  // behaviors.
  [nodoc] dictionary OptionGroup {
    // Printable title, e.g. "Geometry options".
    DOMString title;

    // Names of contained options, in backend-provided order.
    DOMString[] members;
  };

  // The response from <code>getScannerList()</code>.
  [nodoc] dictionary GetScannerListResponse {
    // The backend's enumeration result.  Note that partial results could be
    // returned even if this indicates an error.
    OperationResult result;

    // A possibly-empty list of scanners that match the provided
    // <code>DeviceFilter</code>.
    ScannerInfo[] scanners;
  };

  // The response from <code>openScanner()</code>.
  [nodoc] dictionary OpenScannerResponse {
    // Same scanner ID passed to <code>openScanner()</code>.
    DOMString scannerId;

    // Backend result of opening the scanner.
    OperationResult result;

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

    // If <code>result</code> is <code>OperationResult.SUCCESS</code>, a
    // key-value mapping from option names to <code>ScannerOption</code>.
    object? options;
  };

  // The response from <code>getOptionGroups()</code>.
  [nodoc] dictionary GetOptionGroupsResponse {
    // Same scanner handle passed to <code>getOptionGroups()</code>.
    DOMString scannerHandle;

    // The backend's result of getting the option groups.
    OperationResult result;

    // If <code>result</code> is <code>OperationResult.SUCCESS</code>, a list of
    // option groups in the order supplied by the backend.
    OptionGroup[]? groups;
  };

  // The response from <code>closeScanner()</code>.
  [nodoc] dictionary CloseScannerResponse {
    // Same scanner handle passed to <code>closeScanner()</code>.
    DOMString scannerHandle;

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

  // A subset of <code>ScannerOption</code> that contains enough information to
  // set an option to a new value.
  [nodoc] dictionary OptionSetting {
    // Name of the option to set.
    DOMString name;

    // Type of the option.  The requested type must match the real type of the
    // underlying option.
    OptionType type;

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

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

    // Backend result of setting the option.
    OperationResult result;
  };

  // The response from a call to <code>setOptions()</code>.
  [nodoc] dictionary SetOptionsResponse {
    // The same scanner handle passed to <code>setOptions()</code>.
    DOMString scannerHandle;

    // One result per passed-in <code>OptionSetting</code>.
    SetOptionResult[] results;

    // Updated key-value mapping from option names to
    // <code>ScannerOption</code> containing the new configuration after
    // attempting to set all supplied options.  This has the same structure as
    // the <code>options</code> field in <code>OpenScannerResponse</code>.
    //
    // This field will be set even if some options were not set successfully,
    // but will be unset if retrieving the updated configuration fails (e.g.,
    // if the scanner is disconnected in the middle).
    object? options;
  };

  // Used to specify options for <code>startScan()</code>.
  [nodoc] dictionary StartScanOptions {
    // MIME type to return scanned data in.
    DOMString format;
  };

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

    // The backend's start scan result.
    OperationResult result;

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

  // The response from <code>cancelScan()</code>.
  [nodoc] dictionary CancelScanResponse {
    // The same job handle that was passed to <code>cancelScan()</code>.
    DOMString job;

    // The backend's cancel scan result.
    OperationResult result;
  };

  // The response from <code>readScanData()</code>.
  [nodoc] dictionary ReadScanDataResponse {
    // Same job handle passed to <code>readScanData()</code>.
    DOMString job;

    // The backend result of reading data.  If this is
    // <code>OperationResult.SUCCESS</code>, <code>data</code> will contain the
    // next (possibly zero-length) chunk of image data that was ready for
    // reading.  If this is <code>OperationResult.EOF</code>, <code>data</code>
    // will contain the final chunk of image data.
    OperationResult result;

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

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

  // Callback from the <code>scan</code> method.
  // |result| The results from the scan, if successful.
  // Otherwise will return null and set runtime.lastError.
  callback ScanCallback = void (ScanResults result);

  // Callback from the <code>getScannerList</code> method.
  // |response| The response from enumeration, if the call was valid.
  // Otherwise will return null and set runtime.lastError.
  [nodoc] callback GetScannerListCallback = void (GetScannerListResponse response);

  // Callback from the <code>openScanner</code> method.
  // |response| The response from opening the scanner, if the call was valid.
  // Otherwise will return null and set runtime.lastError.
  [nodoc] callback OpenScannerCallback = void (OpenScannerResponse response);

  // Callback from the <code>getOptionGroups</code> method.
  // |response| The response from getting the option groups, if the call was
  // valid.  Otherwise will return null and set runtime.lastError.
  [nodoc] callback GetOptionGroupsCallback =
      void (GetOptionGroupsResponse response);

  // Callback from the <code>closeScanner</code> method.
  // |response| The response from closing the scanner, if the call was valid.
  // Otherwise will return null and set runtime.lastError.
  [nodoc] callback CloseScannerCallback = void (CloseScannerResponse response);

  // Callback from the <code>setOptions</code> method.
  // |response| The response from setting the options, if the call was valid.
  // Otherwise will return null and set runtime.lastError.
  [nodoc] callback SetOptionsCallback = void (SetOptionsResponse response);

  // Callback from the <code>startScan</code> method.
  // |response| The response from starting the scan, if the call was valid.
  // Otherwise will return null and set runtime.lastError.
  [nodoc] callback StartScanCallback = void (StartScanResponse response);

  // Callback from the <code>cancelScan</code> method.
  // |response| The response from canceling the scan, if the call was valid.
  // Otherwise will return null and set runtime.lastError.
  [nodoc] callback CancelScanCallback = void (CancelScanResponse response);

  // Callback from the <code>readScanData</code> method.
  // |response| The response from reading the next chunk of scanned image data,
  // if the call was valid.  Otherwise will return null and set
  // runtime.lastError.
  [nodoc] callback ReadScanDataCallback = void (ReadScanDataResponse response);

  interface Functions {
    // Performs a document scan.  On success, the PNG data will be
    // sent to the callback.
    // |options| : Object containing scan parameters.
    // |callback| : Called with the result and data from the scan.
    [supportsPromises] static void scan(ScanOptions options,
                                        ScanCallback callback);

    // Gets the list of available scanners.  On success, the list will be
    // sent to the callback.
    // |filter| : <code>DeviceFilter</code> indicating which types of scanners
    // should be returned.
    // |callback| : Called with the result and list of scanners.
    [nodoc, supportsPromises] static void getScannerList(
        DeviceFilter filter, GetScannerListCallback callback);

    // Opens a scanner for exclusive access.  On success, the response containing
    // a scanner handle and configuration will be sent to the callback.
    // |scannerId| : Scanner id previously returned from <code>getScannerList</code>
    // indicating which scanner should be opened.
    // |callback| : Called with the result.
    [nodoc, supportsPromises] static void openScanner(
        DOMString scannerId, OpenScannerCallback callback);

    // Gets the group names and member options from a scanner handle previously
    // opened by <code>openScanner</code>.
    // |scannerHandle| : Open scanner handle previously returned from
    // <code>openScanner</code>.
    // |callback| : Called with the result.
    [nodoc, supportsPromises] static void getOptionGroups(
        DOMString scannerHandle, GetOptionGroupsCallback callback);

    // Closes a previously opened scanner handle.  A response indicating the
    // outcome will be sent to the callback.  Even if the response is not a
    // success, the supplied handle will become invalid and should not be used
    // for further operations.
    // |scannerHandle| : Open scanner handle previously returned from
    // <code>openScanner</code>.
    // |callback| : Called with the result.
    [nodoc, supportsPromises] static void closeScanner(
        DOMString scannerHandle, CloseScannerCallback callback);

    // Sends the list of new option values in <code>options</code> as a bundle
    // to be set on <code>scannerHandle</code>.  Each option will be set by the
    // backend the order specified.  Returns a backend response indicating the
    // result of each option setting and a new set of final option values after
    // all options have been updated.
    // |scannerHandle| : Open scanner handle previously returned from
    // <code>openScanner</code>.
    // |options| : A list of <code>OptionSetting</code>s that will be applied to
    // <code>scannerHandle</code>.
    // |callback| : Called with the result.
    [nodoc, supportsPromises] static void setOptions(
        DOMString scannerHandle, OptionSetting[] options,
        SetOptionsCallback callback);

    // Starts a scan using a previously opened scanner handle.  A response
    // indicating the outcome will be sent to the callback.  If successful, the
    // response will include a job handle that can be used in subsequent calls
    // to read scan data or cancel a scan.
    // |scannerHandle| : Open scanner handle previously returned from
    // <code>openScanner</code>.
    // |options| : <code>StartScanOptions</code> indicating what options are to
    // be used for the scan.  <code>StartScanOptions.format</code> must match
    // one of the entries returned in the scanner's <code>ScannerInfo</code>.
    // |callback| : Called with the result.
    [nodoc, supportsPromises] static void startScan(
        DOMString scannerHandle, StartScanOptions options,
        StartScanCallback callback);

    // Cancels a scan that was previously started using <code>startScan</code>.
    // The response is sent to the callback.
    // |job| : An active scan job previously returned from
    // <code>startScan</code>.
    // |callback| : Called with the result.
    [nodoc, supportsPromises] static void cancelScan(
        DOMString job, CancelScanCallback callback);

    // Reads the next chunk of available image data from an active job handle.
    // A response indicating the outcome will be sent to the callback.
    //
    // It is valid for a response to have result
    // <code>OperationResult.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
    // <code>OperationResult.EOF</code>.  This response may contain a final
    // non-zero <code>data</code> member.
    // |job| : Active job handle previously returned from
    // <code>startScan</code>.
    // |callback| : Called with the result.
    [nodoc, supportsPromises] static void readScanData(
        DOMString job, ReadScanDataCallback callback);
  };
};