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