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