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

module blink.mojom;

import "third_party/blink/public/mojom/blob/blob.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";

enum WebPrintingMultipleDocumentHandling {
  kSeparateDocumentsCollatedCopies,
  kSeparateDocumentsUncollatedCopies
};

enum WebPrintingSides {
  kOneSided,
  kTwoSidedLongEdge,
  kTwoSidedShortEdge
};

enum WebPrintQuality {
  kDraft,
  kNormal,
  kHigh
};

enum WebPrintColorMode {
  kColor,
  kMonochrome
};

enum WebPrintingOrientationRequested {
  kPortrait,
  kLandscape,
};

// Corresponds to the printer-state IPP field.
// Reports the current state of the printer.
enum WebPrinterState {
  kIdle,
  kProcessing,
  kStopped,
};

// Corresponds to the printer-state-reason IPP field.
// Reports the reasons related to the current state of the printer.
enum WebPrinterStateReason {
  // All values for this enum listed below are IPP constants from RFC8011:
  // https://www.rfc-editor.org/rfc/rfc8011.html#section-5.4.12
  kNone,
  kOther,
  kConnectingToDevice,
  kCoverOpen,
  kDeveloperEmpty,
  kDeveloperLow,
  kDoorOpen,
  kFuserOverTemp,
  kFuserUnderTemp,
  kInputTrayMissing,
  kInterlockOpen,
  kInterpreterResourceUnavailable,
  kMarkerSupplyEmpty,
  kMarkerSupplyLow,
  kMarkerWasteAlmostFull,
  kMarkerWasteFull,
  kMediaEmpty,
  kMediaJam,
  kMediaLow,
  kMediaNeeded,
  kMovingToPaused,
  kOpcLifeOver,
  kOpcNearEol,
  kOutputAreaAlmostFull,
  kOutputAreaFull,
  kOutputTrayMissing,
  kPaused,
  kShutdown,
  kSpoolAreaFull,
  kStoppedPartly,
  kStopping,
  kTimedOut,
  kTonerEmpty,
  kTonerLow,

  // Non-standard CUPS extensions.
  // See https://github.com/apple/cups/blob/master/backend/ipp.c for details.
  kCupsPkiExpired,
};

// Basic description of a single printer.
struct WebPrinterInfo {
  string printer_name;
  // Opaque representation of the printer id.
  // Unique per printer even if the name is not.
  string printer_id;
  pending_remote<WebPrinter> printer_remote;
};

struct WebPrintingRange {
  uint32 from;
  uint32 to;
};

union WebPrintingMediaSizeDimension {
  WebPrintingRange range;
  uint32 value;
};

// Each media size dimension can be either a fixed value or a range.
// Examples from the IPP spec:
//
// /* ISO A4 transparency only from manual feed */
// media-size={
//  x-dimension=21000
//  y-dimension=29700
// }
//
// /* Custom sizes from 3x5 to 8.5x14 inches */
// media-size={
//  x-dimension=7620-21590
//  y-dimension=12700-35560
// }
//
// Dimensions are specified in PWG units (hundredths of millimeters).
struct WebPrintingMediaSize {
  WebPrintingMediaSizeDimension x_dimension;
  WebPrintingMediaSizeDimension y_dimension;
};

// Represents the media-col entry of printer attributes. See §6.3.1 in
// https://ftp.pwg.org/pub/pwg/candidates/cs-ippjobext21-20230210-5100.7.pdf
struct WebPrintingMediaCollection {
  WebPrintingMediaSize media_size;
  string media_size_name;
};

// Detailed description of a single printer.
// Attribute names & values are largely modelled according to the
// `Printer Description` collection of IANA Internet Printing Protocol
// registrations, which can be found at:
// https://www.iana.org/assignments/ipp-registrations/ipp-registrations.xhtml
struct WebPrinterAttributes {
  uint32 copies_default;
  WebPrintingRange copies_supported;

  WebPrintingMediaCollection media_col_default;
  array<WebPrintingMediaCollection> media_col_database;

  // Represents the media-source entry of printer attributes. See §6.3.1.17 in
  // https://ftp.pwg.org/pub/pwg/candidates/cs-ippjobext21-20230210-5100.7.pdf
  string? media_source_default;
  array<string> media_source_supported;

  WebPrintingMultipleDocumentHandling multiple_document_handling_default;
  array<WebPrintingMultipleDocumentHandling> multiple_document_handling_supported;

  WebPrintingOrientationRequested orientation_requested_default;
  array<WebPrintingOrientationRequested> orientation_requested_supported;

  gfx.mojom.Size printer_resolution_default;
  array<gfx.mojom.Size> printer_resolution_supported;

  WebPrintColorMode print_color_mode_default;
  array<WebPrintColorMode> print_color_mode_supported;

  WebPrintQuality? print_quality_default;
  array<WebPrintQuality> print_quality_supported;

  WebPrinterState printer_state;
  string printer_state_message;
  array<WebPrinterStateReason> printer_state_reasons;

  WebPrintingSides? sides_default;
  array<WebPrintingSides> sides_supported;

  // Opaque representation of the printer id.
  // Unique per printer even if the name is not.
  string printer_id;
};

// Represents the requested media-col entry for a print job. Note that this
// struct slightly differs from WebPrintingMediaCollection and thus is defined
// separately:
//   * `media_size` dimensions are defined as values instead of ranges;
//   * `media_size_name` is omitted (callers are supposed to pass `media_size`).
struct WebPrintingMediaCollectionRequested {
  gfx.mojom.Size media_size;
};

// Detailed description of a single printer.
// Attribute names & values are largely modelled according to the
// `Job Template` collection of IANA Internet Printing Protocol
// registrations, which can be found at:
// https://www.iana.org/assignments/ipp-registrations/ipp-registrations.xhtml
struct WebPrintJobTemplateAttributes {
  string job_name;

  uint32 copies;
  WebPrintingMediaCollectionRequested? media_col;

  // Represents the media-source entry of printer attributes. See §6.3.1.17 in
  // https://ftp.pwg.org/pub/pwg/candidates/cs-ippjobext21-20230210-5100.7.pdf
  string? media_source;

  WebPrintingMultipleDocumentHandling? multiple_document_handling;
  WebPrintingOrientationRequested? orientation_requested;
  gfx.mojom.Size? printer_resolution;
  WebPrintColorMode? print_color_mode;
  WebPrintQuality? print_quality;
  WebPrintingSides? sides;
};

enum WebPrintJobState {
  kPending,
  kProcessing,
  kCompleted,
  kCanceled,
  kAborted,
};

struct WebPrintJobUpdate {
  WebPrintJobState state;
  uint32 pages_printed = 0;
};

// Informs the renderer of changes to a particular print job.
interface WebPrintJobStateObserver {
  // Dispatches an update notification.
  OnWebPrintJobUpdate(WebPrintJobUpdate update);
};

// Allows the renderer to control a particular job.
interface WebPrintJobController {
  // Requests the browser to cancel the job.
  Cancel();
};

struct WebPrintJobInfo {
  string job_name;
  uint32 job_pages;
  pending_receiver<WebPrintJobStateObserver> observer;
  pending_remote<WebPrintJobController> controller;
};

enum GetPrintersError {
  kUserPermissionDenied,
};

enum WebPrinterFetchError {
  kPrinterUnreachable,
  kUserPermissionDenied,
};

enum WebPrintError {
  kPrinterUnreachable,
  kDocumentMalformed,
  kPrintJobTemplateAttributesMismatch,
  kUserPermissionDenied,
};

// Interface for interactions with a particular printer from the render process.
// The implementation is responsible for checking access permissions.
interface WebPrinter {
  // Fetches full attributes of this printer.
  FetchAttributes() => result<WebPrinterAttributes, WebPrinterFetchError>;

  // Sends a print job to a printer.
  Print(pending_remote<blink.mojom.Blob> document,
        WebPrintJobTemplateAttributes attributes) => result<WebPrintJobInfo, WebPrintError>;
};

// Interface for accessing printers from the render process.
// The implementation is responsible for checking access permissions.
interface WebPrintingService {
  // Returns a list of local printers for this device.
  GetPrinters() => result<array<WebPrinterInfo>, GetPrintersError>;
};