chrome/common/mac/app_shim.mojom

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

module chrome.mojom;

import "chrome/services/mac_notifications/public/mojom/mac_notifications.mojom";
import "components/remote_cocoa/common/application.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "ui/gfx/image/mojom/image.mojom";
import "url/mojom/url.mojom";
import "components/metrics/public/mojom/histogram_fetcher.mojom";

enum AppShimLaunchType {
  // Process the app shim's LaunchAppmessage and associate the shim with the
  // given profile and app id.
  kRegisterOnly,
  // Do the above and launch the app.
  kNormal,
  // Like `kRegisterOnly`, but also process notification actions.
  kNotificationAction,
};

enum AppShimLaunchResult {
  // App launched successfully.
  kSuccess,
  // The app launched successfully, but is not using a host (e.g, is an
  // open-in-a-tab bookmark app), or the host has closed.
  kSuccessAndDisconnect,
  // There is already a host registered for this app.
  kDuplicateHost,
  // The profile was not found.
  kProfileNotFound,
  // The app was not found.
  kAppNotFound,
  // The profile was locked.
  kProfileLocked,
  // The app shim did not pass code signing validation.
  kFailedValidation,
};

enum AppShimAttentionType {
  // Removes any active attention request.
  kCancel,
  // Bounces the shim in the dock continuously.
  kCritical,
};

// Enum describing if the application was launched automatically as a
// 'Login Item' or via Resume.
enum AppShimLoginItemRestoreState {
  // The appilcation as not launched during OS login.
  kNone,
  // The application was launched during OS login.
  kWindowed,
  // The application was launched during OS login, with the
  // 'hide on startup' flag.
  kHidden,
};

enum AppShimScreenReaderSupportMode {
  kPartial,
  kComplete
};

// An entry in the profiles NSMenu.
struct ProfileMenuItem {
  // The name to display.
  mojo_base.mojom.String16 name;

  // The icon to display next to the name.
  gfx.mojom.ImageSkia? icon;

  // The index used to look up this item when selected.
  uint32 menu_index;

  // Whether or not this menu item is listed as selected.
  bool active;

  // The profile path to associate with this item.
  mojo_base.mojom.FilePath profile_path;
};

// An entry in the application dock NSMenu.
struct ApplicationDockMenuItem {
  // The name to display.
  mojo_base.mojom.String16 name;

  // The URL to launch when this item is selected.
  url.mojom.Url url;
};

// Interface through which the browser communicates to a shim process.
interface AppShim {
  // Create the interface to the NSApplication (through which NSViews and
  // NSWindows may be created).
  CreateRemoteCocoaApplication(
      pending_associated_receiver<remote_cocoa.mojom.Application> application);

  // Initialize the command handler for the specified BridgedNativeWidget. This
  // method exists at this scope (as opposed to in remote_cocoa) because it
  // creates chrome-scoped objects that implement remote_cocoa interfaces.
  CreateCommandDispatcherForWidget(uint64 widget_id);

  // Instructs the shim to request or cancel user attention.
  SetUserAttention(AppShimAttentionType attention_type);

  // Instructs the shim to set its badge label.
  SetBadgeLabel(string badge_label);

  // Called to update the state of the profiles NSMenu.
  UpdateProfileMenu(array<ProfileMenuItem> profile_menu_items);

  // Called to update the state of the application dock menu.
  UpdateApplicationDockMenu(array<ApplicationDockMenuItem> dock_menu_items);

  // Called from the browser process to connect to an app-scoped
  // NotificationProvider implementation. Calling this again will disconnect
  // the original notification provider connection.
  BindNotificationProvider(
      pending_receiver<mac_notifications.mojom.MacNotificationProvider> provider);

  // Requests notification permissions from the system. This will ask the user
  // to accept permissions if not granted or denied already.
  RequestNotificationPermission()
      => (mac_notifications.mojom.RequestPermissionResult result);

  // Called to connect to a ChildHistogramFetcherFactory, to allow chrome to
  // fetch histogram data from the app shim.
  BindChildHistogramFetcherFactory(
      pending_receiver<metrics.mojom.ChildHistogramFetcherFactory> receiver);
};

// Interface through which the a process communicates to the browser process.
interface AppShimHost {
  // Sent when the user has indicated a desire to focus the app, either by
  // clicking on the app's icon in the dock or by selecting it with Cmd+Tab.
  FocusApp();

  // Sent when the application should launch if needed (e.g, when the dock
  // icon is clicked).
  ReopenApp();

  // Sent when files are opened by the app (e.g, by opening in Finder, or by
  // dragging on to the app in the dock).
  FilesOpened(array<mojo_base.mojom.FilePath> files);

  // Called when a profile is selected from the profiles menu.
  ProfileSelectedFromMenu(mojo_base.mojom.FilePath profile_path);

  // Called when settings is opened from the app menu while no browser windows
  // are open.
  OpenAppSettings();

  // Sent when urls are opened by the app (e.g. clicking a link in mail)
  UrlsOpened(array<url.mojom.Url> urls);

  // Sent when the app should be opened with an override url (e.g.
  // user clicks on an item in the application dock menu).
  OpenAppWithOverrideUrl(url.mojom.Url override_url);

  // Sent when the user activates some mode of Assistive Technology.
  EnableAccessibilitySupport(AppShimScreenReaderSupportMode mode);

  // Sent when the app is about to terminate. Used to persist what profiles
  // where open when the app was terminated.
  ApplicationWillTerminate();

  // Sent any time the app detects a change in the status of its (system level)
  // notification permission. Also sent shortly after startup.
  NotificationPermissionStatusChanged(
      mac_notifications.mojom.PermissionStatus status);
};

// Properties of an app shim that are specified when it connects to the browser
// process for the first time.
struct AppShimInfo {
  // The path of the profile to use with this app.
  mojo_base.mojom.FilePath profile_path;

  // The shim's app id.
  string app_id;

  // The shortcut URL for this app (if this is a shortcut app or a PWA).
  url.mojom.Url app_url;

  // How or if the browser should launch the associated app in response to this
  // shim process connecting.
  AppShimLaunchType launch_type;

  // The files that were dragged on to this app when launching it.
  array<mojo_base.mojom.FilePath> files;

  // Indicates if the app launched during OS login.
  AppShimLoginItemRestoreState login_item_restore_state;

  // The urls that are to be opened by this app.
  array<url.mojom.Url> urls;

  // Interface that will be used by the app shim to inform the browser process
  // of any notification actions taken. Note that this is included even when
  // the notification attribution feature is disabled; it is ignored by the
  // browser process in that case.
  pending_receiver<mac_notifications.mojom.MacNotificationActionHandler>
      notification_action_handler;
};

// Struct used to pass the state of features and field trials from the browser
// process to app shims when a connection is established between the two.
// This corresponds to the C++ `variations::VariationsCommandLine` struct.
// These fields are passed as strings, in the same format as when these would
// be passed over the command line, as that is the format that is supported
// by `base::FieldTrialList` and `base::FeatureList` for serialization and
// deserialization.
struct FeatureState {
  string field_trial_states;
  string field_trial_params;
  string enable_features;
  string disable_features;
};

// The initial interface provided by the browser process. Used to bootstrap to
// the AppShim and AppShimHost interfaces.
interface AppShimHostBootstrap {
  // Signals to the main Chrome process that a shim has started. The app shim
  // process is requesting to be associated with the given profile and app_id.
  // Once the profile and app_id are stored, and all future messages from the
  // app shim relate to this app.
  OnShimConnected(
      pending_receiver<AppShimHost> host_receiver, AppShimInfo app_shim_info)
      => (AppShimLaunchResult launch_result,
          FeatureState feature_state,
          pending_receiver<AppShim> app_shim_receiver);
};