Implement a JavaScript API for document scanning

chrome/common/extensions/api/document_scan.idl

Index: chrome/common/extensions/api/document_scan.idl
diff --git a/chrome/common/extensions/api/document_scan.idl b/chrome/common/extensions/api/document_scan.idl
new file mode 100644
index 0000000000000000000000000000000000000000..ca44ea38c93e110ebb4c7306745a8e2b5172f227
--- /dev/null
+++ b/chrome/common/extensions/api/document_scan.idl
@@ -0,0 +1,55 @@
+// Copyright 2014 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Use the <code>chrome.document_scan</code> API to discover and retrieve
+// images from attached paper document scanners.
+namespace documentScan {
+
+  // Represents a document scanner's properties.
+  dictionary ScannerInfo {
+    // The name of an connected scanner.

[asargent_no_longer_on_chrome, 2014/05/21 18:06:24]

nit: "an" -> "a" (I think - if you are a grammar wizard feel free to let me know
I'm wrong along with optional Strunk and White citation :) )

[Paul Stewart, 2014/05/22 18:37:50]

Done.

+    DOMString name;
+
+    // The manufacturer name of the scanner.
+    DOMString manufacturer;
+
+    // The model name of the scanner.
+    DOMString model;
+
+    // The type of scanner.
+    DOMString type;
+  };
+
+  dictionary ScanOptions {
+    // The mode to perform the scan in: color, gray or lineart.
+    DOMString? mode;

[asargent_no_longer_on_chrome, 2014/05/21 18:06:24]

nit: instead of just using a string, it would be better to define a named enum
for this. E.g.

enum ScanMode { color, gray, lineart };

dictionary ScanOptions {
  ScanMode? mode;

  ...
};


That way you'll get parameter validation at runtime for free from the extension
API plumbing. 

[Paul Stewart, 2014/05/22 18:37:50]

Done.

+
+    // The resolution in dpi to perform the scan.
+    long? resolutionDpi;
+  };
+
+  // Callback from the <code>listScanners</code> method.
+  callback ListScannersCallback = void (ScannerInfo[] scannerInfos);
+
+  // Callback from the <code>scan</code> method; on success (result == true)
+  // PNG image data from the scan is returned in |image_data|.  The image
+  // is also saved to the user's download folder.
+  callback ScanCallback = void (boolean result, ArrayBuffer image_data);

[asargent_no_longer_on_chrome, 2014/05/21 18:06:24]

The prevailing style for a long time has been to avoid using explicit boolean
success/failure parameters in callbacks, instead favoring the built in
"chrome.runtime.lastError" which gets auto-populated when your
AsyncApiFunction::Respond override function returns false (and any
developer-readable error message that you put into your error_ member variable
will be available to the JS as chrome.runtime.lastError.message). 

(We've talked about perhaps moving to JS promises in the future for callbacks,
but AFAIK we aren't there yet). 

[Paul Stewart, 2014/05/22 18:37:50]

Done.

+
+  interface Functions {
+    // Returns information about available scanners on the system.
+    // The list is regenerated each time this method is called.
+    // |callback| : Called with the list of <code>ScannerInfo</code> objects.
+    static void listScanners(ListScannersCallback callback);
+
+    // Performs a document scan.  On success, ths image data will be stored in

[asargent_no_longer_on_chrome, 2014/05/21 18:06:24]

typo: "ths"

[Paul Stewart, 2014/05/22 18:37:50]

Done.

+    // the user's download folder, and the PNG data will also be
+    // sent to the callback.

[asargent_no_longer_on_chrome, 2014/05/21 18:06:24]

It seems slightly strange to me to have both a file generated in the downloads
folder and have the data returned back in an array buffer. Perhaps it would make
sense to make this an option either with an explicit parameter to this method,
or (if for instance there was a default that we think most developers would want
most of the time) as a member developers can set in the ScanOptions dictionary. 

Also, when developers choose the "scan to a file" option, it might be cool to be
able to return to them the download id that they could then turn around and call
chrome.downloads.show on
(https://developer.chrome.com/extensions/downloads#method-show). I'm not sure if
calling that method requires the "downloads" permission, but it seems like it
would not necessarily have to. Or we could add an optional flag to this method
to just tell the system that chrome itself should show the download in the
Downloads folder when the scan is done. 

(Apologies if you've already had API design discussions about all this with
other folks from the apps/extensions team, and this is bikeshedding something
there was already a consensus on)

[Paul Stewart, 2014/05/22 18:37:50]

I've been thinking about this myself as well.  I think I've decided
to drop the automatic download-to-file component completely.  If the
app chooses (and has permissions to do so), it can save to disk all
by itself.

+    // |scanner| : Name of the scanner to acquire an image from.
+    // |options| : <code>ScanObject</code> object containing scan parameters.
+    // |callback| : Called with the result and data from the scan.
+    static void scan(DOMString scanner, ScanOptions options,
+                     ScanCallback callback);
+  };
+};