// 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.

// The <code>chrome.printerProvider</code> API exposes events used by print
// manager to query printers controlled by extensions, to query their
// capabilities and to submit print jobs to these printers.
namespace printerProvider {
  // Error codes returned in response to $(ref:onPrintRequested) event.
  enum PrintError {
    // Operation completed successfully.
    OK,

    // General failure.
    FAILED,

    // Print ticket is invalid. For example, ticket is inconsistent with
    // capabilities or extension is not able to handle all settings from the
    // ticket.
    INVALID_TICKET,

    // Document is invalid. For example, data may be corrupted or the format is
    // incompatible with the extension.
    INVALID_DATA
  };

  // Printer description for $(ref:onGetPrintersRequested) event.
  dictionary PrinterInfo {
    // Unique printer ID.
    DOMString id;

    // Printer's human readable name.
    DOMString name;

    // Printer's human readable description.
    DOMString? description;
  };

  // Printing request parameters. Passed to $(ref:onPrintRequested) event.
  dictionary PrintJob {
    // ID of the printer which should handle the job.
    DOMString printerId;

    // The print job title.
    DOMString title;

    // Print ticket in
    // <a href="https://developers.google.com/cloud-print/docs/cdd#cjt">
    // CJT format</a>.
    object ticket;

    // The document content type. Supported formats are
    // <code>"application/pdf"</code> and <code>"image/pwg-raster"</code>.
    DOMString contentType;

    // Blob containing the document data to print. Format must match
    // |contentType|.
    [instanceOf=Blob] object document;
  };

  callback PrintersCallback = void(PrinterInfo[] printerInfo);

  callback PrinterInfoCallback = void(optional PrinterInfo printerInfo);

  // |capabilities|: Device capabilities in
  // <a href="https://developers.google.com/cloud-print/docs/cdd#cdd">CDD
  // format</a>.
  callback CapabilitiesCallback = void(object capabilities);

  callback PrintCallback = void(PrintError result);

  interface Events {
    // Event fired when print manager requests printers provided by extensions.
    // |resultCallback|: Callback to return printer list. Every listener must
    // call callback exactly once.
    static void onGetPrintersRequested(PrintersCallback resultCallback);

    // Event fired when print manager requests information about a USB device
    // that may be a printer.
    // <p><em>Note:</em> An application should not rely on this event being
    // fired more than once per device. If a connected device is supported it
    // should be returned in the $(ref:onGetPrintersRequested) event.</p>
    // |device|: The USB device.
    // |resultCallback|: Callback to return printer info. The receiving listener
    // must call callback exactly once. If the parameter to this callback is
    // undefined that indicates that the application has determined that the
    // device is not supported.
    static void onGetUsbPrinterInfoRequested(
        usb.Device device,
        PrinterInfoCallback resultCallback);

    // Event fired when print manager requests printer capabilities.
    // |printerId|: Unique ID of the printer whose capabilities are requested.
    // |resultCallback|: Callback to return device capabilities in
    // <a href="https://developers.google.com/cloud-print/docs/cdd#cdd">CDD
    // format</a>.
    // The receiving listener must call callback exectly once.
    static void onGetCapabilityRequested(DOMString printerId,
                                         CapabilitiesCallback resultCallback);

    // Event fired when print manager requests printing.
    // |printJob|: The printing request parameters.
    // |resultCallback|: Callback that should be called when the printing
    // request is completed.
    static void onPrintRequested(PrintJob printJob,
                                 PrintCallback resultCallback);
  };
};