blob: c9e9507705169b343216fe08933b607f2f136f83 [file] [log] [blame]
François Gaffie2110e042015-03-24 08:41:51 +01001/*
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>
François Gaffied0ba9ed2018-11-05 11:50:42 +010020#include <media/AudioProductStrategy.h>
Eric Laurentf5aa58d2019-02-22 18:20:11 -080021#include <IVolumeCurves.h>
François Gaffiedc7553f2018-11-02 10:39:57 +010022#include <policy.h>
François Gaffie2110e042015-03-24 08:41:51 +010023#include <Volume.h>
24#include <HwModule.h>
25#include <DeviceDescriptor.h>
26#include <system/audio.h>
27#include <system/audio_policy.h>
28#include <utils/Errors.h>
29#include <utils/Vector.h>
30
31namespace android {
32
François Gaffiedc7553f2018-11-02 10:39:57 +010033using DeviceStrategyMap = std::map<product_strategy_t, DeviceVector>;
34using StrategyVector = std::vector<product_strategy_t>;
35
36
François Gaffie2110e042015-03-24 08:41:51 +010037/**
38 * This interface is dedicated to the policy manager that a Policy Engine shall implement.
39 */
40class AudioPolicyManagerInterface
41{
42public:
43 /**
44 * Checks if the engine was correctly initialized.
45 *
46 * @return NO_ERROR if initialization has been done correctly, error code otherwise..
47 */
48 virtual status_t initCheck() = 0;
49
50 /**
51 * Sets the Manager observer that allows the engine to retrieve information on collection
52 * of devices, streams, HwModules, ...
53 *
54 * @param[in] observer handle on the manager.
55 */
56 virtual void setObserver(AudioPolicyManagerObserver *observer) = 0;
57
58 /**
François Gaffie2110e042015-03-24 08:41:51 +010059 * Set the Telephony Mode.
60 *
61 * @param[in] mode: Android Phone state (normal, ringtone, csv, in communication)
62 *
63 * @return NO_ERROR if Telephony Mode set correctly, error code otherwise.
64 */
65 virtual status_t setPhoneState(audio_mode_t mode) = 0;
66
67 /**
68 * Get the telephony Mode
69 *
70 * @return the current telephony mode
71 */
72 virtual audio_mode_t getPhoneState() const = 0;
73
74 /**
75 * Set Force Use config for a given usage.
76 *
77 * @param[in] usage for which a configuration shall be forced.
78 * @param[in] config wished to be forced for the given usage.
79 *
François Gaffie20f06f92015-03-24 09:01:14 +010080 * @return NO_ERROR if the Force Use config was set correctly, error code otherwise (e.g. config
81 * not allowed a given usage...)
François Gaffie2110e042015-03-24 08:41:51 +010082 */
83 virtual status_t setForceUse(audio_policy_force_use_t usage,
84 audio_policy_forced_cfg_t config) = 0;
85
86 /**
87 * Get Force Use config for a given usage.
88 *
89 * @param[in] usage for which a configuration shall be forced.
90 *
91 * @return config wished to be forced for the given usage.
92 */
93 virtual audio_policy_forced_cfg_t getForceUse(audio_policy_force_use_t usage) const = 0;
94
95 /**
96 * Set the connection state of device(s).
97 *
98 * @param[in] devDesc for which the state has changed.
99 * @param[in] state of availability of this(these) device(s).
100 *
101 * @return NO_ERROR if devices criterion updated correctly, error code otherwise.
102 */
103 virtual status_t setDeviceConnectionState(const android::sp<android::DeviceDescriptor> devDesc,
104 audio_policy_dev_state_t state) = 0;
105
François Gaffiedc7553f2018-11-02 10:39:57 +0100106 /**
107 * Get the strategy selected for a given audio attributes.
108 *
109 * @param[in] audio attributes to get the selected @product_strategy_t followed by.
110 *
111 * @return @product_strategy_t to be followed.
112 */
113 virtual product_strategy_t getProductStrategyForAttributes(
114 const audio_attributes_t &attr) const = 0;
115
116 /**
117 * @brief getOutputDevicesForAttributes retrieves the devices to be used for given
118 * audio attributes.
119 * @param attributes of the output requesting Device(s) selection
120 * @param preferedDevice valid reference if a prefered device is requested, nullptr otherwise.
121 * @param fromCache if true, the device is returned from internal cache,
122 * otherwise it is determined by current state (device connected,phone state,
123 * force use, a2dp output...)
124 * @return vector of selected device descriptors.
125 * Appropriate device for streams handled by the specified audio attributes according
126 * to current phone state, forced states, connected devices...
127 * if fromCache is true, the device is returned from internal cache,
128 * otherwise it is determined by current state (device connected,phone state, force use,
129 * a2dp output...)
130 * This allows to:
131 * 1 speed up process when the state is stable (when starting or stopping an output)
132 * 2 access to either current device selection (fromCache == true) or
133 * "future" device selection (fromCache == false) when called from a context
134 * where conditions are changing (setDeviceConnectionState(), setPhoneState()...) AND
135 * before manager updates its outputs.
136 */
137 virtual DeviceVector getOutputDevicesForAttributes(
138 const audio_attributes_t &attributes,
139 const sp<DeviceDescriptor> &preferedDevice = nullptr,
140 bool fromCache = false) const = 0;
141
142 /**
143 * @brief getOutputDevicesForStream Legacy function retrieving devices from a stream type.
144 * @param stream type of the output requesting Device(s) selection
145 * @param fromCache if true, the device is returned from internal cache,
146 * otherwise it is determined by current state (device connected,phone state,
147 * force use, a2dp output...)
148 * @return appropriate device for streams handled by the specified audio attributes according
149 * to current phone state, forced states, connected devices...
150 * if fromCache is true, the device is returned from internal cache,
151 * otherwise it is determined by current state (device connected,phone state, force use,
152 * a2dp output...)
153 * This allows to:
154 * 1 speed up process when the state is stable (when starting or stopping an output)
155 * 2 access to either current device selection (fromCache == true) or
156 * "future" device selection (fromCache == false) when called from a context
157 * where conditions are changing (setDeviceConnectionState(), setPhoneState()...) AND
158 * before manager updates its outputs.
159 */
160 virtual DeviceVector getOutputDevicesForStream(audio_stream_type_t stream,
161 bool fromCache = false) const = 0;
162
163 /**
164 * Get the input device selected for given audio attributes.
165 *
166 * @param[in] attr audio attributes to consider
167 * @param[out] mix to be used if a mix has been installed for the given audio attributes.
168 * @return selected input device for the audio attributes, may be null if error.
169 */
170 virtual sp<DeviceDescriptor> getInputDeviceForAttributes(
171 const audio_attributes_t &attr, AudioMix **mix = nullptr) const = 0;
172
173 /**
174 * Get the legacy stream type for a given audio attributes.
175 *
176 * @param[in] audio attributes to get the associated audio_stream_type_t.
177 *
178 * @return audio_stream_type_t associated to the attributes.
179 */
180 virtual audio_stream_type_t getStreamTypeForAttributes(
181 const audio_attributes_t &attr) const = 0;
182
183 /**
184 * @brief getAttributesForStream get the audio attributes from legacy stream type
185 * @param stream to consider
186 * @return audio attributes matching the legacy stream type
187 */
188 virtual audio_attributes_t getAttributesForStreamType(audio_stream_type_t stream) const = 0;
189
190 /**
191 * @brief getStreamTypesForProductStrategy retrieves the list of legacy stream type following
192 * the given product strategy
193 * @param ps product strategy to consider
194 * @return associated legacy Stream Types vector of the given product strategy
195 */
196 virtual StreamTypeVector getStreamTypesForProductStrategy(product_strategy_t ps) const = 0;
197
198 /**
199 * @brief getAllAttributesForProductStrategy retrieves all the attributes following the given
200 * product strategy. Any attributes that "matches" with this one will follow the product
201 * strategy.
202 * "matching" means the usage shall match if reference attributes has a defined usage, AND
203 * content type shall match if reference attributes has a defined content type AND
204 * flags shall match if reference attributes has defined flags AND
205 * tags shall match if reference attributes has defined tags.
206 * @param ps product strategy to consider
207 * @return vector of product strategy ids, empty if unknown strategy.
208 */
209 virtual AttributesVector getAllAttributesForProductStrategy(product_strategy_t ps) const = 0;
210
211 /**
212 * @brief getOrderedAudioProductStrategies
213 * @return priority ordered product strategies to help the AudioPolicyManager evaluating the
214 * device selection per output according to the prioritized strategies.
215 */
216 virtual StrategyVector getOrderedProductStrategies() const = 0;
217
218 /**
219 * @brief updateDeviceSelectionCache. Device selection for AudioAttribute / Streams is cached
220 * in the engine in order to speed up process when the audio system is stable.
221 * When a device is connected, the android mode is changed, engine is notified and can update
222 * the cache.
223 * When starting / stopping an output with a stream that can affect notification, the engine
224 * needs to update the cache upon this function call.
225 */
226 virtual void updateDeviceSelectionCache() = 0;
227
François Gaffied0ba9ed2018-11-05 11:50:42 +0100228 /**
229 * @brief listAudioProductStrategies. Introspection API to retrieve a collection of
230 * AudioProductStrategyVector that allows to build AudioAttributes according to a
231 * product_strategy which is just an index. It has also a human readable name to help the
232 * Car/Oem/AudioManager identiying the use case.
233 * @param strategies collection.
234 * @return OK if the list has been retrieved, error code otherwise
235 */
236 virtual status_t listAudioProductStrategies(AudioProductStrategyVector &strategies) const = 0;
237
Eric Laurentf5aa58d2019-02-22 18:20:11 -0800238 /**
239 * @brief getVolumeCurvesForAttributes retrieves the Volume Curves interface for the
240 * requested Audio Attributes.
241 * @param attr to be considered
242 * @return IVolumeCurves interface pointer if found, nullptr otherwise
243 */
244 virtual IVolumeCurves *getVolumeCurvesForAttributes(const audio_attributes_t &attr) = 0;
245
246 /**
247 * @brief getVolumeCurvesForStreamType retrieves the Volume Curves interface for the stream
248 * @param stream to be considered
249 * @return IVolumeCurves interface pointer if found, nullptr otherwise
250 */
251 virtual IVolumeCurves *getVolumeCurvesForStreamType(audio_stream_type_t stream) = 0;
252
François Gaffiedc7553f2018-11-02 10:39:57 +0100253 virtual void dump(String8 *dst) const = 0;
254
François Gaffie2110e042015-03-24 08:41:51 +0100255protected:
256 virtual ~AudioPolicyManagerInterface() {}
257};
258
Mikhail Naganov1b2a7942017-12-08 10:18:09 -0800259} // namespace android