// Copyright 2019 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.printing</code> API to send print jobs to printers
// installed on Chromebook.
[platforms=("chromeos"),
implemented_in="chrome/browser/extensions/api/printing/printing_api.h"]
namespace printing {
  dictionary SubmitJobRequest {
    // The print job to be submitted.
    // Supported content types are "application/pdf" and "image/png". The
    // <a href="https://developers.google.com/cloud-print/docs/cdd#cjt">Cloud Job Ticket</a>
    // shouldn't include <code>FitToPageTicketItem</code>,
    // <code>PageRangeTicketItem</code> and <code>ReverseOrderTicketItem</code>
    // fields since they are irrelevant for native printing.
    // <code>VendorTicketItem</code> is optional. All other fields must be
    // present.
    printerProvider.PrintJob job;

    // Used internally to store the blob uuid after parameter customization and
    // shouldn't be populated by the extension.
    [nodoc] DOMString? documentBlobUuid;
  };

  // The status of $(ref:submitJob) request.
  enum SubmitJobStatus {
    // Sent print job request is accepted.
    OK,

    // Sent print job request is rejected by the user.
    USER_REJECTED
  };

  // Response for $(ref:submitJob) request.
  dictionary SubmitJobResponse {
    // The status of the request.
    SubmitJobStatus status;

    // The id of created print job. This is a unique identifier among all print
    // jobs on the device. If status is not OK, jobId will be null.
    DOMString? jobId;
  };

  // The source of the printer.
  enum PrinterSource {
    // Printer was added by user.
    USER,

    // Printer was added via policy.
    POLICY
  };

  // Description of the printer.
  dictionary Printer {
    // The printer's identifier; guaranteed to be unique among printers on the
    // device.
    DOMString id;

    // The name of the printer.
    DOMString name;

    // The human-readable description of the printer.
    DOMString description;

    // The printer URI. This can be used by extensions to choose the printer for
    // the user.
    DOMString uri;

    // The source of the printer (user or policy configured).
    PrinterSource source;

    // The flag which shows whether the printer fits
    // <a href="https://chromium.org/administrators/policy-list-3#DefaultPrinterSelection">
    // DefaultPrinterSelection</a> rules.
    // Note that several printers could be flagged.
    boolean isDefault;

    // The value showing how recent the printer was used for printing from
    // Chrome. The lower the value is the more recent the printer was used. The
    // minimum value is 0. Missing value indicates that the printer wasn't used
    // recently. This value is guaranteed to be unique amongst printers.
    long? recentlyUsedRank;
  };

  // The status of the printer.
  enum PrinterStatus {
    // The door of the printer is open. Printer still accepts print jobs.
    DOOR_OPEN,

    // The tray of the printer is missing. Printer still accepts print jobs.
    TRAY_MISSING,

    // The printer is out of ink. Printer still accepts print jobs.
    OUT_OF_INK,

    // The printer is out of paper. Printer still accepts print jobs.
    OUT_OF_PAPER,

    // The output area of the printer (e.g. tray) is full. Printer still accepts
    // print jobs.
    OUTPUT_FULL,

    // The printer has a paper jam. Printer still accepts print jobs.
    PAPER_JAM,

    // Some generic issue. Printer still accepts print jobs.
    GENERIC_ISSUE,

    // The printer is stopped and doesn't print but still accepts print jobs.
    STOPPED,

    // The printer is unreachable and doesn't accept print jobs.
    UNREACHABLE,

    // The SSL certificate is expired. Printer accepts jobs but they fail.
    EXPIRED_CERTIFICATE,

    // The printer is available.
    AVAILABLE
  };

  // Response for $(ref:getPrinterInfo) request.
  dictionary GetPrinterInfoResponse {
    // Printer capabilities in
    // <a href="https://developers.google.com/cloud-print/docs/cdd#cdd">
    // CDD format</a>.
    // The property may be missing.
    object? capabilities;

    // The status of the printer.
    PrinterStatus status;
  };

  // Status of the print job.
  enum JobStatus {
    // Print job is received on Chrome side but was not processed yet.
    PENDING,

    // Print job is sent for printing.
    IN_PROGRESS,

    // Print job was interrupted due to some error.
    FAILED,

    // Print job was canceled by the user or via API.
    CANCELED,

    // Print job was printed without any errors.
    PRINTED
  };

  callback SubmitJobCallback = void(SubmitJobResponse response);
  callback CancelJobCallback = void();
  callback GetPrintersCallback = void(Printer[] printers);
  callback GetPrinterInfoCallback = void(GetPrinterInfoResponse response);
  callback getJobStatusCallback = void(JobStatus status);

  interface Functions {
    // Submits the job for printing. If the extension is not listed in
    // the <a href="https://chromeenterprise.google/policies/#PrintingAPIExtensionsAllowlist">
    // <code>PrintingAPIExtensionsAllowlist</code></a> policy,
    // the user is prompted to accept the print job.<br/>
    // Before Chrome 120, this function did not return a promise.
    static void submitJob(
        SubmitJobRequest request,
        SubmitJobCallback callback);

    // Cancels previously submitted job.
    // |jobId|: The id of the print job to cancel. This should be the same id
    // received in a $(ref:SubmitJobResponse).
    static void cancelJob(
        DOMString jobId,
        CancelJobCallback callback);

    // Returns the list of available printers on the device. This includes
    // manually added, enterprise and discovered printers.
    static void getPrinters(GetPrintersCallback callback);

    // Returns the status and capabilities of the printer in
    // <a href="https://developers.google.com/cloud-print/docs/cdd#cdd">
    // CDD format</a>.
    // This call will fail with a runtime error if no printers with given id are
    // installed.
    static void getPrinterInfo(
        DOMString printerId,
        GetPrinterInfoCallback callback);

    // Returns the status of the print job. This call will fail with a runtime
    // error if the print job with the given `jobId` doesn't exist.
    // `jobId`: The id of the print job to return the status of. This should be
    // the same id received in a $(ref:SubmitJobResponse).
    static void getJobStatus(
        DOMString jobId,
        getJobStatusCallback callback);
  };

  interface Properties {
    // The maximum number of times that $(ref:submitJob) can be called per
    // minute.
    [value=40] static long MAX_SUBMIT_JOB_CALLS_PER_MINUTE();

    // The maximum number of times that $(ref:getPrinterInfo) can be called per
    // minute.
    [value=20] static long MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE();
  };

  interface Events {
    // Event fired when the status of the job is changed.
    // This is only fired for the jobs created by this extension.
    static void onJobStatusChanged(DOMString jobId, JobStatus status);
  };
};