desk.mojom | Explore in Territory

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

module crosapi.mojom;

import "mojo/public/mojom/base/values.mojom";

// Represents error code from ash desk feature implementation.
[Stable, Extensible]
enum DeskCrosApiError {
  // Deprecated. No do use for actual error since it's mapped to default
  // value-0 by mistake. Treat it as unknown error. For storage error use
  // kStorageError.
  kDeprecatedStorageError = 0,
  // Therer is no active profile.
  kNoCurrentUserError,
  // Either the profile is not valid or there is not an active proflile.
  kBadProfileError,
  // The resource cannot be found.
  kResourceNotFoundError,
  // The identifier is not valid.
  kInvalidIdError,
  // The desks are currently being modified.
  kDesksBeingModifiedError,
  // The desk count requirement not met.
  kDesksCountCheckFailedError,
  // Unknown error.
  [Default]kUnknownError,
  // Storage error.
  [MinVersion=3]kStorageError,
};

[Stable, Extensible]
enum SavedDeskType {
  // Unknown desk type.
  [Default] kUnknown,
  // Desk saved for regular desk template.
  kTemplate,
  // Desk saved for Save & Recall.
  kSaveAndRecall,
};

// A Struct represents an ash desk.
[Stable]
struct DeskModel {
  // Unique identifier of a desk.
  string desk_uuid@0;
  // Human readable name of a desk.
  string desk_name@1;
};

// A Struct represents an saved desk.
[Stable]
struct SavedDeskModel {
  // Unique identifier of a saved desk.
  string saved_desk_uuid@0;
  // Human readable name of a saved desk.
  string saved_desk_name@1;
  // Saved desk type
  SavedDeskType saved_desk_type@2;
};

// A Struct represents GUID.
[Stable]
struct GUID {
  // Lowercase string representation of GUID.
  string lowercase@0;
};

// The response from LaunchEmptyDesk API.
[Stable]
union LaunchEmptyDeskResult{
  DeskCrosApiError error;
  GUID desk_id;
};

// The response from RemoveDesk API.
[Stable]
union RemoveDeskResult {
  DeskCrosApiError error;
  bool succeeded;
};

// The response from RemoveDesk API.
[Stable]
union GetTemplateJsonResult{
  DeskCrosApiError error;
  mojo_base.mojom.Value template_json;
};

// The response from GetAllDesks API.
[Stable]
union GetAllDesksResult{
  DeskCrosApiError error;
  array<DeskModel> desks;
};

// The response from SaveActiveDesk API.
[Stable]
union SaveActiveDeskResult{
  DeskCrosApiError error;
  DeskModel saved_desk;
};

// The response from RecallSavedDesk API.
[Stable]
union RecallSavedDeskResult{
  DeskCrosApiError error;
  GUID desk_id;
};

// The response from DeleteSavedDesk API.
[Stable]
union DeleteSavedDeskResult {
  DeskCrosApiError error;
  bool succeeded;
};

// The response from SetAllDesksProperty API.
[Stable]
union SetAllDesksPropertyResult {
  DeskCrosApiError error;
  bool succeeded;
};

// The response from GetSavedDesks API.
[Stable]
union GetSavedDesksResult {
  DeskCrosApiError error;
  array<SavedDeskModel> saved_desks;
};

// The response from GetActiveDesk API.
[Stable]
union GetActiveDeskResult {
  DeskCrosApiError error;
  GUID desk_id;
};

// The response from SwitchDesk API.
[Stable]
union SwitchDeskResult {
  DeskCrosApiError error;
  bool succeeded;
};

// The response from GetDeskByID API.
[Stable]
union GetDeskByIDResult {
  DeskCrosApiError error;
  DeskModel desk;
};

// Implemented by lacros-chrome for consuming events.

// next version: 2
// next method id: 3
[Stable]
interface DeskEventObserver {
  // Fired when desk switch event dispatched.
  OnDeskSwitched@0(GUID new_desk_id, GUID previous_desk_id);
  // Fired when desk add event dispatched. If from_undo is true, sends event
  // stating that desk is from removal retrieval. If false, sends event that
  // desk is very newly being launched.
  OnDeskAdded@1(GUID new_desk_id, [MinVersion=1] bool from_undo);
  // Fired when desk removal event dispatched.
  OnDeskRemoved@2(GUID removed_desk_id);
};

// Interface for desk operations. Implemented by ash-chrome. Used by
// lacros-chrome to forward the desk operation to support wmDesksPrivate private
// API.
//
// next version: 6
// next method id: 13
[Stable, Uuid="5fbc1ef6-3fb5-4553-a161-9f113370daf7"]
interface Desk {
  // Launch an empty desk from ash. Returns the `desk_id` if the operation
  //succeeded. Returns `error` if the operation failed.
  LaunchEmptyDesk@0(string desk_name)
      => (LaunchEmptyDeskResult result);

  // Remove a desk from ash, close all windows if `combine_desk` set to false,
  // otherwise combine the windows to the active desk to the left. Prompt
  // user with notification to undo removal if `allow_undo` is set to true.
  // Returns `error` if the operation failed.
  RemoveDesk@1(GUID desk_uuid, bool combine_desk,
      [MinVersion=5] bool? allow_undo) => (RemoveDeskResult result);

  // Gets the template associated with the templateUuid and returns its JSON
  // representation. Returns an error if either the template could not be
  // found or the user profile is not valid.
  GetTemplateJson@2(GUID desk_template_uuid)
      => (GetTemplateJsonResult result);

  // Returns all desks from ash.
  GetAllDesks@3() => (GetAllDesksResult result);

  // Saves the current active desk to the library and remove it from the desk
  // bar.
  SaveActiveDesk@4() => (SaveActiveDeskResult result);

  // Deletes the saved desk from the library.
  DeleteSavedDesk@5(GUID saved_desk_uuid) => (DeleteSavedDeskResult result);

  // Launches a saved desk from the library back to active desk.
  RecallSavedDesk@6(GUID saved_desk_uuid) => (RecallSavedDeskResult result);

  // Sets all-desk window property by the window app_restore_window_id.
  SetAllDesksProperty@7(int32 app_restore_window_id, bool all_desk)
      => (SetAllDesksPropertyResult result);

  // Returns all available previously-saved desks.
  [MinVersion=2]GetSavedDesks@8() => (GetSavedDesksResult result);

  // Retrieves the UUID of the current active desk.
  [MinVersion=2]GetActiveDesk@9() => (GetActiveDeskResult result);

  // Switches to the target desk.
  [MinVersion=2]SwitchDesk@10(GUID desk_uuid) => (SwitchDeskResult result);

  // Retrieves desk by its desk ID.
  [MinVersion=3]GetDeskByID@11(GUID desk_uuid) => (GetDeskByIDResult result);

  // Adds an observer to desk events. Observers will be removed once the pipe
  // closed between ash and lacros.
  [MinVersion=4]AddDeskEventObserver@12(
      pending_remote<DeskEventObserver> observer);
};
chromium/chromeos/crosapi/mojom/desk.mojom
