ash / components / arc / mojom / app.mojom [blame]

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

module arc.mojom;

import "ash/components/arc/mojom/app_permissions.mojom";
import "ash/components/arc/mojom/compatibility_mode.mojom";
import "ash/components/arc/mojom/gfx.mojom";
import "ash/components/arc/mojom/scale_factor.mojom";

// Describes installation result.
struct InstallationResult {
  string package_name;
  bool success;  // true if app was installed successfully.
  [MinVersion=62] bool is_launchable_app; // true if the package installed
                                          // successfully and is launchable.
};

// Describes application storage.
struct AppStorage {
  uint64 app_size_in_bytes;
  uint64 data_size_in_bytes;
};

// Describes ARC app.
// The list of AppInfo sent by AppInstance contains Android apps which can work
// as ChromeOS apps (e.g. can handle CATEGORY_LAUNCHER ACTION_MAIN intents).
// This is different from ArcPackageInfo.
struct AppInfo {
  string name;
  string package_name;
  string activity;
  [MinVersion=2] bool sticky;  // true if the app cannot be uninstalled
  [MinVersion=7] bool notifications_enabled;
  [MinVersion=35] bool suspended;
  [MinVersion=47] ArcResizeLockState resize_lock_state;
  [MinVersion=50] WindowLayout? initial_layout;

  // Version name will likely be in the format `<major>.<minor>.<point>`,
  // however there is no guarantee and it could be any string value,
  // see https://developer.android.com/studio/publish/versioning.
  [MinVersion=51] string? version_name;

  // Size of app and associated data in bytes.
  [MinVersion=52] AppStorage? app_storage;
  // Option, only for ARC upgrade. True if the app is fixing up.
  // During fixup, it cannot be launched.
  [MinVersion=54] bool need_fixup;

  // App category corresponding to the
  // android.content.pm.ApplicationInfo#category field.
  [MinVersion=57] AppCategory app_category;
};

// Describes the data required to install a web app.
struct WebAppInfo {
  string title;

  // The URL which should be opened when the web app starts.
  string start_url;

  // The scope of URLs which are captured by the web app.
  string scope_url;

  // The color used for the title bar of the app. Passed as a 32 bit ARGB value.
  // INT_MAX+1 represents an invalid color.
  int64 theme_color;

  // If the web app is tied to a web-only TWA.
  [MinVersion=44] bool is_web_only_twa;

  // SHA256 fingerprint of the APK the web app belongs to.
  [MinVersion=45] string? certificate_sha256_fingerprint;
};

// ARC app window type.
[Extensible]
enum WindowSizeType {
  [Default] kUnknown = 0, // System default size app.
  kPhoneSize,             // Phone size app.
  kTabletSize,            // Tablet size app.
  kMaximize,              // Maximize app.
};

// ARC app window layout.
struct WindowLayout {
  WindowSizeType type;
  bool resizable;// Resizability may affect launch state.
  Rect? bounds;  // Window bounds value.
};

// ARC package install priority.
[Extensible]
enum InstallPriority {
  [Default] kUndefined = 0,
  kMedium = 1,
  kLow = 2,
};

// ARC package locale-related info.
// NOTE: All locales here are sent as is, and not guaranteed to have correspondent ICU display name
// translation. Displaying this to user will require special handling.
struct PackageLocaleInfo {
  // These are the locales explicitly mentioned by the app to be supported.
  // Should not be empty.
  // Please see comment on `selected_locale` on possible differences between
  // `supported_locales` and `selected_locale`.
  array<string> supported_locales;

  // Empty string denotes no language has been selected and will default to
  // System Language. Due to Android-side implementation, this also doesn't
  // necessarily comply with locales in `supported_locales`.
  // For example, supported_locales = ["en-US", "ja"], selected_locale can be
  // "en-SG" or even "fr".
  string selected_locale;
};

// Describes ARC package.
// The list of ArcPackageInfo sent by AppInstance contains all the installed
// Android packages including ones other than launchable apps (e.g. Google Play
// Services). This is different from AppInfo.
struct ArcPackageInfo {
  string package_name;
  int32 package_version;
  int64 last_backup_android_id;
  int64 last_backup_time;
  bool sync;  // true if package installation should be synced
  // true if package is signed with the system certificate.
  // TODO(b/255671011): This is unused. Remove this.
  [MinVersion=11] bool deprecated_system;
  // true if package registers VPNService intent.
  [MinVersion=25] bool vpn_provider;

  // If non-null, signifies this package represents a web app that should be
  // installed on the browser side.
  [MinVersion=38] WebAppInfo? web_app_info;

  // Deprecated and unused in favour of |permission_states|
  [MinVersion=41] map<AppPermission, bool>? deprecated_permissions;

  [MinVersion=43] map<AppPermission, PermissionState>? permission_states;

  // Version name will likely be in the format `<major>.<minor>.<point>`,
  // however there is no guarantee and it could be any string value,
  // see https://developer.android.com/studio/publish/versioning.
  [MinVersion=51] string? version_name;

  // If the package is pre-installed in the system image. This is true even
  // after the package is updated.
  [MinVersion=55] bool preinstalled;

  [MinVersion=56] InstallPriority priority;

  // If sent from ARC, null denotes that per-app language is not supported.
  [MinVersion=60] PackageLocaleInfo? locale_info;

  // True if the package has the Game Controls Opt Out metadata set to true.
  [MinVersion=61] bool game_controls_opt_out;
};

// Describes ARC app shortcut.
struct ShortcutInfo {
  string name;
  string package_name;
  string icon_resource_id;
  string intent_uri;
};

// Page for ShowPackageInfoOnPage.
[Extensible]
enum ShowPackageInfoPage {
  // The main package info page.
  MAIN = 0,

  // Page for managing links assigned to the app.
  MANAGE_LINKS = 1,

  // Page for managing permissions assigned to the app.
  [MinVersion=59] MANAGE_PERMISSIONS = 2,
};

// Describes the raw icon png data published by an Android application.
struct RawIconPngData {
  // True if the icon is an adaptive icon, or false otherwise.
  bool is_adaptive_icon;
  // The raw icon for the non-adaptive icon, or the generated standard icon done
  // by the ARC side for the adaptive icon.
  array<uint8>? icon_png_data;
  // The foreground image for the adaptive icon.
  array<uint8>? foreground_icon_png_data;
  // The background image for the adaptive icon.
  array<uint8>? background_icon_png_data;
};

// The window information to launch an app.
// This should be kept in sync with WindowInfo in
// components/services/app_service/public/mojom/types.mojom, and
// MakeArcWindowInfo in chrome/browser/apps/app_service/launch_utils.cc
struct WindowInfo {
  int32 window_id = -1;
  int32 state = 0;
  int64 display_id = -1;
  Rect? bounds;
};

// Describes a Play Store app discovery result.
struct AppDiscoveryResult {
  string? launch_intent_uri;
  string? install_intent_uri;
  string? label;
  bool is_instant_app;
  bool is_recent;
  string? publisher_name;
  string? formatted_price;
  float review_score;
  array<uint8> icon_png_data;
  [MinVersion=22] string? package_name;
  [MinVersion=46] RawIconPngData? icon;
};

// Describes the status of an app discovery request, including completed
// states and all possible anomalies.
[Extensible]
enum AppDiscoveryRequestState {
  // Request handled successfully.
  SUCCESS = 0,
  // Request canceled when a newer request is sent.
  CANCELED = 1,
  // Request failed due to any communication error or Play Store internal error.
  ERROR_DEPRECATED = 2,

  // All possible reasons of ending a request:
  //   PlayStoreProxyService is not available.
  PLAY_STORE_PROXY_NOT_AVAILABLE = 3,
  //   It fails to cancel the previous request.
  FAILED_TO_CALL_CANCEL = 4,
  //   It fails to call findApps API.
  FAILED_TO_CALL_FINDAPPS = 5,
  //   It comes with invalid parameters.
  REQUEST_HAS_INVALID_PARAMS = 6,
  //   It times out.
  REQUEST_TIMEOUT = 7,
  //   At least one result returned from Phonesky has an unmatched request code.
  PHONESKY_RESULT_REQUEST_CODE_UNMATCHED = 8,
  //   At least one result returned from Phonesky has an unmatched session id.
  PHONESKY_RESULT_SESSION_ID_UNMATCHED = 9,
  //   Phonesky returns with an unmatched request code.
  PHONESKY_REQUEST_REQUEST_CODE_UNMATCHED = 10,
  //   The app discovery service is not available.
  PHONESKY_APP_DISCOVERY_NOT_AVAILABLE = 11,
  //   The installed Phonesky version doesn't support app discovery.
  PHONESKY_VERSION_NOT_SUPPORTED = 12,
  //   It gets an unexpected exception from Phonesky.
  PHONESKY_UNEXPECTED_EXCEPTION = 13,
  //   The Phonesky app discovery service thinks it's malformed.
  PHONESKY_MALFORMED_QUERY = 14,
  //   An internal error happens in Phonesky while processing the request.
  PHONESKY_INTERNAL_ERROR = 15,
  //   At least one result returned with invalid app data.
  PHONESKY_RESULT_INVALID_DATA = 16,
};

// Describes the category type of app shortcut item.
[Extensible]
enum AppShortcutItemType {
  // Static shortcut, which means it was published from AndroidManifest.xml.
  kStatic = 0,

  // Dynamic shortcut, which means it was published at runtime using the
  // ShortcutManagerAPI. Dynamic shortcuts are links to specific,
  // context-sensitive actions within the app.
  kDynamic = 1,
};

// Describes app shortcut that is published by Android's ShortcutManager.
struct AppShortcutItem {
  // The ID of this shortcut. Unique within each publisher app and stable across
  // devices.
  string shortcut_id;

  // The short description of this shortcut.
  string short_label;

  // The icon for this shortcut, decoded in the utility process. This will be
  // replaced by |icon|.
  array<uint8> icon_png;

  // The package name of the publisher app.
  [MinVersion=31] string? package_name;

  // The category type of this shortcut.
  [MinVersion=32] AppShortcutItemType type;

  // "Rank" of a shortcut, which is a non-negative, sequential value.
  [MinVersion=32] int32 rank;

  // The icon for this shortcut, decoded in the utility process.
  [MinVersion=46] RawIconPngData? icon;
};

[Extensible]
enum PaiFlowState {
    // PAI flow succeeded.
    SUCCEEDED = 0,
    // PAI flow state was not returned.
    UNKNOWN = 1,
    // PAI flow failed due to no account was provided.
    NO_ACCOUNT = 2,
    // PAI flow failed due Play Store returned no app to install.
    NO_APPS = 3,
    // PAI flow was interrupted.
    INTERRUPTED = 4,
    // PAI flow failed due to no response from Play Store.
    PLAY_STORE_NOT_RESPONDED = 5,
    // PAI flow failed due to no access to Play Store.
    PLAY_STORE_NO_ACCESS = 6,
    // PAI flow failed due to no ArcGmsProxy found.
    PROXY_NOT_FOUND = 7,
    // PAI flow failed due to no ArcGmsProxy access.
    PROXY_NO_ACCESS = 8,
    // PAI flow timeout occurred.
    TIMEOUT = 9,
};

// Names and values match the CATEGORY_ constants on
// android.content.pm.ApplicationInfo.
[Extensible]
enum AppCategory {
  [Default] kUndefined = -1,
  kGame = 0,
  kAudio = 1,
  kVideo = 2,
  kImage = 3,
  kSocial = 4,
  kNews = 5,
  kMaps = 6,
  kProductivity = 7,
  kAccessibility = 8,
};

// Next method ID: 21
// Deprecated method IDs: 1
interface AppHost {
  // Sends newly added ARC app to Chrome. This message is sent when ARC receives
  // package added notification. Multiple apps may be added in the one package.
  [MinVersion=1] OnAppAddedDeprecated@2(AppInfo app);

  // Receives a list of available ARC apps to Chrome. Members of AppInfo must
  // contain non-empty string.
  OnAppListRefreshed@0(array<AppInfo> apps);

  // Notifies that a package has been added.
  [MinVersion=8] OnPackageAdded@8(ArcPackageInfo arcPackageInfo);

  // Notifies that a package list of apps has been updated.
  [MinVersion=14] OnPackageAppListRefreshed@13(string package_name,
                                               array<AppInfo> apps);

  // Receives a list of available ARC packages to Chrome. Members of
  // PackageInfo must contain non-empty string.
  [MinVersion=8] OnPackageListRefreshed@9(array<ArcPackageInfo> packages);

  // Notifies that a package has been modified.
  [MinVersion=8] OnPackageModified@10(ArcPackageInfo arcPackageInfo);

  // Sends removed ARC package to Chrome. |package_name| must contain non-empty
  // string. This message is sent when ARC receives package removed
  // notification. Removing one package can potentially remove more than one
  // app.
  [MinVersion=1] OnPackageRemoved@3(string package_name);

  // Sends information about newly created task |package_name| and |activity|
  // specifies launch activity and |intent| is initial intent used to start
  // new task. |session_id| is the window_id of |window_info| from app launch
  // parameters. |session_id| is -1 if the window_id is not set.
  [MinVersion=4] OnTaskCreated@4(int32 task_id@0,
                                 string package_name@1,
                                 string activity@2,
                                 [MinVersion=13] string? name@3,
                                 [MinVersion=15] string? intent@4,
                                 [MinVersion=48] int32 session_id@5);

  // Sends task label and icon. This is deprecated and will soon be replaced by
  // OnTaskDescriptionChanged().
  [MinVersion=19] OnTaskDescriptionUpdated@17(int32 task_id,
                                              string label,
                                              array<uint8> icon_png_data);

  // Sends task label and icon.
  [MinVersion=46] OnTaskDescriptionChanged@18(
      int32 task_id,
      string label,
      RawIconPngData icon,
      [MinVersion=49] uint32 primary_color,
      [MinVersion=49] uint32 status_bar_color);

  // Notifies that task has been destroyed.
  [MinVersion=4] OnTaskDestroyed@5(int32 task_id);

  // Notifies that task has been activated.
  [MinVersion=4] OnTaskSetActive@6(int32 task_id);

  // Notifies that notifications enabled settings in Android is changed.
  [MinVersion=7] OnNotificationsEnabledChanged@7(string package_name,
                                                 bool enabled);

  // Notifies that an application shortcut needs to be created.
  [MinVersion=9] OnInstallShortcut@11(ShortcutInfo shortcut);

  // Notifies that Play Store installation has been started. |package_name|
  // specifies installation package
  [MinVersion=16] OnInstallationStarted@14(
      [MinVersion=17] string? package_name@0);

  // Notifies that Play Store installation is finished. |result| contains
  // details of installation result.
  [MinVersion=16] OnInstallationFinished@15(
      [MinVersion=17] InstallationResult? result@1);

  // Notifies that an application shortcut needs to be deleted. Shortcut is
  // defined by its |intent_uri| and |package_name|.
  [MinVersion=18] OnUninstallShortcut@16(string package_name,
                                         string intent_uri);

  // Notifies that a package installation has a new progress value.
  [MinVersion=58] OnInstallationProgressChanged@19(string package_name,
                                                   float progress);

  // Notifies that a package installation session has either become active
  // (currently downloading or installing) or inactive (installation is
  // pending or paused).
  [MinVersion=58] OnInstallationActiveChanged@20(string package_name,
                                                 bool active);
};

// Next method ID: 44
// Deprecated method IDs: 0, 1, 2, 3, 4, 6, 9, 12, 13, 15, 17, 18, 19, 22, 29,
//     31
interface AppInstance {
  // Establishes full-duplex communication with the host.
  [MinVersion=26] Init@21(pending_remote<AppHost> host_remote) => ();

  // Closes the the given task.
  [MinVersion=4] CloseTask@8(int32 task_id);

  // Sends a request to ARC to install package.
  [MinVersion=8] InstallPackage@11(ArcPackageInfo arcPackageInfo);

  // Sends a request to ARC to launch an ARC app with specific launch window
  // info.
  [MinVersion=47] LaunchAppWithWindowInfo@38(string package_name,
                                            string activity,
                                            WindowInfo window_info);

  // Sends a request to ARC for the Android launcher to launch the specified app
  // shortcut.
  [MinVersion=30] LaunchAppShortcutItem@24(
      string package_name, string shortcut_id, int64 display_id);

  // Sends a request to ARC to launch an ARC app with specific launch window
  // info.
  [MinVersion=47] LaunchIntentWithWindowInfo@39(string intent_uri,
                                                WindowInfo window_info);

  // Updates ghost window info to ARC.
  [MinVersion=49] UpdateWindowInfo@40(WindowInfo window_info);

  // Sends a request for the ARC icon of a given resource id and
  // |pixel_size|. This is deprecated and will soon be replaced by GetAppIcon().
  [MinVersion=36] RequestAppIcon@27(string package_name,
                                    string activity,
                                    int32 pixel_size) =>
                                        (array<uint8> icon_png_data);

  // Sends a request for the ARC icon of a given resource id and
  // |pixel_size|.
  [MinVersion=46] GetAppIcon@35(string package_name,
                                string activity, int32 pixel_size) =>
                                    (RawIconPngData icon);

  // Sends a request for the ARC shortcut icon of a given resource id and
  // |pixel_size|. This is deprecated and will soon be replaced by
  // GetAppShortcutIcon().
  [MinVersion=36] RequestShortcutIcon@28(string icon_resource_id,
                                         int32 pixel_size) =>
                                             (array<uint8> icon_png_data);

  // Sends a request for the ARC shortcut icon of a given resource id and
  // |pixel_size|.
  [MinVersion=46] GetAppShortcutIcon@36(string icon_resource_id,
                                        int32 pixel_size) =>
                                            (RawIconPngData icon);

  // Sends a request for the ARC icon for a given |package_name| and
  // |pixel_size|. If |normalize| is true, the icon will be normalized per
  // Android's icon guidelines, otherwise, the raw unnormalized icon is
  // returned. Returns an empty array if an error occurred. This is deprecated
  // and will soon be replaced by GetPackageIcon().
  [MinVersion=38] RequestPackageIcon@30(string package_name,
                                        int32 pixel_size,
                                        bool normalize) =>
                                            (array<uint8> icon_png_data);

  // Sends a request for the ARC icon for a given |package_name| and
  // |pixel_size|. If |normalize| is true, the icon will be normalized per
  // Android's icon guidelines, otherwise, the raw unnormalized icon is
  // returned. Returns an empty array if an error occurred.
  [MinVersion=46] GetPackageIcon@37(string package_name,
                                    int32 pixel_size,
                                    bool normalize) =>
                                        (RawIconPngData icon);

  // Removes cached shortcut icon with the given resource id.
  [MinVersion=9] RemoveCachedIcon@14(string icon_resource_id);

  // Activates the given task and move it to foreground.
  [MinVersion=4] SetTaskActive@7(int32 task_id);

  [MinVersion=5] ShowPackageInfoDeprecated@9(string package_name,
                                             Rect dimension_on_screen);

  [MinVersion=10] ShowPackageInfoOnPageDeprecated@15(string package_name,
                                                     ShowPackageInfoPage page,
                                                     Rect dimension_on_screen);

  // Sends a request to ARC to show package info for given package on the
  // specified page.
  [MinVersion=23] ShowPackageInfoOnPage@20(string package_name,
                                           ShowPackageInfoPage page,
                                           int64 display_id);

  // Sets notification setting for the package.
  [MinVersion=6] SetNotificationsEnabled@10(string package_name, bool enabled);

  // Sends a request to ARC to start PAI flow and receives result status.
  [MinVersion=40] StartPaiFlow@32() => (PaiFlowState state);

  // Sends a request to ARC to start FastAppReinstall flow.
  [MinVersion=33] StartFastAppReinstallFlow@25(array<string> arc_package_names);

  // Sends a request to ARC to uninstall the given package.  Error (if ever
  // happens) is ignored, and uninstall option should appear in the UI.
  [MinVersion=2] UninstallPackage@5(string package_name);

  // Sends a request to ARC to call AppHost::OnPackageAppListRefreshed and
  // receive the latest data of a specified app.
  [MinVersion=60] UpdateAppDetails@42(string package_name);

  // Returns Android instance id as it is registered on Google servers. 0 is
  // reserved for the case when Android instance id could not be determined,
  // however this should not normally happen once app instance is connected
  // after ARC provisioning that includes registering Android instance on
  // Google servers (known as initial Check-in flow).
  [MinVersion=42] GetAndroidId@33() => (int64 android_id);

  // Sends a request to ARC to get app shortcuts for apps in global scope that
  // match a |query|. Limits the results to only return |max_results|.
  [MinVersion=34] GetAppShortcutGlobalQueryItems@26(
      string query, int32 max_results) =>
          (array<AppShortcutItem> shortcut_items);

  // Sends a request to ARC to get app shortcuts for app with |package_name|.
  [MinVersion=29] GetAppShortcutItems@23(string package_name) =>
      (array<AppShortcutItem> shortcut_items);

  // Starts a query for Play Store apps.
  [MinVersion=20] GetRecentAndSuggestedAppsFromPlayStore@16(
      string query, int32 max_results) =>
          (AppDiscoveryRequestState state@1,
           array<AppDiscoveryResult> results@0);

  // Queries whether |package_name| is installable for the current user. This
  // may return false if the user has already installed |package_name|, or if
  // it isn't available in the user's store.
  [MinVersion=43] IsInstallable@34(string package_name) =>
      (bool is_installable);

  // Returns the app category of the given package. Corresponds to |category|
  // field on android.content.pm.ApplicationInfo.
  // Returns kUndefined if the package is not found or if the package does not
  // declare an app category.
  [MinVersion=53] GetAppCategory@41(string package_name) =>
      (AppCategory category);

  // Sets app locale for |package_name|. Empty |locale_tag| indicates system
  // language being chosen.
  // The |locale_tag| is using string as there's no direct representation for
  // locale (which is based on IETF BCP 47). As for the content of the string,
  // it's defined by app, so we shouldn't trust the content of this string.
  // As for the implementation / use case, this will only be passed to Android,
  // which is then sent back to the app as is.
  [MinVersion=63] SetAppLocale@43(string package_name, string locale_tag);
};