// Copyright 2020 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 min version: 1

module cros.mojom;

enum DeviceType {
  NONE = 0,  // invalid device type
  ACCEL = 1,
  ANGLVEL = 2,
  LIGHT = 3,
  COUNT = 4,
  MAGN = 5,
  ANGL = 6,
  ACPI_ALS = 7,
  BARO = 8,
  MAX = 9,
};

enum ObserverErrorType {
  ALREADY_STARTED = 0,
  SET_FREQUENCY_IO_FAILED = 1,
  FREQUENCY_INVALID = 2,
  NO_ENABLED_CHANNELS = 3,
  GET_FD_FAILED = 4,
  READ_FAILED = 5,
  READ_TIMEOUT = 6,
};

// SensorService, an interface to search and get SensorDevices. A User can get
// multiple isolated SensorDevices for one physical device, if it wants
// different frequencies of that device's samples.
//
// Next method ID: 3
interface SensorService {
  // Gets device ids as a vector of int given the device's type. Only devices
  // with id having "iio:device" as the prefix would be available.
  // Gets an empty vector if no device can be found.
  GetDeviceIds@0(DeviceType type) => (array<int32> iio_device_ids);

  // Gets all device ids and their types. Only devices with id having
  // "iio:device" as the prefix would be available. For combo sensors, there are
  // multiple types in the array of types.
  // Gets an empty vector if no device can be found.
  GetAllDeviceIds@1() => (map<int32, array<DeviceType>> iio_device_ids_types);

  // Creates a new Mojo channel to the iioservice as an isolated client. Upon
  // successfully binding of |device_request|, the caller will have an
  // established Mojo channel to iioservice.
  // If failed, the request won't be bound and will be destroyed directly.
  GetDevice@2(int32 iio_device_id, pending_receiver<SensorDevice> device_request);
};

// SensorDevice, an interface sending requests for a physical device
// (libiio:iio_device). It is an isolated client in iioservice's point of view.
//
// Next method ID: 9
interface SensorDevice {
  // Sets |timeout| in milliseconds for I/O operations, mainly for reading
  // samples. Sets |timeout| as 0 to specify that no timeout should occur.
  // Default: 5000 milliseconds.
  SetTimeout@0(uint32 timeout);

  // Gets the |attr_name| attribute of this device into |value| in string.
  // Returns base::nullopt if the attribute cannot be read.
  GetAttribute@1(string attr_name) => (string? value);

  // Sets the frequency in Hz of the device before starting to read samples.
  // If no frequency or an invalid frequency is set, an
  // ObserverErrorType::FREQUENCY_INVALID error will occur after calling
  // |StartReadingSamples|.
  // After starting to read samples, the client can set the frequency to 0 to
  // pause the reading, and set a valid frequency later to resume the reading.
  // |result_freq| would be the frequency set by iioservice for the client.
  SetFrequency@2(double frequency) => (double result_freq);

  // Starts reading samples with the frequency set by |SetFrequency|. Samples or
  // errors will be pushed to the observer. It's the user's responsibility to
  // keep |observer| active while reading.
  StartReadingSamples@3(pending_remote<SensorDeviceSamplesObserver> observer);

  // Stops reading samples in this device. Reading can be restarted by calling
  // |StartReadingSamples| again.
  StopReadingSamples@4();

  // Gets all channels' ids as a vector of string. The ids are ordered and the
  // user should use the indices of channels to send further requests and
  // receive samples.
  GetAllChannelIds@5() => (array<string> iio_chn_ids);

  // Sets channels' enabled status to |en| with channel indices
  // |iio_chn_indices|. Returns an array of channel indices |failed_indices| if
  // there are some invalid or duplicate indices.
  SetChannelsEnabled @6(array<int32> iio_chn_indices, bool en)
    => (array<int32> failed_indices);

  // Returns an array of bool indicating if channels are enabled.
  GetChannelsEnabled@7(array<int32> iio_chn_indices) => (array<bool> enabled);

  // Gets the |attr_name| attribute of channels as a group into |values| in
  // string.
  // Returns base::nullopt if the attribute in the channel cannot be read.
  GetChannelsAttributes@8(array<int32> iio_chn_indices, string attr_name)
    => (array<string?> values);
};

// One observer is created to track one specific device's samples, using
// SensorDevice::StartReadingSamples to register the observer.
//
// Next method ID: 2
interface SensorDeviceSamplesObserver {
  // |sample| arrives and is sent to the client as a map from iio_chn_indices to
  // data (64 bit integer).
  OnSampleUpdated@0(map<int32, int64> sample);

  // An error occurs and is sent to the client as an enum type.
  OnErrorOccurred@1(ObserverErrorType type);
};