chromeos/components/print_management/mojom/printing_manager.mojom

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

module chromeos.printing.printing_manager.mojom;

import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";
import "url/mojom/url.mojom";

// Enumeration of print job status.
enum PrintJobCompletionStatus {
  kFailed,
  kCanceled,
  kPrinted
};

// Enumeration of all the possible printer error codes. The order of these enums
// must match that of chrome/browser/chromeos/printing/printer_error_codes.h
enum PrinterErrorCode {
  kNoError,
  kPaperJam,
  kOutOfPaper,
  kOutOfInk,
  kDoorOpen,
  kPrinterUnreachable,
  kTrayMissing,
  kOutputFull,
  kStopped,
  kFilterFailed,
  kUnknownError,
  kClientUnauthorized,
  kExpiredCertificate,
};

// Contains information about a completed print job. Completed print jobs are
// stored to the local database. Information of this struct includes the
// completion status and error code associated with the print job. This struct
// is null for active print jobs, i.e. jobs that are currently being printed and
// are not stored in the local database.
struct CompletedPrintJobInfo {
  // Corresponds to the status of the print job after it has completed.
  PrintJobCompletionStatus completion_status;
};

// Enumeration of ongoing print job status.
enum ActivePrintJobState {
  // Print job is currently being printed.
  kStarted,

  // The print job's document is considered finished to the printer.
  // This includes successful, failed, and cancelled print jobs.
  kDocumentDone,
};

// Contains all relevant information in regards to an active print job i.e. one
// that is current being printed.
struct ActivePrintJobInfo {
  // Number of current printed pages.
  uint32 printed_pages;

  // Current state of the print job.
  ActivePrintJobState active_state;
};

// Contains all the information in regards to a print job. Information is
// provided by the printer. Printer details, i.e. name and uri, can be edited
// via print settings.
struct PrintJobInfo {
  // Unique identifier for a particular print job.
  string id;

  // Title of the print job. Usually the name of the printed file.
  mojo_base.mojom.String16 title;

  // Time of when the print job was requested.
  mojo_base.mojom.Time creation_time;

  // Number of pages requested to print.
  uint32 number_of_pages;

  // Printer GUID.
  string printer_id;

  // The printer destination the print job was sent to.
  mojo_base.mojom.String16 printer_name;

  // The URI of the printer the print job was requested to.
  url.mojom.Url printer_uri;

  // Corresponds to the error code reported by the printer.
  PrinterErrorCode printer_error_code;

  // Information of a completed print job. Null struct if the print job is
  // currently being printed.
  CompletedPrintJobInfo? completed_info;

  // Contains information relevant to an active print job. Null struct if
  // the print job is from the local database.
  ActivePrintJobInfo? active_print_job_info;
};

// Observer interface that sends remote updates to the print management app UI
// receiver.
interface PrintJobsObserver {
  // Notifies that the local print job database has been cleared.
  OnAllPrintJobsDeleted();

  // Notifies that an ongoing print job has been updated.
  OnPrintJobUpdate(PrintJobInfo print_job);
};

// Provides APIs to retrieve print metadata information. This API is exposed
// only to the Print Management App (chrome://print-management). Interfaces are
// implemented by a browser service. Interacts with PrintHistory API to retrieve
// print job metadatas.
interface PrintingMetadataProvider {
  // Takes in a remote so that the implementer binds it and send notifications
  // to the receiver in the print management app. This is to set up automatic
  // updates from the browser process to the renderer process.
  // (print management app UI). This is guaranteed to not send remote updates
  // to disconnected receivers.
  ObservePrintJobs(pending_remote<PrintJobsObserver> observer) => ();

  // Returns an array of PrintJobInfo. This is the main function to retrieve
  // the print history of a device.
  GetPrintJobs() => (array<PrintJobInfo> print_jobs);

  // Deletes all print jobs tracked on this device. Returns true if deleting all
  // print jobs was successful. Returns false if there was an error with
  // retrieving the print jobs to delete in this device.
  DeleteAllPrintJobs() => (bool success);

  // Cancels an ongoing print job keyed by PrintJobInfo.id.
  // This is a best effort attempt as there is no guarantee that we can cancel
  // a print job. Returns true if cancelling the print job was attempted.
  // Returns false if cancelling the print job was not attempted.
  CancelPrintJob(string id) => (bool attempted_cancel);

  // Returns true if the user is allowed to delete their own print job history
  // (default value is true for non-managed users).
  GetDeletePrintJobHistoryAllowedByPolicy() => (bool is_allowed_by_policy);

  // Returns the database expiration period of the print job metadata in days.
  GetPrintJobHistoryExpirationPeriod() => (
      int16 expiration_period_in_days,
      bool is_from_policy);
};