| // 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; |
| }; |