chromeos/services/multidevice_setup/public/mojom/multidevice_setup.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 chromeos.multidevice_setup.mojom;

import "chromeos/components/multidevice/mojom/multidevice_types.mojom";

// Enumeration of event types which can be dispatched. Only used for debugging
// purposes.
enum EventTypeForDebugging {
  kNewUserPotentialHostExists,
  kExistingUserConnectedHostSwitched,
  kExistingUserNewChromebookAdded,
};

// This enum is tied directly to a UMA enum defined in
// //tools/metrics/histograms/enums.xml, and should always reflect it (do not
// change one without changing the other).
enum HostStatus {
  // The user's account has no devices which can serve as a host for
  // multi-device features.
  kNoEligibleHosts = 0,

  // The user's account has one or more devices which can be used as a host for
  // multi-device features, but the user has not yet completed the setup flow
  // for any one of these devices.
  kEligibleHostExistsButNoHostSet = 1,

  // The user has completed the setup flow for multi-device features on this
  // device, but there was an error contacting the back-end (e.g., the device
  // was offline during the setup flow, or the back-end rejected the request for
  // some reason). The local device will continue trying to contact the back-end
  // to confirm that the host is set.
  kHostSetLocallyButWaitingForBackendConfirmation = 2,

  // The host has been set (both locally and on the back-end), but verification
  // has not yet completed. The local device will continue trying to establish
  // a Bluetooth connection to the host until verification succeeds.
  kHostSetButNotYetVerified = 3,

  // The host has been set (both locally and on the back-end), and the
  // verification step over Bluetooth has completed. Features should be
  // available for use.
  kHostVerified = 4
};

// Individual multi-device features types.
enum Feature {
  kBetterTogetherSuite,
  kInstantTethering,
  kMessages,
  kSmartLock
};

// This enum is tied directly to a UMA enum defined in
// //tools/metrics/histograms/enums.xml, and should always reflect it (do not
// change one without changing the other).
enum FeatureState {
  // Feature was prohibited by a device policy (e.g., EDU or Enterprise).
  kProhibitedByPolicy = 0,

  // Feature was disabled by the user (i.e., via settings).
  kDisabledByUser = 1,

  // Feature was enabled by the user (i.e., via settings).
  kEnabledByUser = 2,

  // Feature is not supported by this Chromebook.
  kNotSupportedByChromebook = 3,

  // Feature is not supported by the current host phone device.
  kNotSupportedByPhone = 4,

  // The feature is unavailable because there is no verified multi-device host.
  // To set a host, use SetHostDevice(); to verify a host, use
  // RetrySetHostNow().
  kUnavailableNoVerifiedHost = 5,

  // The feature is unavailable because there are insufficient security
  // mechanisms in place (e.g., Smart Lock returns this value when the host
  // phone device does not have a lock screen set).
  kUnavailableInsufficientSecurity = 6,

  // The feature has been enabled by the user, but it is still unavailable
  // because the entire Better Together suite has been disabled by the user.
  kUnavailableSuiteDisabled = 7,

  // The feature still requires further setup to be ready for use (e.g., Android
  // Messages requires a separate pairing flow after unified setup).
  kFurtherSetupRequired = 8,
};

interface AccountStatusChangeDelegate {
  // Callback which indicates that one or more MultiDevice host phones are
  // available for setup with the MultiDevice setup flow. This function is only
  // called if the current user has not yet set up MultiDevice features.
  OnPotentialHostExistsForNewUser();

  // Callback which indicates that the account left the state of having a
  // potential host ready for setup. Note that it is called both when a host is
  // set and when there are simply no host devices (i.e. neither potential nor
  // set) on the account anymore. This function is only called if the current
  // user has not yet set up MultiDevice features and received backend
  // confirmation.
  OnNoLongerNewUser();

  // Callback which indicates that the currently-connected MultiDevice host has
  // changed. This likely means that the user has changed MultiDevice settings
  // on another device. This function is only called if the current user has
  // already set up MultiDevice features.
  OnConnectedHostSwitchedForExistingUser(string new_host_device_name);

  // Callback which indicates that a new Chromebook was added to the account of
  // the current user. This function is only called if the current user has
  // already set up MultiDevice features.
  OnNewChromebookAddedForExistingUser(string new_host_device_name);
};

interface HostStatusObserver {
  // Called whenever the host status changes. If the host status is
  // HostStatus::kNoEligibleHosts or
  // HostStatus::kEligibleHostExistsButNoHostSet, |host_device| is null.
  OnHostStatusChanged(HostStatus host_status,
                      chromeos.multidevice.mojom.RemoteDevice? host_device);
};

interface FeatureStateObserver {
  // Invoked when one or more features have changed state.
  OnFeatureStatesChanged(map<Feature, FeatureState> feature_states_map);
};

// Provides an API to the MultiDevice Setup flow. Designed to be exposed
// primarily to the MultiDevice setup flow at chrome://multidevice-setup and
// chrome://oobe (normal usage) as well as the ProximityAuth debug WebUI page at
// chrome://proximity-auth (debugging only).
interface MultiDeviceSetup {
  // Registers the "account status change" delegate to be used by the service.
  // Only one delegate can be set; this function should not be called more than
  // once.
  SetAccountStatusChangeDelegate(AccountStatusChangeDelegate delegate);

  // Adds an observer of host status changes. To stop observing, disconnect the
  // HostStatusObserverPtr passed here.
  AddHostStatusObserver(HostStatusObserver observer);

  // Adds an observer of feature state changes. To stop observing, disconnect
  // the FeatureStateObserverPtr passed here.
  AddFeatureStateObserver(FeatureStateObserver observer);

  // Provides a list of all eligible host devices (i.e., those which can be
  // passed to SetHostDevice()).
  GetEligibleHostDevices() =>
      (array<chromeos.multidevice.mojom.RemoteDevice> eligible_host_devices);

  // Sets the host associated with the provided device ID as the host device
  // for this account. The provided auth token must be valid in order to prove
  // that the user is authenticated. If called when there is no current host or
  // when the current host is a different device from the one passed, this
  // function initiates a connection to the back-end and attempts to set the
  // host. When called with the same device that is already the host, this
  // function is a no-op. Returns a success boolean; this function will fail if
  // the provided device ID does not correspond to an eligible host device on
  // the account, or the provided auth token is invalid.
  SetHostDevice(string device_id, string auth_token) => (bool success);

  // Removes the currently-set host as the multi-device host for this account.
  // If there was no host set to begin with, this function is a no-op.
  RemoveHostDevice();

  // Returns the host status and host device. If the host status is
  // HostStatus::kNoEligibleHosts or
  // HostStatus::kEligibleHostExistsButNoHostSet, |host_device| is null.
  GetHostStatus() => (HostStatus host_status,
                      chromeos.multidevice.mojom.RemoteDevice? host_device);

  // Attempts to enable or disable |feature|. This function succeeds only if
  // |feature|'s current state is FeatureState::kEnabledByUser or
  // FeatureState::kDisabledByUser.
  //
  // A valid |auth_token| only needs to be provided if Smart Lock is being
  // enabled. To be exact, this means a valid |auth_token| must be passed if
  // |feature| == EASY_UNLOCK_CLIENT and |enabled| == true, or
  // |feature| == BETTER_TOGETHER_CLIENT, |enabled| == true, and the pref for
  // Smart Lock is already enabled.
  SetFeatureEnabledState(Feature feature, bool enabled, string? auth_token) =>
      (bool success);

  // Provides the states of all Features.
  GetFeatureStates() => (map<Feature, FeatureState> feature_states_map);

  // Retries the most recent SetHostDevice() call.
  //
  // If the current status is
  // HostStatus::kHostSetLocallyButWaitingForBackendConfirmation, this function
  // retries the network attempt to set the device on the back-end. If the
  // current status is HostStatus::kHostSetButNotYetVerified, this function
  // retries the verification step. Both of these cases return true to the
  // caller.
  //
  // If the current status is any other value, this function is not applicable,
  // and false is returned to the caller.
  RetrySetHostNow() => (bool success);

  // Triggers an event to be dispatched by the service. This API function is
  // intended to be used only for debugging in the chrome://proximity-auth page.
  // During normal usage, events are triggered internally within the service.
  TriggerEventForDebugging(EventTypeForDebugging type) => (bool success);
};

// Provides an API for setting a MultiDevice host without the need to provide an
// auth token. This interface should only be used in circumstances when the user
// has just entered their password.
interface PrivilegedHostDeviceSetter {
  // Same functionality as MultiDeviceSetup's SetHostDevice() function above,
  // except that no auth token is required.
  SetHostDevice(string device_id) => (bool success);
};