chromeos/services/device_sync/public/mojom/device_sync.mojom

// Copyright 2017 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.device_sync.mojom;

import "chromeos/components/multidevice/mojom/multidevice_types.mojom";
import "mojo/public/mojom/base/time.mojom";

enum NetworkRequestResult {
  // Successful network request.
  kSuccess,

  // The network request itself was successful, but it did not produce the
  // expected result (e.g., called SetSoftwareFeatureState(), but the call did
  // not result in the feature state changing).
  kRequestSucceededButUnexpectedResult,

  // Service was not yet initialized; could not complete request.
  kServiceNotYetInitialized,

  // Request could not be completed because the device is offline or has issues
  // sending the HTTP request.
  kOffline,

  // Server endpoint could not be found.
  kEndpointNotFound,

  // Authentication error contacting back-end.
  kAuthenticationError,

  // Request was invalid.
  kBadRequest,

  // The server responded, but the response was not formatted correctly.
  kResponseMalformed,

  // Internal server error.
  kInternalServerError,

  // Unknown result.
  kUnknown
};

struct FindEligibleDevicesResponse {
  array<chromeos.multidevice.mojom.RemoteDevice> eligible_devices;
  array<chromeos.multidevice.mojom.RemoteDevice> ineligible_devices;
};

struct DebugInfo {
  // Enrollment stats:
  mojo_base.mojom.Time last_enrollment_time;
  mojo_base.mojom.TimeDelta time_to_next_enrollment_attempt;
  bool is_recovering_from_enrollment_failure;
  bool is_enrollment_in_progress;

  // Sync stats:
  mojo_base.mojom.Time last_sync_time;
  mojo_base.mojom.TimeDelta time_to_next_sync_attempt;
  bool is_recovering_from_sync_failure;
  bool is_sync_in_progress;
};

interface DeviceSyncObserver {
  // Invoked when the current device has successfully completed enrollment. Note
  // that enrollment occurs once when the device first starts up, then the
  // device re-enrolls periodically (and on-command when ForceEnrollmentNow() is
  // called).
  OnEnrollmentFinished();

  // Invoked when new devices have been synced from the server. Note that this
  // function is not invoked if a device sync failed or if a device sync
  // succeeded but did not result in a change of devices.
  OnNewDevicesSynced();
};

// TODO(khorimoto): Flesh out API.
interface DeviceSync {
  // Adds an Observer of this API.
  AddObserver(DeviceSyncObserver observer) => ();

  // Triggers an enrollment; result is relayed via the OnEnrollmentFinished()
  // observer function. Returns whether the call could be completed
  // successfully. If the function returns false, this means that the device has
  // not yet completed registration with the back-end; clients should observe
  // this service and wait for an OnEnrollmentFinished() callback before
  // retrying.
  [Sync]
  ForceEnrollmentNow() => (bool success);

  // Triggers a device sync; result is relayed via the OnDevicesSynced()
  // observer function. Returns whether the call could be completed
  // successfully. If the function returns false, this means that the device has
  // not yet completed registration with the back-end; clients should observe
  // this service and wait for an OnEnrollmentFinished() callback before
  // retrying.
  [Sync]
  ForceSyncNow() => (bool success);

  // Returns all synced devices associated with the primary account. If this
  // device has not yet registered with the back-end, no list is provided.
  GetSyncedDevices() =>
      (array<chromeos.multidevice.mojom.RemoteDevice>? devices);

  // Returns the RemoteDevice object associated with this device. If this device
  // has not yet registered with the back-end, no device is provided.
  GetLocalDeviceMetadata() =>
      (chromeos.multidevice.mojom.RemoteDevice? local_device);

  // Enables or disables the given software feature for the device with the
  // given public key. If |enabled| and |is_exclusive| are both true, this
  // function will enable the feature for the given device and disable the
  // feature for any other device which currently has that feature enabled.
  // |is_exclusive| is ignored if |enabled| is false.
  //
  // On success, this function returns a null error_code to the callback; on
  // error, it returns a valid error_code string indicating the reason for
  // failure.
  //
  // Note: In the special case of passing |software_feature| =
  // SoftwareFeature::EASY_UNLOCK_HOST and |enabled| = false, |public_key| is
  // ignored, because that combination of arguments disables EASY_UNLOCK_HOST on
  // all of the user's devices.
  SetSoftwareFeatureState(
      string device_public_key,
      chromeos.multidevice.mojom.SoftwareFeature software_feature,
      bool enabled,
      bool is_exclusive) => (NetworkRequestResult result_code);

  // Finds devices which are eligible for the given feature. When this function
  // is invoked, a network request will be sent to each eligible device which
  // instructs that device to enable BLE advertising; thus, this function can be
  // used to bootstrap connections to these devices.
  //
  // On success, this function returns a null error_code with a valid response
  // to the callback; on error, it returns a valid error_code string indicating
  // the reason for failure along with a null response.
  FindEligibleDevices(
      chromeos.multidevice.mojom.SoftwareFeature software_feature) =>
          (NetworkRequestResult result_code,
           FindEligibleDevicesResponse? response);

  // Functions below are implemented for chrome://proximity-auth page, which is
  // intended for debugging purposes only.
  // TODO(khorimoto): Determine whether a new, debug-only interface should be
  //                  refactored out of DeviceSync.
  GetDebugInfo() => (DebugInfo? debug_info);
};