blob: bfa2b422ac3ec9fe06cc149ffb0aec30dc54e3ad [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;
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() -> (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.
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.
RemovePolicy(struct {
policy_id PolicyId;
}) -> (struct {}) 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;
};