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 <utility> 20 21 #include <AudioPolicyManagerObserver.h> 22 #include <media/AudioProductStrategy.h> 23 #include <media/AudioVolumeGroup.h> 24 #include <IVolumeCurves.h> 25 #include <policy.h> 26 #include <Volume.h> 27 #include <HwModule.h> 28 #include <DeviceDescriptor.h> 29 #include <system/audio.h> 30 #include <system/audio_policy.h> 31 #include <utils/Errors.h> 32 #include <utils/Vector.h> 33 34 namespace android { 35 36 using DeviceStrategyMap = std::map<product_strategy_t, DeviceVector>; 37 using StrategyVector = std::vector<product_strategy_t>; 38 using VolumeGroupVector = std::vector<volume_group_t>; 39 using CapturePresetDevicesRoleMap = 40 std::map<std::pair<audio_source_t, device_role_t>, AudioDeviceTypeAddrVector>; 41 42 /** 43 * This interface is dedicated to the policy manager that a Policy Engine shall implement. 44 */ 45 class EngineInterface 46 { 47 public: 48 /** 49 * Checks if the engine was correctly initialized. 50 * 51 * @return NO_ERROR if initialization has been done correctly, error code otherwise.. 52 */ 53 virtual status_t initCheck() = 0; 54 55 /** 56 * Sets the Manager observer that allows the engine to retrieve information on collection 57 * of devices, streams, HwModules, ... 58 * 59 * @param[in] observer handle on the manager. 60 */ 61 virtual void setObserver(AudioPolicyManagerObserver *observer) = 0; 62 63 /** 64 * Set the Telephony Mode. 65 * 66 * @param[in] mode: Android Phone state (normal, ringtone, csv, in communication) 67 * 68 * @return NO_ERROR if Telephony Mode set correctly, error code otherwise. 69 */ 70 virtual status_t setPhoneState(audio_mode_t mode) = 0; 71 72 /** 73 * Get the telephony Mode 74 * 75 * @return the current telephony mode 76 */ 77 virtual audio_mode_t getPhoneState() const = 0; 78 79 /** 80 * Set Force Use config for a given usage. 81 * 82 * @param[in] usage for which a configuration shall be forced. 83 * @param[in] config wished to be forced for the given usage. 84 * 85 * @return NO_ERROR if the Force Use config was set correctly, error code otherwise (e.g. config 86 * not allowed a given usage...) 87 */ 88 virtual status_t setForceUse(audio_policy_force_use_t usage, 89 audio_policy_forced_cfg_t config) = 0; 90 91 /** 92 * Get Force Use config for a given usage. 93 * 94 * @param[in] usage for which a configuration shall be forced. 95 * 96 * @return config wished to be forced for the given usage. 97 */ 98 virtual audio_policy_forced_cfg_t getForceUse(audio_policy_force_use_t usage) const = 0; 99 100 /** 101 * Set the connection state of device(s). 102 * 103 * @param[in] devDesc for which the state has changed. 104 * @param[in] state of availability of this(these) device(s). 105 * 106 * @return NO_ERROR if devices criterion updated correctly, error code otherwise. 107 */ 108 virtual status_t setDeviceConnectionState(const android::sp<android::DeviceDescriptor> devDesc, 109 audio_policy_dev_state_t state) = 0; 110 111 /** 112 * Get the strategy selected for a given audio attributes. 113 * 114 * @param[in] audio attributes to get the selected @product_strategy_t followed by. 115 * @param fallbackOnDefault if true, will return the fallback strategy if the attributes 116 * are not explicitly assigned to a given strategy. 117 * @return @product_strategy_t to be followed. 118 */ 119 virtual product_strategy_t getProductStrategyForAttributes( 120 const audio_attributes_t &attr, bool fallbackOnDefault = true) const = 0; 121 122 /** 123 * @brief getOutputDevicesForAttributes retrieves the devices to be used for given 124 * audio attributes. 125 * @param attributes of the output requesting Device(s) selection 126 * @param preferedDevice valid reference if a prefered device is requested, nullptr otherwise. 127 * @param fromCache if true, the device is returned from internal cache, 128 * otherwise it is determined by current state (device connected,phone state, 129 * force use, a2dp output...) 130 * @return vector of selected device descriptors. 131 * Appropriate device for streams handled by the specified audio attributes according 132 * to current phone state, forced states, connected devices... 133 * if fromCache is true, the device is returned from internal cache, 134 * otherwise it is determined by current state (device connected,phone state, force use, 135 * a2dp output...) 136 * This allows to: 137 * 1 speed up process when the state is stable (when starting or stopping an output) 138 * 2 access to either current device selection (fromCache == true) or 139 * "future" device selection (fromCache == false) when called from a context 140 * where conditions are changing (setDeviceConnectionState(), setPhoneState()...) AND 141 * before manager updates its outputs. 142 */ 143 virtual DeviceVector getOutputDevicesForAttributes( 144 const audio_attributes_t &attributes, 145 const sp<DeviceDescriptor> &preferedDevice = nullptr, 146 bool fromCache = false) const = 0; 147 148 /** 149 * @brief getOutputDevicesForStream Legacy function retrieving devices from a stream type. 150 * @param stream type of the output requesting Device(s) selection 151 * @param fromCache if true, the device is returned from internal cache, 152 * otherwise it is determined by current state (device connected,phone state, 153 * force use, a2dp output...) 154 * @return appropriate device for streams handled by the specified audio attributes according 155 * to current phone state, forced states, connected devices... 156 * if fromCache is true, the device is returned from internal cache, 157 * otherwise it is determined by current state (device connected,phone state, force use, 158 * a2dp output...) 159 * This allows to: 160 * 1 speed up process when the state is stable (when starting or stopping an output) 161 * 2 access to either current device selection (fromCache == true) or 162 * "future" device selection (fromCache == false) when called from a context 163 * where conditions are changing (setDeviceConnectionState(), setPhoneState()...) AND 164 * before manager updates its outputs. 165 */ 166 virtual DeviceVector getOutputDevicesForStream(audio_stream_type_t stream, 167 bool fromCache = false) const = 0; 168 169 /** 170 * Get the input device selected for given audio attributes. 171 * 172 * @param[in] attr audio attributes to consider 173 * @param[out] mix to be used if a mix has been installed for the given audio attributes. 174 * @return selected input device for the audio attributes, may be null if error. 175 */ 176 virtual sp<DeviceDescriptor> getInputDeviceForAttributes(const audio_attributes_t &attr, 177 uid_t uid = 0, 178 sp<AudioPolicyMix> *mix = nullptr) 179 const = 0; 180 181 /** 182 * Get the legacy stream type for a given audio attributes. 183 * 184 * @param[in] audio attributes to get the associated audio_stream_type_t. 185 * 186 * @return audio_stream_type_t associated to the attributes. 187 */ 188 virtual audio_stream_type_t getStreamTypeForAttributes( 189 const audio_attributes_t &attr) const = 0; 190 191 /** 192 * @brief getAttributesForStream get the audio attributes from legacy stream type 193 * Attributes returned might only be used to check upon routing decision, not volume decisions. 194 * @param stream to consider 195 * @return audio attributes matching the legacy stream type 196 */ 197 virtual audio_attributes_t getAttributesForStreamType(audio_stream_type_t stream) const = 0; 198 199 /** 200 * @brief getStreamTypesForProductStrategy retrieves the list of legacy stream type following 201 * the given product strategy 202 * @param ps product strategy to consider 203 * @return associated legacy Stream Types vector of the given product strategy 204 */ 205 virtual StreamTypeVector getStreamTypesForProductStrategy(product_strategy_t ps) const = 0; 206 207 /** 208 * @brief getAllAttributesForProductStrategy retrieves all the attributes following the given 209 * product strategy. Any attributes that "matches" with this one will follow the product 210 * strategy. 211 * "matching" means the usage shall match if reference attributes has a defined usage, AND 212 * content type shall match if reference attributes has a defined content type AND 213 * flags shall match if reference attributes has defined flags AND 214 * tags shall match if reference attributes has defined tags. 215 * @param ps product strategy to consider 216 * @return vector of product strategy ids, empty if unknown strategy. 217 */ 218 virtual AttributesVector getAllAttributesForProductStrategy(product_strategy_t ps) const = 0; 219 220 /** 221 * @brief getOrderedAudioProductStrategies 222 * @return priority ordered product strategies to help the AudioPolicyManager evaluating the 223 * device selection per output according to the prioritized strategies. 224 */ 225 virtual StrategyVector getOrderedProductStrategies() const = 0; 226 227 /** 228 * @brief updateDeviceSelectionCache. Device selection for AudioAttribute / Streams is cached 229 * in the engine in order to speed up process when the audio system is stable. 230 * When a device is connected, the android mode is changed, engine is notified and can update 231 * the cache. 232 * When starting / stopping an output with a stream that can affect notification, the engine 233 * needs to update the cache upon this function call. 234 */ 235 virtual void updateDeviceSelectionCache() = 0; 236 237 /** 238 * @brief listAudioProductStrategies. Introspection API to retrieve a collection of 239 * AudioProductStrategyVector that allows to build AudioAttributes according to a 240 * product_strategy which is just an index. It has also a human readable name to help the 241 * Car/Oem/AudioManager identiying the use case. 242 * @param strategies collection. 243 * @return OK if the list has been retrieved, error code otherwise 244 */ 245 virtual status_t listAudioProductStrategies(AudioProductStrategyVector &strategies) const = 0; 246 247 /** 248 * @brief getVolumeCurvesForAttributes retrieves the Volume Curves interface for the 249 * requested Audio Attributes. 250 * @param attr to be considered 251 * @return IVolumeCurves interface pointer if found, nullptr otherwise 252 */ 253 virtual IVolumeCurves *getVolumeCurvesForAttributes(const audio_attributes_t &attr) const = 0; 254 255 /** 256 * @brief getVolumeCurvesForStreamType retrieves the Volume Curves interface for the stream 257 * @param stream to be considered 258 * @return IVolumeCurves interface pointer if found, nullptr otherwise 259 */ 260 virtual IVolumeCurves *getVolumeCurvesForStreamType(audio_stream_type_t stream) const = 0; 261 262 /** 263 * @brief getVolumeCurvesForVolumeGroup retrieves the Volume Curves interface for volume group 264 * @param group to be considered 265 * @return IVolumeCurves interface pointer if found, nullptr otherwise 266 */ 267 virtual IVolumeCurves *getVolumeCurvesForVolumeGroup(volume_group_t group) const = 0; 268 269 /** 270 * @brief getVolumeGroups retrieves the collection of volume groups. 271 * @return vector of volume groups 272 */ 273 virtual VolumeGroupVector getVolumeGroups() const = 0; 274 275 /** 276 * @brief getVolumeGroupForAttributes gets the appropriate volume group to be used for a given 277 * Audio Attributes. 278 * @param attr to be considered 279 * @param fallbackOnDefault if true, will return the fallback volume group if the attributes 280 * are not associated to any volume group. 281 * @return volume group associated to the given audio attributes, default group if none 282 * applicable, VOLUME_GROUP_NONE if no default group defined. 283 */ 284 virtual volume_group_t getVolumeGroupForAttributes( 285 const audio_attributes_t &attr, bool fallbackOnDefault = true) const = 0; 286 287 /** 288 * @brief getVolumeGroupForStreamType gets the appropriate volume group to be used for a given 289 * legacy stream type 290 * @param stream type to be considered 291 * @param fallbackOnDefault if true, will return the fallback volume group if the stream type 292 * is not associated to any volume group. 293 * @return volume group associated to the given stream type, default group if none applicable, 294 * VOLUME_GROUP_NONE if no default group defined. 295 */ 296 virtual volume_group_t getVolumeGroupForStreamType( 297 audio_stream_type_t stream, bool fallbackOnDefault = true) const = 0; 298 299 /** 300 * @brief listAudioVolumeGroups introspection API to get the Audio Volume Groups, aka 301 * former stream aliases in Audio Service, defining volume curves attached to one or more 302 * Audio Attributes. 303 * @param groups 304 * @return NO_ERROR if the volume groups were retrieved successfully, error code otherwise 305 */ 306 virtual status_t listAudioVolumeGroups(AudioVolumeGroupVector &groups) const = 0; 307 308 /** 309 * @brief setDevicesRoleForStrategy sets devices role for a strategy when available. To remove 310 * devices role, removeDevicesRoleForStrategy must be called. When devices role is set 311 * successfully, previously set devices for the same role and strategy will be removed. 312 * @param strategy the audio strategy whose routing will be affected 313 * @param role the role of the devices for the strategy. All device roles are defined at 314 * system/media/audio/include/system/audio_policy.h. DEVICE_ROLE_NONE is invalid 315 * for setting. 316 * @param devices the audio devices to be set 317 * @return BAD_VALUE if the strategy or role is invalid, 318 * or NO_ERROR if the role of the devices for strategy was set 319 */ 320 virtual status_t setDevicesRoleForStrategy(product_strategy_t strategy, device_role_t role, 321 const AudioDeviceTypeAddrVector &devices) = 0; 322 323 /** 324 * @brief removeDevicesRoleForStrategy removes the role of device(s) previously set 325 * for the given strategy 326 * @param strategy the audio strategy whose routing will be affected 327 * @param role the role of the devices for strategy 328 * @return BAD_VALUE if the strategy or role is invalid, 329 * or NO_ERROR if the devices for this role was removed 330 */ 331 virtual status_t removeDevicesRoleForStrategy(product_strategy_t strategy, 332 device_role_t role) = 0; 333 334 /** 335 * @brief getDevicesForRoleAndStrategy queries which devices have the specified role for the 336 * specified strategy 337 * @param strategy the strategy to query 338 * @param role the role of the devices to query 339 * @param devices returns list of devices with matching role for the specified strategy. 340 * DEVICE_ROLE_NONE is invalid as input. 341 * @return BAD_VALUE if the strategy or role is invalid, 342 * or NAME_NOT_FOUND if no device for the role and strategy was set 343 * or NO_ERROR if the devices parameter contains a list of devices 344 */ 345 virtual status_t getDevicesForRoleAndStrategy(product_strategy_t strategy, device_role_t role, 346 AudioDeviceTypeAddrVector &devices) const = 0; 347 348 /** 349 * @brief setDevicesRoleForCapturePreset sets devices role for a capture preset when available. 350 * To remove devices role, removeDevicesRoleForCapturePreset must be called. Calling 351 * clearDevicesRoleForCapturePreset will remove all devices as role. When devices role is set 352 * successfully, previously set devices for the same role and capture preset will be removed. 353 * @param audioSource the audio capture preset whose routing will be affected 354 * @param role the role of the devices for the capture preset. All device roles are defined at 355 * system/media/audio/include/system/audio_policy.h. DEVICE_ROLE_NONE is invalid 356 * for setting. 357 * @param devices the audio devices to be set 358 * @return BAD_VALUE if the capture preset or role is invalid, 359 * or NO_ERROR if the role of the devices for capture preset was set 360 */ 361 virtual status_t setDevicesRoleForCapturePreset(audio_source_t audioSource, device_role_t role, 362 const AudioDeviceTypeAddrVector &devices) = 0; 363 364 /** 365 * @brief addDevicesRoleForCapturePreset adds devices role for a capture preset when available. 366 * To remove devices role, removeDevicesRoleForCapturePreset must be called. Calling 367 * clearDevicesRoleForCapturePreset will remove all devices as role. 368 * @param audioSource the audio capture preset whose routing will be affected 369 * @param role the role of the devices for the capture preset. All device roles are defined at 370 * system/media/audio/include/system/audio_policy.h. DEVICE_ROLE_NONE is invalid 371 * for setting. 372 * @param devices the audio devices to be added 373 * @return BAD_VALUE if the capture preset or role is invalid, 374 * or NO_ERROR if the role of the devices for capture preset was added 375 */ 376 virtual status_t addDevicesRoleForCapturePreset(audio_source_t audioSource, device_role_t role, 377 const AudioDeviceTypeAddrVector &devices) = 0; 378 379 /** 380 * @brief removeDevicesRoleForCapturePreset removes the role of device(s) previously set 381 * for the given capture preset 382 * @param audioSource the audio capture preset whose routing will be affected 383 * @param role the role of the devices for the capture preset 384 * @param devices the devices to be removed 385 * @return BAD_VALUE if 1) the capture preset is invalid, 2) role is invalid or 3) the list of 386 * devices to be removed are not all present as role for a capture preset 387 * or NO_ERROR if the devices for this role was removed 388 */ 389 virtual status_t removeDevicesRoleForCapturePreset(audio_source_t audioSource, 390 device_role_t role, const AudioDeviceTypeAddrVector& devices) = 0; 391 392 /** 393 * @brief clearDevicesRoleForCapturePreset removes the role of all device(s) previously set 394 * for the given capture preset 395 * @param audioSource the audio capture preset whose routing will be affected 396 * @param role the role of the devices for the capture preset 397 * @return BAD_VALUE if the capture preset or role is invalid, 398 * or NO_ERROR if the devices for this role was removed 399 */ 400 virtual status_t clearDevicesRoleForCapturePreset(audio_source_t audioSource, 401 device_role_t role); 402 403 /** 404 * @brief getDevicesForRoleAndCapturePreset queries which devices have the specified role for 405 * the specified capture preset 406 * @param audioSource the capture preset to query 407 * @param role the role of the devices to query 408 * @param devices returns list of devices with matching role for the specified capture preset. 409 * DEVICE_ROLE_NONE is invalid as input. 410 * @return BAD_VALUE if the capture preset or role is invalid, 411 * or NAME_NOT_FOUND if no device for the role and capture preset was set 412 * or NO_ERROR if the devices parameter contains a list of devices 413 */ 414 virtual status_t getDevicesForRoleAndCapturePreset(audio_source_t audioSource, 415 device_role_t role, AudioDeviceTypeAddrVector &devices) const = 0; 416 417 /** 418 * @brief getActiveMediaDevices returns which devices will most likely to be used for media 419 * @param availableDevices all available devices 420 * @return collection of active devices 421 */ 422 virtual DeviceVector getActiveMediaDevices(const DeviceVector& availableDevices) const = 0; 423 424 virtual void dump(String8 *dst) const = 0; 425 426 protected: ~EngineInterface()427 virtual ~EngineInterface() {} 428 }; 429 430 __attribute__((visibility("default"))) 431 extern "C" EngineInterface* createEngineInstance(); 432 433 __attribute__((visibility("default"))) 434 extern "C" void destroyEngineInstance(EngineInterface *engine); 435 436 } // namespace android 437