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 30package ohos.hdi.audio.v1_0; 31 32import ohos.hdi.audio.v1_0.AudioTypes; 33import ohos.hdi.audio.v1_0.IAudioRender; 34import ohos.hdi.audio.v1_0.IAudioCapture; 35import 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 */ 46interface 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 * @return Returns <b>0</b> if the initialization is successful; returns a negative value otherwise. 55 */ 56 InitAllPorts(); 57 58 /** 59 * @brief Creates an <b>IAudioRender</b> object. 60 * 61 * @param adapter Indicates the pointer to the audio adapter to operate. 62 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 63 * @param attrs Indicates the pointer to the audio sampling attributes to open. 64 * @param render Indicates the double pointer to the <b>IAudioRender</b> object. 65 * @return Returns <b>0</b> if the <b>IAudioRender</b> object is created successfully; 66 * returns a negative value otherwise. 67 * @see GetPortCapability 68 * @see DestroyRender 69 */ 70 CreateRender([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs, 71 [out] IAudioRender render, [out] unsigned int renderId); 72 73 /** 74 * @brief Destroys an <b>IAudioRender</b> object. 75 * 76 * @attention Do not destroy the object during audio rendering. 77 * 78 * @param renderId Indicates the pointer to the <b>IAudioRender</b> object to operate. 79 * @return Returns <b>0</b> if the <b>IAudioRender</b> object is destroyed; returns a negative value otherwise. 80 * @see CreateRender 81 */ 82 DestroyRender([in] unsigned int renderId); 83 84 /** 85 * @brief Creates an <b>IAudioCapture</b> object. 86 * 87 * @param adapter Indicates the pointer to the audio adapter to operate. 88 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 89 * @param attrs Indicates the pointer to the audio sampling attributes to open. 90 * @param capture Indicates the double pointer to the <b>IAudioCapture</b> object. 91 * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is created successfully; 92 * returns a negative value otherwise. 93 * @see GetPortCapability 94 * @see DestroyCapture 95 */ 96 CreateCapture([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs, 97 [out] IAudioCapture capture, [out] unsigned int captureId); 98 99 /** 100 * @brief Destroys an <b>IAudioCapture</b> object. 101 * 102 * @attention Do not destroy the object during audio capturing. 103 * 104 * @param captureId Indicates the pointer to the <b>IAudioCapture</b> object to operate. 105 * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is destroyed; returns a negative value otherwise. 106 * @see CreateCapture 107 */ 108 DestroyCapture([in] unsigned int captureId); 109 110 /** 111 * @brief Obtains the capability set of the port driver for the audio adapter. 112 * 113 * @param port Indicates the pointer to the port. 114 * @param capability Indicates the pointer to the capability set to obtain. 115 * @return Returns <b>0</b> if the capability set is successfully obtained; returns a negative value otherwise. 116 */ 117 GetPortCapability([in] struct AudioPort port, [out] struct AudioPortCapability capability); 118 119 /** 120 * @brief Sets the passthrough data transmission mode of the audio port driver. 121 * 122 * @param port Indicates the pointer to the port. 123 * @param mode Indicates the passthrough transmission mode to set. 124 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 125 * @see GetPassthroughMode 126 */ 127 SetPassthroughMode([in] struct AudioPort port, [in] enum AudioPortPassthroughMode mode); 128 129 /** 130 * @brief Obtains the passthrough data transmission mode of the audio port driver. 131 * 132 * @param port Indicates the pointer to the port. 133 * @param mode Indicates the pointer to the passthrough transmission mode to obtain. 134 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 135 * @see SetPassthroughMode 136 */ 137 GetPassthroughMode([in] struct AudioPort port, [out] enum AudioPortPassthroughMode mode); 138 139 /** 140 * @brief Get the device status of an adapter. 141 * 142 * @param status Indicates the status of device . 143 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 144 */ 145 GetDeviceStatus([out] struct AudioDeviceStatus status); 146 147 /** 148 * @brief Update audio route on several source and sink ports. 149 * 150 * @param route Indicates route information. 151 * @param routeHandle Indicates route handle. 152 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 153 * @see SetPassthroughMode 154 */ 155 UpdateAudioRoute([in] struct AudioRoute route, [out] int routeHandle); 156 157 /** 158 * @brief Release an audio route. 159 * 160 * @param routeHandle Indicates route handle. 161 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 162 * @see SetPassthroughMode 163 */ 164 ReleaseAudioRoute([in] int routeHandle); 165 166 /** 167 * @brief Sets the mute operation for the audio. 168 * 169 * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio, 170 * and <b>false</b> means the opposite. 171 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 172 * @see GetMute 173 */ 174 SetMicMute([in] boolean mute); 175 176 /** 177 * @brief Obtains the mute operation set for the audio. 178 * 179 * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that 180 * the audio is muted, and <b>false</b> means the opposite. 181 * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise. 182 * @see SetMute 183 */ 184 GetMicMute([out] boolean mute); 185 186 /** 187 * @brief Sets the audio volume for voice call. 188 * 189 * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15, 190 * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15). 191 * 192 * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0. 193 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 194 * @see GetVolume 195 */ 196 SetVoiceVolume([in] float volume); 197 198 /** 199 * @brief Sets extra audio parameters. 200 * 201 * @param key Indicates what kind of parameter type will be set. 202 * @param condition Indicates the specific extend parameter condition of AudioExtParamKey. 203 * @param value Indicates the value of the specified condition. 204 * 205 * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 206 * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this: 207 * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i> 208 * EVENT_TYPE indicates sub volume event type: SetVolume = 1; SetMute = 4; 209 * VOLUME_GROUP_ID indicates which volume group will be set; 210 * AUDIO_VOLUME_TYPE indicates which volume type will be set; 211 * 212 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 213 */ 214 SetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [in] String value); 215 216 /** 217 * @brief Get extra audio parameters. 218 * 219 * @param key Indicates what kind of parameter type will be get. 220 * @param condition Indicates the specific extend parameter condition of AudioExtParamKey. 221 * @param value Indicates the value of the specified condition. 222 * 223 * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 224 * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this: 225 * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i> 226 * EVENT_TYPE indicates sub volume event type: GetVolume = 1; GetMinVolume = 2; GetMaxVolume = 3; IsStreamMute = 4; 227 * VOLUME_GROUP_ID indicates which volume group want get; 228 * AUDIO_VOLUME_TYPE indicates which volume type want get; 229 * 230 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 231 */ 232 GetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [out] String value); 233 234 /** 235 * @brief Register extra audio parameters observer. 236 * 237 * @param audioCallback Indicates param observer. 238 * @param cookie Indicates the pointer to the callback parameters; 239 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 240 */ 241 RegExtraParamObserver([in] IAudioCallback audioCallback, [in] byte cookie); 242} 243/** @} */