// 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.remote_apps.mojom;

import "url/mojom/url.mojom";

[Stable]
union AddFolderResult {
  // The ID of the added folder. Implies success.
  string folder_id;

  // Implies failure.
  string error;
};

[Stable]
union AddAppResult {
  // The ID of the added app. Implies success.
  string app_id;

  // Implies failure.
  string error;
};

// Interface for communication between an extension and the Remote Apps
// Manager.
//
// Next MinVersion: 3
// Next Method ID: 5
[Stable]
interface RemoteApps {
  // Adds a Remote Apps folder to the launcher. Empty folders are not shown in
  // the launcher.
  //
  // Input parameters:
  // - |name|: the name of the folder.
  // - |add_to_front|: true if the folder should be added to the front of the
  //                   app list.
  //
  // Output parameters:
  // - |result|: A union with |folder_id| representing the ID of the added
  //             folder on success, and |error| representing the error message
  //             on failure.
  AddFolder@0(string name,
            bool add_to_front) => (AddFolderResult result);

  // Adds a Remote Apps app to the launcher.
  //
  // Input parameters:
  // - |source_id|: An ID used to identify the source of the caller. The JS
  //                bindings manages this and passes the extension ID.
  // - |name|: the name of the app.
  // - |folder_id|: the ID of the parent folder. An empty string indicates the
  //                app has no parent folder.
  // - |icon_url|: a URL pointing to an image which represents the app's icon.
  // - |add_to_front|: true if the app should be added to the front of the app
  //                   list. Has no effect if the app has a parent folder.
  //
  // Output parameters:
  // - |result|: A union with |app_id| representing the ID of the added app on
  //             success, and |error| representing the error message on
  //             failure.
  AddApp@1(string source_id,
         string name,
         string folder_id,
         url.mojom.Url icon_url,
         bool add_to_front) => (AddAppResult result);

  // Deletes a Remote App added by |AddApp()|.
  //
  // Input parameters:
  // - |app_id|: ID of the app.
  //
  // Output parameters:
  // - |error|: A string describing the error if any.
  DeleteApp@2(string app_id) => (string? error);

  // Sorts the Remote apps and folders at the front of the launcher, in
  // alphabetical, case insensitive, order.
  //
  // Output parameters:
  // - |error|: A string describing the error if any.
  [MinVersion=1]
  SortLauncherWithRemoteAppsFirst@3() => (string? error);

  // Set the list of apps to be pinned on the shelf. Can be called with an
  // empty list to unpin all the apps.
  //
  // Output parameters:
  // - |error|: A string describing the error if any.
  [MinVersion=2]
  SetPinnedApps@4(array<string> app_ids) => (string? error);
};

// Factory for creating an instance of |RemoteApps|.
[Stable]
interface RemoteAppsFactory {
  // Binds to the Profile's |RemoteApps| implementation. The
  // |OnRemoteAppLaunched| event is only dispatched to the observer associated
  // with the source which added the app.
  BindRemoteAppsAndAppLaunchObserver@0(string source_id,
         pending_receiver<RemoteApps> remote_apps,
         pending_remote<RemoteAppLaunchObserver> observer);
};

// A RemoteAppLaunchObserver gets notifications when a remote app is launched.
[Stable]
interface RemoteAppLaunchObserver {
  // Invoked when a remote app is launched. |app_id| is the ID of the app which
  // was launched. |source_id| is the same ID passed to the |AddApp()| method.
  OnRemoteAppLaunched@0(string app_id, string source_id);
};