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..16a1cdcae3fb7a190d77ee3d46c7eedfd384070a
--- /dev/null
+++ b/chrome/common/extensions/api/document_scan.idl
@@ -0,0 +1,36 @@
+// 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 {
+  dictionary ScanOptions {
+    // The MIME types that are accepted by the caller.
+    DOMString[]? mimeTypes;
+
+    // The number of scanned images allowed (defaults to 1).
+    long? maxImages;

[asargent_no_longer_on_chrome, 2014/10/23 22:15:57]

How are we expecting developers to handle multi-page documents from a scanner?
It seems like having them pass maxImages presumes them having some advance
knowledge of the possible number of pages they might get? 

Is the idea that they will keep calling the scan() function with as high a
maxImages number as they are willing to get pages at once, and then when the
last scan() call returns 0 or something < maxImages, they know that all pages
have been scanned?

[Paul Stewart, 2014/10/23 23:06:58]

This is simply a hint to the UI handling the image capture to tell it how many
images the application is expecting.  Think of the example where a bank website
wants you to scan the front and back of your check.  It would expect to get two
images, and wouldn't know what to do with more.  So this hint to the UI would
indicate to the user that they were "all done" after 2 images.

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

[asargent_no_longer_on_chrome, 2014/10/23 22:15:57]

I wonder if it would be better to cache the image data in the browser process
(either in memory or on disk in a temporary file) and just return object urls
instead here. That way we don't have to serialize such big strings over IPC.
Also, there are limitations to how big of a dataUrl chrome will be willing to
handle (sounds like it might be 2MB from this bug:
https://code.google.com/p/chromium/issues/detail?id=44820). 

The trick then becomes how to manage the lifetime of those URLs - the browser
process will want to garbage collect at some point. We do something like this in
the pageCapture API:
https://developer.chrome.com/extensions/pageCapture

The code to implement that lives in: chrome/browser/extensions/api/page_capture/


BTW, if you want to just move forward with this as-is for proof-of-concept or
whatever, and change the API to blob urls later on in follow-up CL's, that would
be fine. 

[Paul Stewart, 2014/10/23 23:06:58]

I'd prefer to move forward as-is.  This does work for the current application
and
the API is extensible to use something else if needs be.

+
+    // The MIME type of |dataUrls|.
+    DOMString mimeType;
+  };
+
+  // Callback from the <code>scan</code> method; on success (result == true)

[asargent_no_longer_on_chrome, 2014/10/23 22:15:57]

nit: looks like you removed |result| in favor of just using
chrome.runtime.lastError, so this comment referencing |result| should be updated

[Paul Stewart, 2014/10/23 23:06:58]

Done.

+  // the results from the scan is returned in |results|.
+  callback ScanCallback = void (ScanResults results);
+
+  interface Functions {
+    // Performs a document scan.  On success, the PNG data will be
+    // sent to the callback.
+    // |options| : <code>Options</code> object containing scan parameters.
+    // |callback| : Called with the result and data from the scan.
+    static void scan(ScanOptions options, ScanCallback callback);
+  };
+};