// 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 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. 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.
DOMString[] dataUrls;
// The MIME type of the <code>dataUrls</code>.
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.
DOMString scannerId;
// A human-readable name for the scanner to display in the UI.
DOMString name;
// The scanner manufacturer.
DOMString manufacturer;
// The scanner model if it is available, or a generic description.
DOMString model;
// For matching against other <code>ScannerInfo</code> entries that point
// to the same physical device.
DOMString deviceUuid;
// Indicates 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;
// An array of MIME types that can be requested for returned scans.
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.
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 {
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.
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.
DOMString name;
// A printable one-line title.
DOMString title;
// A longer description of the option.
DOMString description;
// The data type contained in the <code>value</code> property, which
// is needed for setting this option.
OptionType type;
// The unit of measurement for this option.
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 double[] or long or long[] or DOMString)? value;
// Defines $(ref:OptionConstraint) on the current scanner option.
OptionConstraint? constraint;
// Indicates that this option can be detected from software.
boolean isDetectable;
// Indicates whether and how the option can be changed.
Configurability configurability;
// Can be automatically set by the scanner driver.
boolean isAutoSettable;
// Emulated by the scanner driver if true.
boolean isEmulated;
// Indicates the option is active and can be set or retrieved. If false,
// the <code>value</code> property will not be set.
boolean isActive;
// Indicates that the UI should not display this option by default.
boolean isAdvanced;
// Indicates that the 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.
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".
DOMString title;
// An array of option names in driver-provided order.
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.
OperationResult result;
// A possibly-empty list of scanners that match the provided
// $(ref:DeviceFilter).
ScannerInfo[] scanners;
};
// The response from $(ref:openScanner).
dictionary OpenScannerResponse {
// The scanner ID passed to <code>openScanner()</code>.
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.
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).
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.
OperationResult result;
// If <code>result</code> is <code>SUCCESS</code>, provides a
// list of option groups in the order supplied by the scanner driver.
OptionGroup[]? groups;
};
// The response from <code>closeScanner()</code>.
dictionary CloseScannerResponse {
// The same scanner handle as was passed to $(ref:closeScanner).
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.
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.
DOMString name;
// Indicates the data type of the option. The requested data type must
// match the real data type of the underlying option.
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 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
// due to things like rounding and constraints.
dictionary SetOptionResult {
// Indicates the name of the option that was set.
DOMString name;
// Indicates the result of setting the option.
OperationResult result;
};
// The response from a call to $(ref:setOptions).
dictionary SetOptionsResponse {
// Provides the scanner handle passed to <code>setOptions()</code>.
DOMString scannerHandle;
// An array of results, one each for every passed-in
// <code>OptionSetting</code>.
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.
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>.
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.
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>.
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.
OperationResult result;
};
// The response from $(ref:readScanData).
dictionary ReadScanDataResponse {
// Provides the job handle passed to <code>readScanData()</code>.
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.
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;
};
// Callback from the $(ref:scan) method.
// |result| Provides the results from the scan, if successful.
// Otherwise, this value will be null and $(ref:runtime.lastError)
// will be set.
callback ScanCallback = void (ScanResults result);
// Callback from the $(ref:getScannerList) method.
// |response| The response from enumeration, if the call was valid.
// Otherwise, this value will be null and $(ref:runtime.lastError)
// will be set.
callback GetScannerListCallback = void (GetScannerListResponse response);
// Callback from the $(ref:openScanner) method.
// |response| The response from opening the scanner, if the call was valid.
// Otherwise, this value will be null and $(ref:runtime.lastError)
// will be set.
callback OpenScannerCallback = void (OpenScannerResponse response);
// Callback from the $(ref:getOptionGroups) method.
// |response| The response from getting the option groups, if the call was
// valid. Otherwise, this value will be null and $(ref:runtime.lastError)
// will be set.
callback GetOptionGroupsCallback =
void (GetOptionGroupsResponse response);
// Callback from the $(ref:closeScanner) method.
// |response| The response from closing the scanner, if the call was valid.
// Otherwise, this value will be null and $(ref:runtime.lastError)
// will be set.
callback CloseScannerCallback = void (CloseScannerResponse response);
// Callback from the $(ref:setOptions) method.
// |response| The response from setting the options, if the call was valid.
// Otherwise, this value will be null and $(ref:runtime.lastError)
// will be set.
callback SetOptionsCallback = void (SetOptionsResponse response);
// Callback from the $(ref:startScan) method.
// |response| The response from starting the scan, if the call was valid.
// Otherwise, this value will be null and $(ref:runtime.lastError)
// will be set.
callback StartScanCallback = void (StartScanResponse response);
// Callback from the $(ref:cancelScan) method.
// |response| The response from canceling the scan, if the call was valid.
// Otherwise, this value will be null and $(ref:runtime.lastError)
// will be set.
callback CancelScanCallback = void (CancelScanResponse response);
// Callback from the $(ref:readScanData) method.
// |response| The response from reading the next chunk of scanned image data,
// if the call was valid. Otherwise, this value will be null and
// $(ref:runtime.lastError) will be set.
callback ReadScanDataCallback = void (ReadScanDataResponse response);
interface Functions {
// 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.
// |callback| : Called with the result and data from the scan.
static void scan(
ScanOptions options,
ScanCallback callback);
// 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.
// |callback| : Called with the result and list of scanners.
static void getScannerList(
DeviceFilter filter, GetScannerListCallback callback);
// 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).
// |callback| : Called with the result.
static void openScanner(
DOMString scannerId, OpenScannerCallback callback);
// 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).
// |callback| : Called with the result.
static void getOptionGroups(
DOMString scannerHandle, GetOptionGroupsCallback callback);
// 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).
// |callback| : Called with the result.
static void closeScanner(
DOMString scannerHandle, CloseScannerCallback callback);
// 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.
// |callback| : Called with the result.
static void setOptions(
DOMString scannerHandle, OptionSetting[] options,
SetOptionsCallback callback);
// 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>.
// |callback| : Called with the result.
static void startScan(
DOMString scannerHandle, StartScanOptions options,
StartScanCallback callback);
// 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).
// |callback| : Called with the result.
static void cancelScan(
DOMString job, CancelScanCallback callback);
// 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).
// |callback| : Called with the result.
static void readScanData(
DOMString job, ReadScanDataCallback callback);
};
};
Codebase Browser
chromium