Added chrome.printerProvider API definitions.

chrome/common/extensions/api/printer_provider.idl

+// 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.
+
+// API provides set of events that should be handled by extension to discover
+// printers, get printer capabilities and to submit print jobs.

[not at google - send to devlin, 2014/10/30 14:51:28]

Yes, thanks, this is a much better description (I didn't actually look at your
API proposal description - but since I understood it, but not this comment, I
figured there was something better in there somewhere).

Grammar nits:
- "This API exposes" or just "Exposes". Either one, but not "API provides".
- "Extensions" not "extension".

And ideally you'd imply more strongly that it's not the *Extension* that is
discovering printers (and so forth), but the *print manager* queries this API to
discover printers (and so forth).

All concisely :) note that this description is what appears in the table at the
top of the API reference pages. E.g. see
https://developer.chrome.com/extensions/storage - which I think is too brief an
explanation - but something too long would look odd as well. 

Also note that paragraph breaks in this comment will be respected in that
description.

[Vitaly Buka (NO REVIEWS), 2014/10/30 17:57:53]

Done. 

On 2014/10/30 14:51:28, kalman wrote:

+namespace printerProvider {
+  // Error codes used by providing extensions in response to requests.
+  enum PrintError {
+    // Operation completed successfully.
+    OK,
+
+    // General failure.
+    FAILED,
+
+    // Print ticket is invalid. Extensions may not be able to handle all
+    // settings from print ticket. It's recomeneded to ignore them and don't

[not at google - send to devlin, 2014/10/30 14:51:28]

recommended

and perhaps "ignore this failure and gracefully fail" rather than "ignore them
and don't fail if possible"?

[Vitaly Buka (NO REVIEWS), 2014/10/30 17:57:53]

Done.

+    // fail if possible.
+    INVALID_TICKET,
+
+    // Document is invalid. If data is corrupted or format is incompartible with

[not at google - send to devlin, 2014/10/30 14:51:28]

"If data is corrupted..." -> "For example, data may be corrupted or the format
incompatible with the Extension".

[Vitaly Buka (NO REVIEWS), 2014/10/30 17:57:53]

Done.

+    // extension.
+    INVALID_DATA
+  };
+
+  // Printer description for <code>onGetPrintersRequested()</code> event.

[not at google - send to devlin, 2014/10/30 14:51:28]

Rather than <code>onGetPrintersRequested</code> use
$(ref:onGetPrintersRequested).

[Vitaly Buka (NO REVIEWS), 2014/10/30 17:57:53]

Done.

+  dictionary PrinterInfo {
+    // Unique id of printer.

[not at google - send to devlin, 2014/10/30 14:51:28]

"ID" everywhere, not "id".

[Vitaly Buka (NO REVIEWS), 2014/10/30 17:57:53]

Done.

+    DOMString id;
+
+    // Human readable display name of printer.
+    DOMString name;
+
+    // Human readable description of printer.
+    DOMString? description;
+  };
+
+  // Parameters of |onPrintRequested|.

[not at google - send to devlin, 2014/10/30 14:51:28]

Likewise.

[Vitaly Buka (NO REVIEWS), 2014/10/30 17:57:53]

Done.

+  dictionary PrintJob {
+    // Id of the printer to submit the job.
+    DOMString printerId;
+
+    // print ticket in CJT format described at
+    // https://developers.google.com/cloud-print/docs/cdd#cjt
+    object ticket;
+
+    // Content type of the document. Supported formats are "application/pdf" and
+    // "image/pwg-raster".
+    DOMString contentType;
+
+    // Buffer with document to printer. Format must match |contentType|.
+    ArrayBuffer document;
+  };
+
+  callback PrintersCallback = void(PrinterInfo[] printerInfo);
+  callback CapabilitiesCallback = void(object capabilities);
+  callback PrintCallback = void(PrintError result);
+
+  interface Events {
+    // Event fired when print preview requests printers provided by extension.

[not at google - send to devlin, 2014/10/30 14:51:28]

You mention "preview" in each of these event descriptions, but I thought it was
actually just general printing, not limited to print preview? Could you phrase
each of these like "Event fired when the print manager requests the printers
provided by the Extension", and so on?

[Vitaly Buka (NO REVIEWS), 2014/10/30 17:57:53]

On Chrome OS print preview is going to be the only entry point for printing.
Still I am OK with abstract "print manager".

On 2014/10/30 14:51:28, kalman wrote:

+    // |resultCallback| : callback to return printer list. Every listener must
+    // call callback exactly once.
+    static void onGetPrintersRequested(PrintersCallback resultCallback);
+
+    // Event fired when print preview requests printer capabilities.
+    // |printerId| : unique id of the printer.
+    // |resultCallback| : callback to return device capabilities in CDD format
+    // as described at https://developers.google.com/cloud-print/docs/cdd#cdd.
+    // The receiving listener must call callback exectly once.
+    static void onGetCapabilityRequested(DOMString printerId,
+                                         CapabilitiesCallback resultCallback);
+
+    // Event fired when print preview requests printing.
+    // |printJob| : parameters of printing request.
+    static void onPrintRequested(PrintJob printJob,
+                                 PrintCallback resultCallback);
+  };
+};
+