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

// Copyright 2016 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: 54

module arc.mojom;

import "ash/components/arc/mojom/app.mojom";
import "ash/components/arc/mojom/bitmap.mojom";
import "ash/components/arc/mojom/camera_intent.mojom";
import "ash/components/arc/mojom/intent_common.mojom";
import "ash/components/arc/mojom/scale_factor.mojom";
import "mojo/public/mojom/base/safe_base_name.mojom";
import "url/mojom/url.mojom";

[Extensible]
enum PatternType {
  PATTERN_LITERAL = 0,
  PATTERN_PREFIX = 1,
  PATTERN_SIMPLE_GLOB = 2,
  [MinVersion=51] PATTERN_ADVANCED_GLOB = 3,
  [MinVersion=51] PATTERN_SUFFIX = 4,
  [MinVersion=51, Default] kUnknown = -1,
};

struct PatternMatcher {
  string pattern;
  PatternType type;
};

struct AuthorityEntry {
  string host;
  int32 port;
};

struct UriComponents {
  string scheme; // Scheme to create URI in ARC.
  string authority; // Authority to create URI in ARC.
  string path; // Path to create URI in ARC.
};

struct IntentInfo {
  string action;
  array<string>? categories;
  string? data;  // URI
  string? type;  // explicit MIME type for data
  [MinVersion=13] string? clip_data_uri;  // optional URI to provide as ClipData.
  [MinVersion=20] bool ui_bypassed; // Whether or not the user saw the UI.

  // Optional string extras. These are the key-value pairs stored in android
  // intents to carry additional data. See:
  // https://developer.android.com/reference/android/content/Intent#putExtra(java.lang.String,%20java.lang.String)
  [MinVersion=22] map<string, string>? extras;

  // Optional URI components to build data URI in ARC. If |IntentInfo.data| is
  // set, this field will be ignored.
  [MinVersion=30] UriComponents? uri_components;
};

struct IntentFilter {
  array<string> actions;
  array<string> categories;
  array<string> data_schemes;
  [MinVersion=10] array<AuthorityEntry>? data_authorities;
  [MinVersion=10] array<PatternMatcher>? data_paths;
  [MinVersion=10] array<PatternMatcher>? deprecated_data_scheme_specific_parts;
  [MinVersion=21] string? package_name; // Package which registered the filter.
  [MinVersion=38] array<string>? mime_types; // Intent filer mime types.

  // Activity which registered the filter.
  [MinVersion=39] string? activity_name;

  // The label shown to the user for this activity.
  [MinVersion=41] string? activity_label;
};

// Describes a package that can handle an intent.
struct IntentHandlerInfo {
  string name;
  string package_name;
  string activity_name;  // A hint for retrieving the package's icon.
  [MinVersion=4] ActionType action_type;
  [MinVersion=6] bool is_preferred;
  [MinVersion=11] string? action;  // e.g. "android.intent.action.VIEW"
  // RequestUrlHandlerList may fill |fallback_url| when it is called with an
  // intent: URL.
  [MinVersion=14] string? fallback_url;
};

// Describes an icon for the activity.
struct ActivityIcon {
  ActivityName activity;
  uint32 width;  // in px
  uint32 height;  // in px
  array<uint8> icon;  // in BGRA8888 format
  [MinVersion=40] RawIconPngData? icon_png_data;
};

// URL associated with its mime type.
struct UrlWithMimeType {
  string url;
  string mime_type;
};

// Describes a specific page in chrome://, about:blank, about:downloads and about:history.
// This enum should have only the chrome pages used by ARC.
// Numerical values should be used for each constant and should not be reused.
[Extensible]
enum ChromePage {
  MULTIDEVICE = 0,
  MAIN = 1,
  POWER = 2,
  BLUETOOTH = 3,
  DATETIME = 4,
  DISPLAY = 5,
  WIFI = 6,
  LANGUAGES = 7,
  // TODO(b/181930573): Remove after P retires. This value is used only by P.
  PRIVACY = 8,
  HELP = 9,
  ACCOUNTS = 10,
  APPEARANCE = 11,
  AUTOFILL = 12,
  BLUETOOTHDEVICES = 13,
  CHANGEPICTURE = 14,
  CLEARBROWSERDATA = 15,
  CUPSPRINTERS = 17,
  DOWNLOADS = 18,
  KEYBOARDOVERLAY = 19,
  LOCKSCREEN = 20,
  MANAGEACCESSIBILITY = 21,
  NETWORKSTYPEVPN = 22,
  ONSTARTUP = 23,
  PASSWORDS = 24,
  POINTEROVERLAY = 25,
  RESET = 26,
  SEARCH = 27,
  STORAGE = 28,
  SYNCSETUP = 29,
  ABOUTBLANK = 30,
  ABOUTDOWNLOADS = 31,
  ABOUTHISTORY = 32,
  // 33-48 are removed intentionally. Do not reuse them.
  MANAGEACCESSIBILITYTTS = 49,
  // 50-70 are removed intentionally. Do not reuse them.
  OSLANGUAGESINPUT = 71,
  OSLANGUAGESLANGUAGES = 72,
  // 73-76 are removed intentionally. Do not reuse them.
  SMARTPRIVACY = 77,
  PRIVACYHUB = 78,
  TEXTTOSPEECH = 79,
  AUDIO = 80,
  DISPLAYANDMAGNFICATION = 81,
  KEYBOARDANDTEXTINPUT = 82,
  CURSORANDTOUCHPAD = 83,
  AUDIOANDCAPTIONS = 84,
  PERDEVICEKEYBOARD = 85,
  PERDEVICEMOUSE = 86,
  PERDEVICETOUCHPAD = 87,
  PERDEVICEPOINTINGSTICK = 88,
  GRAPHICSTABLET = 89,
  NETWORKS = 90,

  // Next value to be used is 91.
};

// Describes an unique chrome app.
[Extensible]
enum ChromeApp {
  CAMERA,

  LAST = CAMERA,
};

// Describes an action given by the android text selection delegate (e.g. open
// maps).
struct TextSelectionAction {
  // The icon of the component that can handle the action intent.
  ActivityIcon icon;

  // The activity and package name of the component that handle the intent.
  ActivityName activity;

  // The title of the action that will be shown in the UI, e.g. "Map", "Call",
  // "Open".
  string title;

  // The intent to launch when the action is clicked.
  IntentInfo action_intent;

  // Whether the action was generated by the Android TextClassifier.
  [MinVersion=23] bool text_classifier_action;

  // The bitmap icon of the component that can handle the action intent.
  [MinVersion=23] ArcBitmap? bitmap_icon;
};

// Location and metadata for a single file attached to an app launch.
struct LaunchFileInfo {
  // URI location for the file, likely with a content:// scheme.
  url.mojom.Url content_uri;

  // MIME type for the file. Will be "application/octet-stream" if no more
  // specific type can be determined.
  string type;

  // Unused, replaced by |name|.
  string removed_name;

  // Size of the file in bytes.
  uint64 size;

  // Human readable name for the file.
  [MinVersion=48] mojo_base.mojom.SafeBaseName? name;
};

// Contains the information needed to launch an app along with any data which
// was shared to it.
struct LaunchIntent {
  string action;

  // URI for the data to be handled by this intent.
  url.mojom.Url? data;

  // MIME type of the intent data.
  string? type;

  // The contents of Intent.EXTRA_SUBJECT.
  string? extra_subject;

  // The contents of Intent.EXTRA_TEXT.
  string? extra_text;

  // File metadata for files shared through Intent.EXTRA_STREAM.
  array<LaunchFileInfo>? files;
};

// Contains information about supported links for an ARC package.
[RenamedFrom="arc.mojom.SupportedLinks"]
struct SupportedLinksPackage {
  // Android package name of the app.
  string package_name;
  // Deprecated and no longer used.
  array<IntentFilter>? deprecated_filters;
};

// The source of a change in the supported links setting.
[Extensible]
enum SupportedLinkChangeSource {
  kUnknown,
  // The ARC system made a change to the supported links setting without direct
  // user input (e.g. a new app was installed).
  kArcSystem,
  // The update to the supported links setting was the result of a user
  // action/choice.
  kUserPreference,
};

// Android setting that we want to relay back to update Chrome setting.
[Extensible]
enum AndroidSetting {
  [Default] kUnknown = 0,
  kGeoLocation,           // Deprecated, replaced with specific scenarios.
  kGeoLocationAtBoot,
  kGeoLocationUserTriggered,
  // We don't need atBoot for accuracy as the value is in sync with GeoLocation
  kGeoLocationAccuracyUserTriggered,
};

// The type of shadow used for Chrome captions.
// https://developer.android.com/reference/android/view/accessibility/CaptioningManager.CaptionStyle
[Extensible]
enum CaptionTextShadowType {
  // Edge type value specifying no character edges.
  kNone = 0,

  // Edge type value specifying uniformly outlined character edges.
  kUniform = 1,

  // Edge type value specifying drop-shadowed character edges.
  kDropShadow = 2,

  // Edge type value specifying raised bevel character edges.
  kRaised = 3,

  // Edge type value specifying depressed bevel character edges.
  kDepressed = 4,

  [Default] kInvalidEnumValue = -1,
};

struct CaptionColor {
  uint8 alpha;
  uint8 red;
  uint8 green;
  uint8 blue;
};

// Encapsulates settings to stylize captions.
// https://developer.android.com/reference/android/view/accessibility/CaptioningManager.CaptionStyle.html
struct CaptionStyle {
  string user_locale;
  float font_scale;
  CaptionColor? text_color;
  CaptionColor? background_color;
  CaptionTextShadowType text_shadow_type;
};

// Accessibility features supported by ARC AccessibilityService.
struct AccessibilityFeatures {
  bool docked_magnifier_enabled;
  bool focus_highlight_enabled;
  bool screen_magnifier_enabled;
  bool select_to_speak_enabled;
  bool spoken_feedback_enabled;
  bool switch_access_enabled;
};

// Interface to interact with a custom tab.
// Close the interface pointer to close the custom tab.
// Next method ID: 1
interface CustomTabSession {
  // Called when "Open in Chrome" button on the custom tab is clicked.
  [MinVersion=26] OnOpenInChromeClicked@0();
};

// Handles intents from ARC in Chrome.
// Deprecated method ID: 4, 9, 10, 16, 18
// Next method ID: 24
interface IntentHelperHost {
  // Called when icons associated with the package are no longer up to date.
  [MinVersion=3] OnIconInvalidated@1(string package_name);

  // Called when intent filters are updated on startup.
  [MinVersion=9] OnIntentFiltersUpdated@5(array<IntentFilter> intent_filters);

  // Opens the downloads directory in the Chrome OS file manager.
  [MinVersion=5] OnOpenDownloads@2();

  // Opens the url with Chrome for Chrome OS.
  // This function is intended to only open URLs that other web content in Chrome would be able to
  // navigate to as well. No special URLs that allow access to privileged functions are allowed.
  OnOpenUrl@0(string url);

  // Opens the |url| with a custom tab.
  // |task_id| specifies the Android task on which the custom tab should be
  // shown.
  [MinVersion=42] OnOpenCustomTab@17(string url, int32 task_id)
      => (pending_remote<CustomTabSession>? session);

  // Opens the wallpaper picker dialog.
  [MinVersion=6] OpenWallpaperPicker@3();

  // Opens the volume control.
  [MinVersion=16] OpenVolumeControl@6();

  // Opens the specified Chrome page in the Chrome browser.
  [MinVersion=17] OnOpenChromePage@7([MinVersion=18] ChromePage page);

  // Opens the specified URL as a web app if it is installed. Otherwise falls
  // back to the behaviour of OnOpenUrl. |url| must have a HTTPS scheme.
  [MinVersion=23] OnOpenWebApp@8(string url);

  // Does a reset of ARC; this wipes /data, and then re-calls on OOBE for
  // account binding to happen again, as if the user just went through OOBE.
  [MinVersion=27] FactoryResetArc@11();

  // Launches camera app from the camera intent.
  // |intent_id| is an unique id that used to recognize different intents.
  // |mode| indicates which mode should camera app land on. If
  // |should_handle_result| is true, the intent expects the captured result
  // will be returned after capturing. If |should_down_scale| is true, the
  // intent expects the captured image would be down-scaled to a small enough
  // size. If |is_secure| is true, the intent is fired when the device is
  // secured, which means the camera app should not show any user-sensitive
  // data. |task_id| represents the id of the caller task in ARC.
  [MinVersion=28] LaunchCameraApp@12(uint32 intent_id,
                                     CameraIntentMode mode,
                                     bool should_handle_result,
                                     bool should_down_scale,
                                     bool is_secure,
                                     [MinVersion=36] int32 task_id);

  // Called when intent filters are updated for one package. This will be
  // called when apps are installed, uninstalled or updated.
  [MinVersion=29] OnIntentFiltersUpdatedForPackage@13(
      string package_name, array<IntentFilter> intent_filters);

  // Closes Chrome camera app.
  [MinVersion=31] CloseCameraApp@14();

  // Checks if given chrome app is enabled.
  [MinVersion=33] IsChromeAppEnabled@15(ChromeApp app) => (bool is_enabled);

  // Called when the link capturing preference for one or more apps has changed.
  // Set the apps in |added_packages| as handling their supported link
  // IntentFilters, and removes the apps in |removed_packages| from handling
  // supported links.
  [MinVersion=47] OnSupportedLinksChanged@20(
      array<SupportedLinksPackage> added_packages,
      array<SupportedLinksPackage> removed_packages,
      [MinVersion=48] SupportedLinkChangeSource source);

  // DEPRECATED: Replaced by `FileSystemHost::OnMediaStoreUriAdded()`.
  // Called when a new entry has been added to the MediaStore.Downloads
  // collection of downloaded items with the specified metadata.
  // |relative_path|      relative path of the download within the Download/
  //                      folder (e.g. "Download/foo/bar.pdf"). The method
  //                      implementation must verify that the `relative_path` is
  //                      in fact within the Download/ folder (or subdirectory),
  //                      treating ARC as an untrusted source.
  // |owner_package_name| package name that contributed the download (e.g.
  //                      "com.bar.foo").
  [MinVersion=44] OnDownloadAddedDeprecated@18(
      string relative_path, string owner_package_name);

  // Opens the web app for a specified URL, if it is installed, and delivers
  // |intent| to it. If the URL is not installed, will open |intent.data| in a
  // browser tab, unless |intent.data| is not set, in which case nothing
  // happens.
  // Note that the |start_url| is used for resolving the app to open, but the
  // actual URL which is loaded is based on the contents of |intent|.
  [MinVersion=45] OnOpenAppWithIntent@19(
      url.mojom.Url start_url, LaunchIntent intent);

  // Opens the global actions dialog.
  [MinVersion=49] OnOpenGlobalActions@21();

  // Close any dialogs opened from ARC.
  [MinVersion=49] OnCloseSystemDialogs@22();

  // Relay android setting to Chrome.
  [MinVersion=50] OnAndroidSettingChange@23(
      AndroidSetting setting, bool is_enabled);
};

// Sends intents to ARC on behalf of Chrome.
// Deprecated method ID: 0, 7, 11, 12, 14, 17, 18
// Next method ID: 24
interface IntentHelperInstance {
  // Sets the given package as a preferred package. The next time an ACTION_VIEW
  // intent is sent with a URL that requires disambiguation, instead of opening
  // the ResolverActivity, this package will be picked if it is on the list.
  // When multiple packages are set as preferred, the most recent setting wins.
  [MinVersion=7] AddPreferredPackage@8(string package_name);

  // Set the verified link domain status to either always open (|always_open| is
  // true) or always ask (|always_open| is false) for the |package_names|.
  // This method will be called when Chrome OS changes the link capturing
  // setting for an app.
  [MinVersion=46] SetVerifiedLinks@21(array<string> package_names,
                                      bool always_open);

  // DEPRECATED. Use HandleIntentWithWindowInfo() instead.
  [MinVersion=12] HandleIntent@10(IntentInfo intent, ActivityName activity);

  // Passes an intent to an activity with a specific launch window info.
  [MinVersion=43] HandleIntentWithWindowInfo@20(
      IntentInfo intent, ActivityName activity, WindowInfo window_info);

  // Handles the URL by sending an ACTION_VIEW intent to the package. The
  // most suitable activity for the URL within the package will be started.
  [MinVersion=2] HandleUrl@2(string url, string package_name);

  // Establishes full-duplex communication with the host.
  [MinVersion=19] Init@13(pending_remote<IntentHelperHost> host_remote) => ();

  // Requests 48dp * 48dp icons of the |activities| suitable for the
  // |scale_factor|. An array of icon data will be returned.
  [MinVersion=3] RequestActivityIcons@4(array<ActivityName> activities,
                                        ScaleFactor scale_factor)
      => (array<ActivityIcon> icons);

  // Requests a list of packages that can handle |intent|.
  [MinVersion=12] RequestIntentHandlerList@9(IntentInfo intent)
      => (array<IntentHandlerInfo> handlers);

  // Requests a list of packages that can handle the URL.
  [MinVersion=2] RequestUrlHandlerList@3(string url)
      => (array<IntentHandlerInfo> handlers);

  // Requests a list of packages that can handle the list of files.
  [MinVersion=4] RequestUrlListHandlerList@6(array<UrlWithMimeType> urls)
      => (array<IntentHandlerInfo> handlers);

  // Send an Android broadcast message to the Android package and class
  // specified.  Data can be sent as extras by including a JSON map string which
  // will be automatically converted to a bundle accessible by the receiver.
  //
  // Note: Broadcasts can only be sent to allowlisted packages.  Packages can be
  // added to the allowlist in ArcBridgeService.java in the Android source.
  [MinVersion=1] SendBroadcast@1(string action,
                                 string package_name,
                                 string cls,
                                 string extras);

  // Asks ChromeTextSelectionDelegate to generate actions that can handle the
  // |text|. |scale_factor| is used to find a suitable icon to show in the
  // context menu.
  [MinVersion=22] RequestTextSelectionActions@15(string text,
                                                 ScaleFactor scale_factor)
      => (array<TextSelectionAction> actions);

  // Sends the captured result |data| for corresponding intent recognized by
  // |intent_id| back to ARC. The handler should handle |data| and maybe notify
  // the intent caller according to the intention of the |action|. |is_success|
  // will be set to true if the ARC received the result and set to false for
  // invalid input.
  [MinVersion=28] HandleCameraResult@16(uint32 intent_id,
                                        CameraIntentAction action,
                                        array<uint8> data)
      => (bool is_success);

  // Request ARC to send the domain verification status update for all packages
  // to Chrome OS.
  [MinVersion=37] RequestDomainVerificationStatusUpdate@19();

  // Requests the service to set the caption style.
  [MinVersion=52] SetCaptionStyle@22(CaptionStyle style);

  // Send list of enabled accessibility features to ARC.
  [MinVersion=53] EnableAccessibilityFeatures@23(AccessibilityFeatures
      features);
};