blob: 6a91ee2fdee5f95abf472c88f94f9e30e158d1ee [file] [log] [blame]
// 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;
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.
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: 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;