1 /* 2 * Copyright (c) 2022-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup HdiAudio 18 * 19 * @brief Provides unified APIs for audio services to access audio drivers. 20 * 21 * An audio service can obtain an audio driver object or agent and then call APIs provided by this object or agent to 22 * access different types of audio devices based on the audio IDs, thereby obtaining audio information, 23 * subscribing to or unsubscribing from audio data, enabling or disabling an audio, 24 * setting the audio data reporting mode, and setting audio options such as the accuracy and measurement range. 25 * 26 * @since 4.0 27 * @version 1.0 28 */ 29 30 package ohos.hdi.audio.v1_0; 31 32 import ohos.hdi.audio.v1_0.AudioTypes; 33 import ohos.hdi.audio.v1_0.IAudioRender; 34 import ohos.hdi.audio.v1_0.IAudioCapture; 35 import ohos.hdi.audio.v1_0.IAudioCallback; 36 37 /** 38 * @brief Provides audio adapter capabilities, including initializing ports, creating rendering and capturing tasks, 39 * and obtaining the port capability set. 40 * 41 * @see IAudioRender 42 * @see IAudioCapture 43 * @since 4.0 44 * @version 1.0 45 */ 46 interface IAudioAdapter { 47 /** 48 * @brief Initializes all ports of an audio adapter. 49 * 50 * Call this function before calling other driver functions to check whether the initialization is complete. 51 * If the initialization is not complete, wait for a while (for example, 100 ms) and perform the check again 52 * until the port initialization is complete. 53 * 54 * @param adapter Indicates the pointer to the audio adapter to operate. 55 * @return Returns <b>0</b> if the initialization is successful; returns a negative value otherwise. 56 */ 57 InitAllPorts(); 58 59 /** 60 * @brief Creates an <b>IAudioRender</b> object. 61 * 62 * @param adapter Indicates the pointer to the audio adapter to operate. 63 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 64 * @param attrs Indicates the pointer to the audio sampling attributes to open. 65 * @param render Indicates the double pointer to the <b>IAudioRender</b> object. 66 * @return Returns <b>0</b> if the <b>IAudioRender</b> object is created successfully; 67 * returns a negative value otherwise. 68 * @see GetPortCapability 69 * @see DestroyRender 70 */ 71 CreateRender([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs, 72 [out] IAudioRender render, [out] unsigned int renderId); 73 74 /** 75 * @brief Destroys an <b>IAudioRender</b> object. 76 * 77 * @attention Do not destroy the object during audio rendering. 78 * 79 * @param adapter Indicates the pointer to the audio adapter to operate. 80 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 81 * @return Returns <b>0</b> if the <b>IAudioRender</b> object is destroyed; returns a negative value otherwise. 82 * @see CreateRender 83 */ 84 DestroyRender([in] unsigned int renderId); 85 86 /** 87 * @brief Creates an <b>IAudioCapture</b> object. 88 * 89 * @param adapter Indicates the pointer to the audio adapter to operate. 90 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 91 * @param attrs Indicates the pointer to the audio sampling attributes to open. 92 * @param capture Indicates the double pointer to the <b>IAudioCapture</b> object. 93 * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is created successfully; 94 * returns a negative value otherwise. 95 * @see GetPortCapability 96 * @see DestroyCapture 97 */ 98 CreateCapture([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs, 99 [out] IAudioCapture capture, [out] unsigned int captureId); 100 101 /** 102 * @brief Destroys an <b>IAudioCapture</b> object. 103 * 104 * @attention Do not destroy the object during audio capturing. 105 * 106 * @param adapter Indicates the pointer to the audio adapter to operate. 107 * @param capture Indicates the pointer to the <b>IAudioCapture</b> object to operate. 108 * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is destroyed; returns a negative value otherwise. 109 * @see CreateCapture 110 */ 111 DestroyCapture([in] unsigned int captureId); 112 113 /** 114 * @brief Obtains the capability set of the port driver for the audio adapter. 115 * 116 * @param adapter Indicates the pointer to the audio adapter to operate. 117 * @param port Indicates the pointer to the port. 118 * @param capability Indicates the pointer to the capability set to obtain. 119 * @return Returns <b>0</b> if the capability set is successfully obtained; returns a negative value otherwise. 120 */ 121 GetPortCapability([in] struct AudioPort port, [out] struct AudioPortCapability capability); 122 123 /** 124 * @brief Sets the passthrough data transmission mode of the audio port driver. 125 * 126 * @param adapter Indicates the pointer to the audio adapter to operate. 127 * @param port Indicates the pointer to the port. 128 * @param mode Indicates the passthrough transmission mode to set. 129 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 130 * @see GetPassthroughMode 131 */ 132 SetPassthroughMode([in] struct AudioPort port, [in] enum AudioPortPassthroughMode mode); 133 134 /** 135 * @brief Obtains the passthrough data transmission mode of the audio port driver. 136 * 137 * @param adapter Indicates the pointer to the audio adapter to operate. 138 * @param port Indicates the pointer to the port. 139 * @param mode Indicates the pointer to the passthrough transmission mode to obtain. 140 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 141 * @see SetPassthroughMode 142 */ 143 GetPassthroughMode([in] struct AudioPort port, [out] enum AudioPortPassthroughMode mode); 144 145 /** 146 * @brief Get the device status of an adapter. 147 * 148 * @param adapter Indicates the audio adapter. 149 * @param status Indicates the status of device . 150 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 151 */ 152 GetDeviceStatus([out] struct AudioDeviceStatus status); 153 154 /** 155 * @brief Update audio route on several source and sink ports. 156 * 157 * @param adapter Indicates the pointer to the audio adapter to operate. 158 * @param route Indicates route information. 159 * @param routeHandle Indicates route handle. 160 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 161 * @see SetPassthroughMode 162 */ 163 UpdateAudioRoute([in] struct AudioRoute route, [out] int routeHandle); 164 165 /** 166 * @brief Release an audio route. 167 * 168 * @param adapter Indicates the pointer to the audio adapter to operate. 169 * @param routeHandle Indicates route handle. 170 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 171 * @see SetPassthroughMode 172 */ 173 ReleaseAudioRoute([in] int routeHandle); 174 175 /** 176 * @brief Sets the mute operation for the audio. 177 * 178 * @param adapter Indicates the pointer to the audio adapter to operate. 179 * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio, 180 * and <b>false</b> means the opposite. 181 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 182 * @see GetMute 183 */ 184 SetMicMute([in] boolean mute); 185 186 /** 187 * @brief Obtains the mute operation set for the audio. 188 * 189 * @param adapter Indicates the pointer to the audio adapter to operate. 190 * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that 191 * the audio is muted, and <b>false</b> means the opposite. 192 * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise. 193 * @see SetMute 194 */ 195 GetMicMute([out] boolean mute); 196 197 /** 198 * @brief Sets the audio volume for voice call. 199 * 200 * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15, 201 * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15). 202 * 203 * @param adapter Indicates the pointer to the audio adapter to operate. 204 * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0. 205 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 206 * @see GetVolume 207 */ 208 SetVoiceVolume([in] float volume); 209 210 /** 211 * @brief Sets extra audio parameters. 212 * 213 * @param adapter Indicates the audio adapter. 214 * @param key Indicates what kind of parameter type will be set. 215 * @param condition Indicates the specific extend parameter condition of AudioExtParamKey. 216 * @param value Indicates the value of the specified condition. 217 * 218 * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 219 * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this: 220 * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i> 221 * EVENT_TYPE indicates sub volume event type: SetVolume = 1; SetMute = 4; 222 * VOLUME_GROUP_ID indicates which volume group will be set; 223 * AUDIO_VOLUME_TYPE indicates which volume type will be set; 224 * 225 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 226 */ 227 SetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [in] String value); 228 229 /** 230 * @brief Get extra audio parameters. 231 * 232 * @param adapter Indicates the audio adapter. 233 * @param key Indicates what kind of parameter type will be get. 234 * @param condition Indicates the specific extend parameter condition of AudioExtParamKey. 235 * @param value Indicates the value of the specified condition. 236 * @param lenth Indicates the length of the value pointer. 237 * 238 * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 239 * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this: 240 * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i> 241 * EVENT_TYPE indicates sub volume event type: GetVolume = 1; GetMinVolume = 2; GetMaxVolume = 3; IsStreamMute = 4; 242 * VOLUME_GROUP_ID indicates which volume group want get; 243 * AUDIO_VOLUME_TYPE indicates which volume type want get; 244 * 245 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 246 */ 247 GetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [out] String value); 248 249 /** 250 * @brief Register extra audio parameters observer. 251 * 252 * @param adapter Indicates the audio adapter. 253 * @param callback Indicates param observer. 254 * @param cookie Indicates the pointer to the callback parameters; 255 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 256 */ 257 RegExtraParamObserver([in] IAudioCallback audioCallback, [in] byte cookie); 258 } 259 /** @} */