// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.settings;

/// Settings related to input to the device.
///
/// Supported SettingsEpitaph enums:
/// REQUEST_NOT_SUPPORTED, INTERNAL_SERVICE_ERROR, PERSISTENT_STORAGE_ERROR
@discoverable
protocol Input {
    /// Gets the current |InputSettings|. Returns immediately on first call;
    /// subsequent calls return when the value changes.
    ///
    /// When any of the input devices' states change, this will return the
    /// full [InputSettings] object, containing the states for all the
    /// available input devices on the target device.
    ///
    /// To find the state of a specific input device, the devices vector
    /// contained in settings can be iterated through to find a specific
    /// [DeviceType]. If there are multiple devices of the same [DeviceType],
    /// the [InputDevice]'s device_name can be examined in conjunction with
    /// the [DeviceType] to find the desired input device. Together, the
    /// device_name and [DeviceType] uniquely identify an [InputDevice].
    ///
    /// If this call fails, it is considered a fatal error and the channel
    /// will be closed.
    @transitional("Future replacement for Watch2")
    Watch() -> (struct {
        settings InputSettings;
    });

    /// Requests software input devices to set their software state. May
    /// not necessarily change the overall state of the device, depending on
    /// the hardware state. Will modify the software state of the existing
    /// device if a known device_name and device_type are passed. Otherwise
    /// it will add a new input device. Devices not included in the SetStates
    /// call will not be modified.
    @transitional("Future replacement for SetStates")
    Set(struct {
        input_states vector<InputState>:MAX;
    }) -> (struct {}) error Error;

    /// Gets the current |InputSettings|. Returns immediately on first call;
    /// subsequent calls return when the value changes.
    ///
    /// When any of the input devices' states change, this will return the
    /// full [InputSettings] object, containing the states for all the
    /// available input devices on the target device.
    ///
    /// To find the state of a specific input device, the devices vector
    /// contained in settings can be iterated through to find a specific
    /// [DeviceType]. If there are multiple devices of the same [DeviceType],
    /// the [InputDevice]'s device_name can be examined in conjunction with
    /// the [DeviceType] to find the desired input device. Together, the
    /// device_name and [DeviceType] uniquely identify an [InputDevice].
    ///
    /// If this call fails, it is considered a fatal error and the channel
    /// will be closed.
    @transitional("Will be deprecated in favor of Watch")
    Watch2() -> (struct {
        settings InputSettings;
    });

    /// Requests software input devices to set their software state. May
    /// not necessarily change the overall state of the device, depending on
    /// the hardware state. Will modify the software state of the existing
    /// device if a known device_name and device_type are passed. Otherwise
    /// it will add a new input device. Devices not included in the SetStates
    /// call will not be modified.
    @transitional("Will be deprecated in favor of Set")
    SetStates(struct {
        input_states vector<InputState>:MAX;
    }) -> (struct {}) error Error;
};

/// A series of flags determining the state of an input device mute toggle.
type ToggleStateFlags = strict bits : uint64 {
    /// The input device exists and is neither muted nor disabled.
    AVAILABLE = 0x01;
    /// The input device is being used.
    ACTIVE = 0x02;
    /// The input device could be available if it was enabled, but it is muted.
    MUTED = 0x04;
    /// The input device is permanently disabled, e.g. by policy.
    DISABLED = 0x08;
    /// The state cannot be determined.
    ERROR = 0x10;
};

type DeviceType = strict enum {
    MICROPHONE = 1;
    CAMERA = 2;
};

type DeviceStateSource = strict enum {
    HARDWARE = 1;
    SOFTWARE = 2;
};

/// Settings related to device input. New format for InputDeviceSettings.
///
/// InputSettings contains a list of input devices, e.g. Microphone and Camera
/// devices. There may be multiple devices of each type. If so, they will be
/// differentiated by the device_name. If there is only one device of a certain
/// [DeviceType], then the name defaults to the same as the device type, e.g.
/// DeviceType::Microphone -> "microphone".
type InputSettings = table {
    1: devices vector<InputDevice>:MAX;
};

/// Contains the information for an input device. The device is uniquely identified
/// by the combination of device_name and device_type.
type InputDevice = table {
    /// Uniquely identifies a device within a device type.
    1: device_name string:MAX;
    /// The type of input device (e.g. camera, microphone).
    2: device_type DeviceType;
    /// The state for each individual [DeviceStateSource].
    3: source_states vector<SourceState>:MAX;
    /// The software toggle states which are allowed to be changed for a device.
    4: mutable_toggle_state ToggleStateFlags;
    /// The overall state of the device, considering the combination
    /// of the source states.
    5: state DeviceState;
};

/// Holds the state for an |InputDevice|.
type DeviceState = table {
    /// Controls the on/off state of the input device.
    1: toggle_flags ToggleStateFlags;
};

/// Describes what the |source|'s |state| is.
type SourceState = table {
    1: source DeviceStateSource;
    2: state DeviceState;
};

/// A subset of |DeviceState|'s properties that clients may pass to change the
/// software state of an InputDevice.
type InputState = table {
    1: name string:MAX;
    2: device_type DeviceType;
    3: state DeviceState;
};