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..20d78f73dfbc5a036a3798868df2f508d0a7960a
--- /dev/null
+++ b/chrome/common/extensions/api/document_scan.idl
@@ -0,0 +1,29 @@
+// 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[]? accepted_mime_types;

[not at google - send to devlin, 2014/10/20 22:36:13]

"accepted" is probably unnecessary in this context.

[Paul Stewart, 2014/10/21 02:42:16]

Done.

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

[not at google - send to devlin, 2014/10/20 22:36:13]

Be consistent with underscores vs camel case. We usually use camel case in
extension APIs.

Also: since this API is to do with scanning, the "scan" is somewhat of a
tautology, perhaps "maxImages"?

[Paul Stewart, 2014/10/21 02:42:16]

Done.

+  };
+
+  // Callback from the <code>scan</code> method; on success (result == true)
+  // images from the scan is returned in the |data_urls| strings which can be
+  // passed as the "src" value to an image tag.  The image data is of the
+  // type |mime_type|.
+  callback ScanCallback = void (DOMString[] data_urls, DOMString mime_type);

[not at google - send to devlin, 2014/10/20 22:36:13]

It's better for backwards compatibility to use a parameters object here, and
just a nicer API IMO. For example, you could have an object ScanResult with
"dataURLs" and "mimeType".

[Paul Stewart, 2014/10/21 02:42:16]

Using "dataUrls" instead of "dataURLs" since the IDL compiler would otherwise
convert to "std::vector<std::string> data_ur_ls"

[not at google - send to devlin, 2014/10/21 17:30:01]

Ah bummer. We should fix the schema compiler (though not urgently) - the code we
generate internally isn't a reason to chose one API or other. I consciously
chose dataURLs because the web uses dataURL, blobURL for its function names.
It's not that big a deal though, really, I don't feel strongly.

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