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

module device.mojom;

// Types of supported sensors
// When adding new sensor type, update the documentation of sensor data values
// in SensorReading struct at sensor_reading.h file.
enum SensorType {
  FIRST = 1,
  AMBIENT_LIGHT = FIRST,
  PROXIMITY,
  ACCELEROMETER,
  LINEAR_ACCELERATION,
  GYROSCOPE,
  MAGNETOMETER,
  PRESSURE,
  // Legacy sensor to support the W3C DeviceOrientation Event Specification.
  ABSOLUTE_ORIENTATION_EULER_ANGLES,
  // Recommended for new code.
  ABSOLUTE_ORIENTATION_QUATERNION,
  // Legacy sensor to support the W3C DeviceOrientation Event Specification.
  RELATIVE_ORIENTATION_EULER_ANGLES,
  // Recommended for new code.
  RELATIVE_ORIENTATION_QUATERNION,
  LAST = RELATIVE_ORIENTATION_QUATERNION // Note: LAST is also equal to the types count.
};

// Reporting mode supported by the Sensor.
// ON_CHANGE  - client will be notified through OnSensorReadingChanged() signal
//              whenever sensor reading is changed.
// CONTINUOUS - sensor will continuously update its reading with frequency
//              specified in SensorConfiguration.frequency.
//              OnSensorReadingChanged() signal is not sent to the client for
//              sensors with CONTINUOUS reporting mode.
enum ReportingMode {
  ON_CHANGE,
  CONTINUOUS
};

struct SensorConfiguration {
  // Requested frequency in Hz.
  double frequency;
  // TODO(shalamov): Add map<string, union> for sensor specific configuration.
};

// Interface for controlling the Sensor.
interface Sensor {

  // Requests sensor to provide its default configuration.
  GetDefaultConfiguration() => (SensorConfiguration configuration);

  // Requests sensor to start reading sensor data with specified
  // SensorConfiguration.
  // Sensor holds the list of added configurations and it always polls
  // the platform (and updates the shared buffer) at the maxiumum frequency
  // among the obtained from the stored configurations, so that all clients
  // can have sensor data in time.
  // Returns 'true' if |configuration| was successfully added.
  // Returns 'false' if |configuration| could not be added (is invalid
  // or not supported).
  AddConfiguration(SensorConfiguration configuration) => (bool success);

  // Requests sensor to stop reading sensor data for specified
  // SensorConfiguration.
  // This call excludes |configuration| from the Sensor's list making it
  // reconsider the the shared buffer udpate frequency. If there are no
  // configurations left in the Sensor's configuration list it stops polling
  // sensor data from the platform and update the shared buffer.
  // If |configuration| is not present in the Sensor's list the call is
  // ignored.
  RemoveConfiguration(SensorConfiguration configuration);

  // Temporary suppresses sensor reading changes notification and deactivates
  // all the previously added configurations for current instance.
  Suspend();

  // Resumes previously suspended sensor reading changes notification and
  // activates all the previously added configurations for current instance.
  Resume();

  // Disables or enables reading change notification for sensors with ON_CHANGE
  // reporting mode, keeping all the previously added configurations active.
  // Reading change notification is enabled by default.
  ConfigureReadingChangeNotifications(bool enabled);
};

// Interface that client of the Sensor interface must implement to observe
// sensor reading changes and error conditions.
interface SensorClient {
  // Signals SensorClient when there is an error.
  RaiseError();

  // Signals SensorClient when reading has been changed (only for sensors with
  // ReportingMode::ON_CHANGE).
  SensorReadingChanged();
};