components/services/app_service/public/mojom/types.mojom

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

module apps.mojom;

import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/time.mojom";
import "ui/gfx/image/mojom/image.mojom";
import "url/mojom/url.mojom";

// Information about an app. See components/services/app_service/README.md.
struct App {
  AppType app_type;
  string app_id;

  // The fields above are mandatory. Everything else below is optional.

  Readiness readiness;
  string? name;
  string? short_name;

  // An optional, publisher-specific ID for this app, e.g. for Android apps,
  // this field contains the Android package name, and for web apps, it
  // contains the start URL.
  string? publisher_id;

  string? description;
  string? version;
  array<string> additional_search_terms;
  IconKey? icon_key;
  mojo_base.mojom.Time? last_launch_time;
  mojo_base.mojom.Time? install_time;

  // This vector must be treated atomically, if there is a permission
  // change, the publisher must send through the entire list of permissions.
  // Should contain no duplicate IDs.
  // If empty during updates, Subscriber can assume no changes.
  // There is no guarantee that this is sorted by any criteria.
  array<Permission> permissions;

  // Whether the app was installed by sync, policy or as a default app.
  InstallSource install_source;

  // Whether the app is an extensions::Extensions where is_platform_app()
  // returns true.
  OptionalBool is_platform_app;

  // TODO(nigeltao): be more principled, instead of ad hoc show_in_xxx and
  // show_in_yyy fields?
  OptionalBool recommendable;
  OptionalBool searchable;
  OptionalBool show_in_launcher;
  OptionalBool show_in_shelf;
  OptionalBool show_in_search;
  OptionalBool show_in_management;

  // Whether the app icon should add the notification badging.
  OptionalBool has_badge;

  // Paused apps cannot be launched, and any running apps that become paused
  // will be stopped. This is independent of whether or not the app is ready to
  // be launched (defined by the Readiness field).
  OptionalBool paused;

  // This vector stores all the intent filters defined in this app. Each
  // intent filter defines a matching criteria for whether an intent can
  // be handled by this app. One app can have multiple intent filters.
  array<IntentFilter> intent_filters;

  // Whether the app can be free resized. If this is true, various resizing
  // operations will be restricted.
  OptionalBool resize_locked;

  // Whether the app's display mode is in the browser or otherwise.
  WindowMode window_mode;

  // When adding new fields, also update the Merge method and other helpers in
  // components/services/app_service/public/cpp/app_update.*
};

struct Permission {
  // An AppType-specific value, opaque to the App Service.
  // Different publishers (with different AppType's) can
  // re-use the same numerical value to mean different things.
  uint32 permission_id;
  PermissionValueType value_type;
  // The semantics of value depends on the value_type.
  uint32 value;
  // If the permission is managed by an enterprise policy.
  bool is_managed;
};

// The types of apps available in the registry.
enum AppType {
  kUnknown = 0,
  kArc,                   // Android app.
  kBuiltIn,               // Built-in app.
  kCrostini,              // Linux (via Crostini) app.
  kExtension,             // Extension-backed app.
  kWeb,                   // Web app.
  kMacOs,                 // Mac OS app.
  kPluginVm,              // Plugin VM app, see go/pluginvm.
  kStandaloneBrowser,     // Lacros browser app, see //docs/lacros.md.
  kRemote,                // Remote app.
  kBorealis,              // Borealis app, see go/borealis-app.
  kSystemWeb,             // System web app.
  kStandaloneBrowserExtension,  // Extension based apps hosted in Lacros.
};

// Whether an app is ready to launch, i.e. installed.
enum Readiness {
  kUnknown = 0,
  kReady,                // Installed and launchable.
  kDisabledByBlocklist,  // Disabled by SafeBrowsing.
  kDisabledByPolicy,     // Disabled by admin policy.
  kDisabledByUser,       // Disabled by explicit user action.
  kTerminated,           // Renderer process crashed.
  kUninstalledByUser,
  // Removed apps are purged from the registry cache and have their
  // associated memory freed. Subscribers are not notified of removed
  // apps, so publishers must set the app as uninstalled before
  // removing it.
  kRemoved,
  kUninstalledByMigration,
};

// How the app was installed.
enum InstallSource {
  kUnknown = 0,
  kSystem,     // Installed with the system and is considered a part of the OS.
  kPolicy,     // Installed by policy.
  kOem,        // Installed by an OEM.
  kDefault,    // Preinstalled by default, but is not considered a system app.
  kSync,       // Installed by sync.
  kUser,       // Installed by user action.
};

// What caused the app to be uninstalled.
enum UninstallSource {
  kUnknown = 0,
  kAppList,       // Uninstall by the user from the App List (Launcher)
  kAppManagement, // Uninstall by the user from the App Management page
  kShelf,         // Uninstall by the user from the Shelf
  kMigration,     // Uninstall by app migration.
};

// Augments a bool to include an 'unknown' value.
enum OptionalBool {
  kUnknown = 0,
  kFalse,
  kTrue,
};

struct IconKey {
  // A timeline value for icons that do not change.
  const uint64 kDoesNotChangeOverTime = 0;

  const int32 kInvalidResourceId = 0;

  // A monotonically increasing number so that, after an icon update, a new
  // IconKey, one that is different in terms of field-by-field equality, can be
  // broadcast by a Publisher.
  //
  // The exact value of the number isn't important, only that newer IconKey's
  // (those that were created more recently) have a larger timeline than older
  // IconKey's.
  //
  // This is, in some sense, *a* version number, but the field is not called
  // "version", to avoid any possible confusion that it encodes *the* app's
  // version number, e.g. the "2.3.5" in "FooBar version 2.3.5 is installed".
  //
  // For example, if an app is disabled for some reason (so that its icon is
  // grayed out), this would result in a different timeline even though the
  // app's version is unchanged.
  uint64 timeline;
  // If non-zero (or equivalently, not equal to kInvalidResourceId), the
  // compressed icon is compiled into the Chromium binary as a statically
  // available, int-keyed resource.
  int32 resource_id;
  // A bitmask of icon post-processing effects, such as desaturation to gray
  // and rounding the corners.
  uint32 icon_effects;

  // When adding new fields, also update the IconLoader::Key type in
  // components/services/app_service/public/cpp/icon_loader.*
};

enum IconType {
  // Sentinel value used in error cases.
  kUnknown,
  // Icon as an uncompressed gfx::ImageSkia with no standard Chrome OS mask.
  kUncompressed,
  // Icon as compressed bytes with no standard Chrome OS mask.
  kCompressed,
  // Icon as an uncompressed gfx::ImageSkia with the standard Chrome OS mask
  // applied. This is the default suggested icon type.
  kStandard,
};

struct IconValue {
  IconType icon_type;
  gfx.mojom.ImageSkia? uncompressed;
  array<uint8>? compressed;
  bool is_placeholder_icon;
};

// Enumeration of possible app launch sources.
// This should be kept in sync with histogram_suffixes_list.xml, and
// LaunchSource in enums.xml.
// Note the enumeration is used in UMA histogram so entries should not be
// re-ordered or removed. New entries should be added at the bottom.
enum LaunchSource {
  kUnknown = 0,
  kFromAppListGrid = 1,               // Grid of apps, not the search box.
  kFromAppListGridContextMenu = 2,    // Grid of apps; context menu.
  kFromAppListQuery = 3,              // Query-dependent results (larger icons).
  kFromAppListQueryContextMenu = 4,   // Query-dependent results; context menu.
  kFromAppListRecommendation = 5,     // Query-less recommendations (smaller
                                      // icons).
  kFromParentalControls = 6,          // Parental Controls Settings Section and
                                      // Per App time notification.
  kFromShelf = 7,                     // Shelf.
  kFromFileManager = 8,               // FileManager.
  kFromLink = 9,                      // Left-licking on links in the browser.
  kFromOmnibox = 10,                  // Enter URL in the Omnibox in the
                                      // browser.
  kFromChromeInternal = 11,           // Chrome internal call.
  kFromKeyboard = 12,                 // Keyboard shortcut for opening app.
  kFromOtherApp = 13,                 // Clicking link in another app or webui.
  kFromMenu = 14,                     // Menu.
  kFromInstalledNotification = 15,    // Installed notification
  kFromTest = 16,                     // Test
  kFromArc = 17,                      // Arc.
  kFromSharesheet = 18,               // Sharesheet.
  kFromReleaseNotesNotification = 19, // Release Notes Notification.
  kFromFullRestore = 20,              // Full restore.
  kFromSmartTextContextMenu = 21,     // Smart text selection context menu.
  kFromDiscoverTabNotification = 22,  // Discover Tab Notification.
};

enum TriState {
  kAllow,
  kBlock,
  kAsk,
};

enum PermissionValueType {
  kBool,                       // Permission.value is a Bool (either 0 or 1).
  kTriState,                   // Permission.value is a TriState.
};

// MenuItems are used to populate context menus, e.g. in the app list or shelf.
// Note: Some menu item types only support a subset of these item features.
// Please update comments below (MenuItemType -> [fields expected for usage])
// when anything changed to MenuItemType or MenuItem.
//
// kCommand    -> [command_id, string_id].
// kRadio      -> [command_id, string_id, radio_group_id].
// kSeparator  -> [command_id].
// kSubmenu    -> [command_id, string_id, submenu].
// kPublisherCommand -> [command_id, shortcut_id, label, image].
//
struct MenuItems {
  array<MenuItem> items;
};

struct MenuItem {
  MenuItemType type;                 // The type of the menu item.
  int32 command_id;                  // The menu item command id.
  int32 string_id;                   // The id of the menu item label.
  array<MenuItem> submenu;           // The optional nested submenu item list.
  int32 radio_group_id;              // The radio group id.
  string shortcut_id;                // The shortcut id, may be empty.
  string label;                      // The string label, may be empty.
  gfx.mojom.ImageSkia? image;        // The image icon, may be null.
};

// The types of menu items shown in the app list or shelf.
enum MenuItemType {
  kCommand,    // Performs an action when selected.
  kRadio,      // Can be selected/checked among a group of choices.
  kSeparator,  // Shows a horizontal line separator.
  kSubmenu,    // Presents a submenu within another menu.
  kPublisherCommand, // Performs an app publisher shortcut action when selected.
};

// Which component requests context menus, the app list or shelf.
enum MenuType {
  kAppList,
  kShelf,
};

// The intent filter matching condition types.
enum ConditionType {
  kScheme,    // Matches the URL scheme (e.g. https, tel).
  kHost,      // Matches the URL host (e.g. www.google.com).
  kPattern,   // Matches the URL pattern (e.g. /abc/*).
  kAction,    // Matches the action type (e.g. view, send).
  kMimeType,  // Matches the data mime type (e.g. image/jpeg).
};

// The pattern match type for intent filter pattern condition.
enum PatternMatchType {
  kNone = 0,
  kLiteral,
  kPrefix,
  kGlob,
  kMimeType,
};

// For pattern type of condition, the value match will be based on the pattern
// match type. If the match_type is kNone, then an exact match with the value
// will be required.
struct ConditionValue {
  string value;
  PatternMatchType match_type; // This will be None for non pattern conditions.
};

// The condition for an intent filter. It matches if the intent contains this
// condition type and the corresponding value matches with any of the
// condition_values.
struct Condition {
  ConditionType condition_type;
  array<ConditionValue> condition_values;
};

// An intent filter is defined by an app, and contains a list of conditions that
// an intent needs to match. If all conditions match, then this intent filter
// matches against an intent.
struct IntentFilter {
  array<Condition> conditions;

  // Activity which registered this filter. We only fill this field for ARC
  // share intent filters.
  string? activity_name;

  // The label shown to the user for this activity.
  string? activity_label;
};

// Metadata for a single file shared through an intent.
struct IntentFile {
  // The URL of the file to share. Normally has the filesystem: scheme, but
  // could be externalfile: or a different scheme, depending on the source.
  url.mojom.Url url;

  // The following optional fields can be provided to supply additional metadata
  // information in cases where fetching the metadata through the file would be
  // difficult or expensive.

  string? mime_type;  // File MIME type.
  string? file_name;  // Human readable file name, including extension. Should
                      // not contain path separators.
  uint64 file_size;   // File size in bytes.
};

// Action and resource handling request. This should
// be kept in sync with ConvertIntentToValue and ConvertValueToIntent in
// components/services/app_service/public/cpp/intent_util.*
struct Intent {
  string? action; // Intent action. e.g. view, send.
  url.mojom.Url? url; // The URL of the intent. e.g. https://www.google.com/.
  string? mime_type; // MIME type. e.g. text/plain, image/*.
  array<IntentFile>? files; // The files to share.
  string? activity_name; // The activity for the app to launch.

  // The Drive share URL, this is only filled if the intent contains a file
  // from Google Drive.
  url.mojom.Url? drive_share_url;
  string? share_text; // Text to share. e.g. Share link to other app.
  string? share_title; // Title for the share.
  string? start_type; // Start type.
  array<string>? categories;
  string? data;  // URI
  OptionalBool ui_bypassed; // Whether or not the user saw the UI.
  map<string, string>? extras; // Optional string extras.
};

// Represents a group of |app_ids| that is no longer preferred app of their
// corresponding |intent_filters|.
struct ReplacedAppPreferences {
  map<string, array<IntentFilter>> replaced_preference;
};

// The preferred app represents by |app_id| for |intent_fitler|.
struct PreferredApp {
  IntentFilter intent_filter;
  string app_id;
};

struct FilePaths {
  array<mojo_base.mojom.FilePath> file_paths;
};

// Enumeration of possible app launch sources.
// This should be kept in sync with LaunchSource in
// extensions/common/api/app_runtime.idl, and GetLaunchSourceEnum() in
// extensions/browser/api/app_runtime/app_runtime_api.cc.
// Note the enumeration is used in UMA histogram so entries
// should not be re-ordered or removed.
enum AppLaunchSource {
  kSourceNone = 0,
  kSourceUntracked = 1,
  kSourceAppLauncher = 2,
  kSourceNewTabPage = 3,
  kSourceReload = 4,
  kSourceRestart = 5,
  kSourceLoadAndLaunch = 6,
  kSourceCommandLine = 7,
  kSourceFileHandler = 8,
  kSourceUrlHandler = 9,
  kSourceSystemTray = 10,
  kSourceAboutPage = 11,
  kSourceKeyboard = 12,
  kSourceExtensionsPage = 13,
  kSourceManagementApi = 14,
  kSourceEphemeralAppDeprecated = 15,
  kSourceBackground = 16,
  kSourceKiosk = 17,
  kSourceChromeInternal = 18,
  kSourceTest = 19,
  kSourceInstalledNotification = 20,
  kSourceContextMenu = 21,
  kSourceArc = 22,
  kSourceIntentUrl = 23,  // App launch triggered by a URL.
  kSourceRunOnOsLogin = 24,  // App launched during OS login.
};

// Don't remove items or change the order of this enum.  It's used in
// histograms and preferences.
enum LaunchContainer {
  kLaunchContainerWindow = 0,
  kLaunchContainerPanelDeprecated = 1,
  kLaunchContainerTab = 2,
  // For platform apps, which don't actually have a container (they just get a
  // "onLaunched" event).
  kLaunchContainerNone = 3,
};

// Information about whether an app is accessing some capability, e.g. camera,
// microphone.
struct CapabilityAccess {
  string app_id;

  // The fields above are mandatory. Everything else below is optional.

  // Whether the app is accessing camera.
  OptionalBool camera;

  // Whether the app is accessing microphone.
  OptionalBool microphone;

  // When adding new fields, also update the Merge method and other helpers in
  // components/services/app_service/public/cpp/access_update.*
};

// The window bounds information.
struct Rect {
  int32 x;
  int32 y;
  int32 width;
  int32 height;
};

// The window information to launch an app.
struct WindowInfo {
  int32 window_id = -1;
  int32 state = 0;
  int64 display_id = -1;
  Rect? bounds;
};

// The window mode that each app will open in.
enum WindowMode {
  kUnknown = 0,
  // Opens in a standalone window
  kWindow,
  // Opens in the default web browser
  kBrowser,
  // Opens in a tabbed app window
  kTabbedWindow,
};