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

using fuchsia.media;

alias PolicyId = uint32;

/// Provides access to enumerating and modifying policies for the
/// fuchsia.settings.Audio API.
///
/// Policies are automatically persisted across reboots and take effect again on
/// boot.
@discoverable
@available(deprecated=11, removed=12)
closed protocol VolumePolicyController {
    /// Gets a list of volume policy properties, including possible transforms
    /// and active policies for the property.
    strict GetProperties() -> (struct {
        properties vector<Property>:MAX;
    });

    /// Adds a policy for the given target.
    ///
    /// Returns a policy_id for the added policy, which can be used to remove
    /// the policy with RemovePolicy.
    ///
    /// If the policy being added contradicts an existing policy, the add
    /// call will return an error. An example would be specifying a max volume
    /// for a stream that is lower than an existing min volume.
    ///
    /// If the transform specified in the PolicyParameters is not enumerated in
    /// the available_transforms of the policy property, the connection will be
    /// closed.
    ///
    /// Adding a policy will immediately adjust the audio setting values if they
    /// don't yet conform to the policy, such as reducing the volume if it's
    /// greater than a specified maximum volume.
    strict AddPolicy(struct {
        target Target;
        parameters PolicyParameters;
    }) -> (struct {
        policy_id PolicyId;
    }) error Error;

    /// Removes a policy with the given policy id.
    ///
    /// Any client of this API can remove policies set by any other client.
    strict RemovePolicy(struct {
        policy_id PolicyId;
    }) -> () error Error;
};

/// A controllable property of the fuchsia.settings.Audio API that can have
/// transforms applied to it.
type Property = table {
    /// Unique aspect of settings that this property controls.
    ///
    /// Only one property may control any given target.
    1: target Target;

    /// List of available transform types for this property.
    2: available_transforms vector<Transform>:MAX;

    /// List of active policies for this property.
    3: active_policies vector<Policy>:MAX;
};

/// Specifies what aspect of the settings a property controls.
type Target = strict union {
    /// An audio stream that can have policies applied to it.
    1: stream fuchsia.media.AudioRenderUsage;
};

/// Possible transforms for a policy target.
///
/// A transform is an operation that is applied to a policy property when the
/// fuchsia.settings.Audio API is used. Multiple transforms of the same time can
/// be active for a single property.
type Transform = strict enum : uint8 {
    /// Limits the maximum value of an audio stream to a certain level.
    ///
    /// Max volume limits are transparent to clients of fuchsia.settings.Audio.
    /// Clients will always be able to set the volume to 1.0 (max) to prevent
    /// user confusion about not being able to set the volume to max. The
    /// internal volume, which is communicated to AudioCore to set the true
    /// volume level, will always be clamped to the specified maximum.
    ///
    /// Externally, the volume percentage will always be a percentage of the max
    /// allowed by policy. For example, if the max limit is set to 0.8, a client
    /// setting the volume to 1.0 translates to 0.8 internally. An external
    /// volume of 0.5 would be scaled to 0.4 internally.
    ///
    /// If a min volume limit is present, the minimum external volume will be
    /// the min volume limit divided by the max volume limit. For example, if
    /// the max volume limit is 0.8 and the min volume limit is 0.2, the lowest
    /// possible external volume is 0.25, since 0.2 is 25% of 0.8. The min range
    /// is not transparent to clients to prevent the confusion of volume being
    /// at 0% but still being able to hear audio.
    MAX = 1;

    /// Limits the minimum value of an audio stream to a certain level.
    ///
    /// If the volume is below the specified minimum level when the policy is
    /// added, it will automatically be raised to the specified minimum. Calls
    /// to set the volume below the minimum level will not fail, but the actual
    /// volume will stay above the specified minimum level.
    ///
    /// Note that the minimum volume limit is a limit on the internal "true"
    /// volume level. If a maximum volume policy is set, the minimum that
    /// clients of fuchsia.settings.Audio will see is higher. See the
    /// documentation of the MAX volume transform for more information.
    MIN = 2;
};

/// Definition for a policy that is applied to the fuchsia.settings.Audio API.
type Policy = table {
    /// Unique identifier for this policy.
    ///
    /// Returned from AddPolicy and also used by RemovePolicy.
    1: policy_id PolicyId;

    /// Parameters for this policy.
    2: parameters PolicyParameters;
};

/// Specifies the type of policy transform and its arguments.
///
/// The chosen union field implies the type of transform that the arguments
/// apply to.
type PolicyParameters = strict union {
    /// This parameter should be included for the MIN transform and specifies
    /// the volume level to clamp the audio stream to.
    1: min Volume;

    /// This parameter should be included for the MAX transform and specifies
    /// the volume level to clamp the audio stream to.
    2: max Volume;
};

type Volume = table {
    /// A volume between 0.0 and 1.0 inclusive.
    1: volume float32;
};