sdk/fidl/fuchsia.settings.policy/volume_policy.fidl

// 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]
protocol VolumePolicyController {
    /// Gets a list of volume policy properties, including possible transforms
    /// and active policies for the property.
    GetProperties() -> (vector<Property>:MAX properties);

    /// 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.
    AddPolicy(Target target, PolicyParameters parameters) -> (PolicyId policy_id) error Error;

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

/// A controllable property of the fuchsia.settings.Audio API that can have
/// transforms applied to it.
table Property {
    /// 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: vector<Transform>:MAX available_transforms;

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

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

/// 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.
enum Transform : 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.
table Policy {
    /// Unique identifier for this policy.
    ///
    /// Returned from AddPolicy and also used by RemovePolicy.
    1: PolicyId policy_id;

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

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

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

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