intent_helper.mojom

// Copyright 2016 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.
//
// Next MinVersion: 49

module arc.mojom;

import "ash/components/arc/mojom/bitmap.mojom";
import "ash/components/arc/mojom/camera_intent.mojom";
import "components/arc/mojom/app.mojom";
import "components/arc/mojom/intent_common.mojom";
import "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,
  PATTERN_PREFIX,
  PATTERN_SIMPLE_GLOB,
};

[Extensible]
enum ShareFiles {
  // 0 and 3: capture that everything went great, the files were copied.
  SINGLE_FILE_SUCCESS = 0,
  // 1 and 4: Whenever we fail to copy, we try to delete the partially copied
  // files, if the backroll goes well we call this entry.
  SINGLE_FILE_BACKROLLED = 1,
  // 2 and 5: Whenever we are unable to backroll because something else went
  // wrong, we place this error on the MISC_ERROR bin. (it could have been a bad
  // file descriptor, or just a read/write error)
  SINGLE_FILE_MISC_ERROR = 2,
  MULTIPLE_FILES_SUCCESS = 3,
  MULTIPLE_FILES_BACKROLLED = 4,
  MULTIPLE_FILES_MISC_ERROR = 5,
  // This records a faulty response from DocumentsUI, since our implementation
  // relies on DocumentsUI, sometimes it may return a bad response that we
  // cannot process (e.g. for a single file DocumentsUI is in charge of creating
  // the new file where we will copy, if it fails it can send us a bad response
  // or maybe DocumentsUI is not returning the expected flags).
  BAD_RESPONSE_FROM_DOCUMENTS_UI = 6,
};

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,
  CLOUDPRINTERS = 16,
  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,

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

// 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;

  // TODO(crbug.com/1238215): Remove references and rename.
  string deprecated_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 an app's supported links.
struct SupportedLinks {
  // Android package name of the app.
  string package_name;
  // A list of all the link intent filters handled by the app. Should only
  // include, link intents. That is, filters must have an http/https scheme and
  // at least one authority. This field can be omitted when deleting supported
  // links for an app.
  array<IntentFilter>? 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,
};

// 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
// Next method ID: 21
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);

  // Records Sharing files feature's metrics via Chrome.
  [MinVersion=24] RecordShareFilesMetricsDeprecated@9(ShareFiles flag);

  // 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);

  // DEPRECATED. Use OnSupportedLinksChanged() instead.
  // TODO(crbug.com/1265318): Remove this method.
  [MinVersion=34] OnPreferredAppsChangedDeprecated@16(
      array<IntentFilter> added, array<IntentFilter> deleted);

  // 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<SupportedLinks> added_packages,
      array<SupportedLinks> removed_packages,
      [MinVersion=48] SupportedLinkChangeSource source);

  // 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] OnDownloadAdded@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);
};

// Sends intents to ARC on behalf of Chrome.
// Deprecated method ID: 0, 7, 11, 12, 14, 18
// Next method ID: 22
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);

  // Sets the given package as a preferred app for the given |intent_filter|
  // and |intent_info|.
  // The |package_name| is selected by the user on Chrome-side to remember the
  // user preference. The |intent_info| is used to generate the components set
  // and match for setting the preferred activity.
  // This is used to sync the preferred app setting from Chrome OS.
  [MinVersion=32] AddPreferredApp@17(string package_name,
                                     IntentFilter intent_filter,
                                     IntentInfo intent_info);

  // 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();
};