1/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#pragma once
18
19#include <AudioPolicyManagerObserver.h>
20#include <RoutingStrategy.h>
21#include <Volume.h>
22#include <HwModule.h>
23#include <DeviceDescriptor.h>
24#include <system/audio.h>
25#include <system/audio_policy.h>
26#include <utils/Errors.h>
27#include <utils/Vector.h>
28
29namespace android {
30
31/**
32 * This interface is dedicated to the policy manager that a Policy Engine shall implement.
33 */
34class AudioPolicyManagerInterface
35{
36public:
37    /**
38     * Checks if the engine was correctly initialized.
39     *
40     * @return NO_ERROR if initialization has been done correctly, error code otherwise..
41     */
42    virtual status_t initCheck() = 0;
43
44    /**
45     * Sets the Manager observer that allows the engine to retrieve information on collection
46     * of devices, streams, HwModules, ...
47     *
48     * @param[in] observer handle on the manager.
49     */
50    virtual void setObserver(AudioPolicyManagerObserver *observer) = 0;
51
52    /**
53     * Get the input device selected for a given input source.
54     *
55     * @param[in] inputSource to get the selected input device associated to
56     *
57     * @return selected input device for the given input source, may be none if error.
58     */
59    virtual audio_devices_t getDeviceForInputSource(audio_source_t inputSource) const = 0;
60
61    /**
62     * Get the output device associated to a given strategy.
63     *
64     * @param[in] stream type for which the selected ouput device is requested.
65     *
66     * @return selected ouput device for the given strategy, may be none if error.
67     */
68    virtual audio_devices_t getDeviceForStrategy(routing_strategy stategy) const = 0;
69
70    /**
71     * Get the strategy selected for a given stream type.
72     *
73     * @param[in] stream: for which the selected strategy followed by is requested.
74     *
75     * @return strategy to be followed.
76     */
77    virtual routing_strategy getStrategyForStream(audio_stream_type_t stream) = 0;
78
79    /**
80     * Get the strategy selected for a given usage.
81     *
82     * @param[in] usage to get the selected strategy followed by.
83     *
84     * @return strategy to be followed.
85     */
86    virtual routing_strategy getStrategyForUsage(audio_usage_t usage) = 0;
87
88    /**
89     * Set the Telephony Mode.
90     *
91     * @param[in] mode: Android Phone state (normal, ringtone, csv, in communication)
92     *
93     * @return NO_ERROR if Telephony Mode set correctly, error code otherwise.
94     */
95    virtual status_t setPhoneState(audio_mode_t mode) = 0;
96
97    /**
98     * Get the telephony Mode
99     *
100     * @return the current telephony mode
101     */
102    virtual audio_mode_t getPhoneState() const = 0;
103
104    /**
105     * Set Force Use config for a given usage.
106     *
107     * @param[in] usage for which a configuration shall be forced.
108     * @param[in] config wished to be forced for the given usage.
109     *
110     * @return NO_ERROR if the Force Use config was set correctly, error code otherwise (e.g. config
111     * not allowed a given usage...)
112     */
113    virtual status_t setForceUse(audio_policy_force_use_t usage,
114                                 audio_policy_forced_cfg_t config) = 0;
115
116    /**
117     * Get Force Use config for a given usage.
118     *
119     * @param[in] usage for which a configuration shall be forced.
120     *
121     * @return config wished to be forced for the given usage.
122     */
123    virtual audio_policy_forced_cfg_t getForceUse(audio_policy_force_use_t usage) const = 0;
124
125    /**
126     * Set the connection state of device(s).
127     *
128     * @param[in] devDesc for which the state has changed.
129     * @param[in] state of availability of this(these) device(s).
130     *
131     * @return NO_ERROR if devices criterion updated correctly, error code otherwise.
132     */
133    virtual status_t setDeviceConnectionState(const android::sp<android::DeviceDescriptor> devDesc,
134                                              audio_policy_dev_state_t state) = 0;
135
136    /**
137     * Translate a volume index given by the UI to an amplification value in dB for a stream type
138     * and a device category.
139     *
140     * @param[in] deviceCategory for which the conversion is requested.
141     * @param[in] stream type for which the conversion is requested.
142     * @param[in] indexInUi index received from the UI to be translated.
143     *
144     * @return amplification value in dB matching the UI index for this given device and stream.
145     */
146    virtual float volIndexToDb(Volume::device_category deviceCategory, audio_stream_type_t stream,
147                                 int indexInUi) = 0;
148
149    /**
150     * Initialize the min / max index of volume applicable for a given stream type. These indexes
151     * will be used upon conversion of UI index to volume amplification.
152     *
153     * @param[in] stream type for which the indexes need to be set
154     * @param[in] indexMin Minimum index allowed for this stream.
155     * @param[in] indexMax Maximum index allowed for this stream.
156     */
157    virtual status_t initStreamVolume(audio_stream_type_t stream, int indexMin, int indexMax) = 0;
158
159    /**
160     * Initialize volume curves for each strategy and device category
161     *
162     * @param[in] isSpeakerDrcEnabled true on devices that use DRC on the DEVICE_CATEGORY_SPEAKER
163                  path to boost soft sounds, used to adjust volume curves accordingly
164     */
165    virtual void initializeVolumeCurves(bool isSpeakerDrcEnabled) = 0;
166
167protected:
168    virtual ~AudioPolicyManagerInterface() {}
169};
170
171}; // namespace android
172