1 /* 2 * Copyright (c) 2022 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 Audio 18 * @{ 19 * 20 * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, 21 * accessing a driver adapter, and rendering and capturing audios. 22 * 23 * @since 1.0 24 * @version 1.0 25 */ 26 27 /** 28 * @file audio_adapter.h 29 * 30 * @brief Declares APIs for operations related to the audio adapter. 31 * 32 * @since 1.0 33 * @version 1.0 34 */ 35 36 #ifndef AUDIO_ADAPTER_H 37 #define AUDIO_ADAPTER_H 38 39 #include "audio_types.h" 40 #include "audio_render.h" 41 #include "audio_capture.h" 42 43 namespace OHOS { 44 /** 45 * @brief Provides audio adapter capabilities, including initializing ports, creating rendering and capturing tasks, 46 * and obtaining the port capability set. 47 * 48 * @see AudioRender 49 * @see AudioCapture 50 * @since 1.0 51 * @version 1.0 52 */ 53 struct AudioAdapter { 54 /** 55 * @brief Initializes all ports of an audio adapter. 56 * 57 * Call this function before calling other driver functions to check whether the initialization is complete. 58 * If the initialization is not complete, wait for a while (for example, 100 ms) and perform the check again 59 * until the port initialization is complete. 60 * 61 * @param adapter Indicates the pointer to the audio adapter to operate. 62 * @return Returns <b>0</b> if the initialization is successful; returns a negative value otherwise. 63 */ 64 int32_t (*InitAllPorts)(struct AudioAdapter *adapter); 65 66 /** 67 * @brief Creates an <b>AudioRender</b> object. 68 * 69 * @param adapter Indicates the pointer to the audio adapter to operate. 70 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 71 * @param attrs Indicates the pointer to the audio sampling attributes to open. 72 * @param render Indicates the double pointer to the <b>AudioRender</b> object. 73 * @return Returns <b>0</b> if the <b>AudioRender</b> object is created successfully; 74 * returns a negative value otherwise. 75 * @see GetPortCapability 76 * @see DestroyRender 77 */ 78 int32_t (*CreateRender)(struct AudioAdapter *adapter, const struct AudioDeviceDescriptor *desc, 79 const struct AudioSampleAttributes *attrs, struct AudioRender **render); 80 81 /** 82 * @brief Destroys an <b>AudioRender</b> object. 83 * 84 * @attention Do not destroy the object during audio rendering. 85 * 86 * @param adapter Indicates the pointer to the audio adapter to operate. 87 * @param render Indicates the pointer to the <b>AudioRender</b> object to operate. 88 * @return Returns <b>0</b> if the <b>AudioRender</b> object is destroyed; returns a negative value otherwise. 89 * @see CreateRender 90 */ 91 int32_t (*DestroyRender)(struct AudioAdapter *adapter, struct AudioRender *render); 92 93 /** 94 * @brief Creates an <b>AudioCapture</b> object. 95 * 96 * @param adapter Indicates the pointer to the audio adapter to operate. 97 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 98 * @param attrs Indicates the pointer to the audio sampling attributes to open. 99 * @param capture Indicates the double pointer to the <b>AudioCapture</b> object. 100 * @return Returns <b>0</b> if the <b>AudioCapture</b> object is created successfully; 101 * returns a negative value otherwise. 102 * @see GetPortCapability 103 * @see DestroyCapture 104 */ 105 int32_t (*CreateCapture)(struct AudioAdapter *adapter, const struct AudioDeviceDescriptor *desc, 106 const struct AudioSampleAttributes *attrs, struct AudioCapture **capture); 107 108 /** 109 * @brief Destroys an <b>AudioCapture</b> object. 110 * 111 * @attention Do not destroy the object during audio capturing. 112 * 113 * @param adapter Indicates the pointer to the audio adapter to operate. 114 * @param capture Indicates the pointer to the <b>AudioCapture</b> object to operate. 115 * @return Returns <b>0</b> if the <b>AudioCapture</b> object is destroyed; returns a negative value otherwise. 116 * @see CreateCapture 117 */ 118 int32_t (*DestroyCapture)(struct AudioAdapter *adapter, struct AudioCapture *capture); 119 120 /** 121 * @brief Obtains the capability set of the port driver for the audio adapter. 122 * 123 * @param adapter Indicates the pointer to the audio adapter to operate. 124 * @param port Indicates the pointer to the port. 125 * @param capability Indicates the pointer to the capability set to obtain. 126 * @return Returns <b>0</b> if the capability set is successfully obtained; returns a negative value otherwise. 127 */ 128 int32_t (*GetPortCapability)(struct AudioAdapter *adapter, const struct AudioPort *port, 129 struct AudioPortCapability *capability); 130 131 /** 132 * @brief Sets the passthrough data transmission mode of the audio port driver. 133 * 134 * @param adapter Indicates the pointer to the audio adapter to operate. 135 * @param port Indicates the pointer to the port. 136 * @param mode Indicates the passthrough transmission mode to set. 137 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 138 * @see GetPassthroughMode 139 */ 140 int32_t (*SetPassthroughMode)(struct AudioAdapter *adapter, const struct AudioPort *port, 141 enum AudioPortPassthroughMode mode); 142 143 /** 144 * @brief Obtains the passthrough data transmission mode of the audio port driver. 145 * 146 * @param adapter Indicates the pointer to the audio adapter to operate. 147 * @param port Indicates the pointer to the port. 148 * @param mode Indicates the pointer to the passthrough transmission mode to obtain. 149 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 150 * @see SetPassthroughMode 151 */ 152 int32_t (*GetPassthroughMode)(struct AudioAdapter *adapter, const struct AudioPort *port, 153 enum AudioPortPassthroughMode *mode); 154 155 /** 156 * @brief Update audio route on several source and sink ports. 157 * 158 * @param adapter Indicates the pointer to the audio adapter to operate. 159 * @param route Indicates route information. 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 int32_t (*UpdateAudioRoute)(struct AudioAdapter *adapter, const struct AudioRoute *route, int32_t *routeHandle); 165 166 /** 167 * @brief Release an audio route. 168 * 169 * @param adapter Indicates the pointer to the audio adapter to operate. 170 * @param routeHandle Indicates route handle. 171 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 172 * @see SetPassthroughMode 173 */ 174 int32_t (*ReleaseAudioRoute)(struct AudioAdapter *adapter, int32_t routeHandle); 175 176 /** 177 * @brief Sets the mute operation for the audio. 178 * 179 * @param adapter Indicates the pointer to the audio adapter to operate. 180 * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio, 181 * and <b>false</b> means the opposite. 182 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 183 * @see GetMute 184 */ 185 int32_t (*SetMicMute)(struct AudioAdapter *adapter, bool mute); 186 187 /** 188 * @brief Obtains the mute operation set for the audio. 189 * 190 * @param adapter Indicates the pointer to the audio adapter to operate. 191 * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that 192 * the audio is muted, and <b>false</b> means the opposite. 193 * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise. 194 * @see SetMute 195 */ 196 int32_t (*GetMicMute)(struct AudioAdapter *adapter, bool *mute); 197 198 /** 199 * @brief Sets the audio volume for voice call. 200 * 201 * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15, 202 * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15). 203 * 204 * @param adapter Indicates the pointer to the audio adapter to operate. 205 * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0. 206 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 207 * @see GetVolume 208 */ 209 int32_t (*SetVoiceVolume)(struct AudioAdapter *adapter, float volume); 210 211 /** 212 * @brief Sets extra audio parameters. 213 * 214 * @param adapter Indicates the audio adapter. 215 * @param key Indicates what kind of parameter type will be set. 216 * @param condition Indicates the specific extend parameter condition of AudioExtParamKey. 217 * @param value Indicates the value of the specified condition. 218 * 219 * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 220 * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this: 221 * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i> 222 * EVENT_TYPE indicates sub volume event type: SetVolume = 1; SetMute = 4; 223 * VOLUME_GROUP_ID indicates which volume group will be set; 224 * AUDIO_VOLUME_TYPE indicates which volume type will be set; 225 * 226 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 227 */ 228 int32_t (*SetExtraParams)(struct AudioAdapter *adapter, enum AudioExtParamKey key, 229 const char *condition, const char *value); 230 231 /** 232 * @brief Get extra audio parameters. 233 * 234 * @param adapter Indicates the audio adapter. 235 * @param key Indicates what kind of parameter type will be get. 236 * @param condition Indicates the specific extend parameter condition of AudioExtParamKey. 237 * @param value Indicates the value of the specified condition. 238 * @param lenth Indicates the length of the value pointer. 239 * 240 * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 241 * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this: 242 * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i> 243 * EVENT_TYPE indicates sub volume event type: GetVolume = 1; GetMinVolume = 2; GetMaxVolume = 3; IsStreamMute = 4; 244 * VOLUME_GROUP_ID indicates which volume group want get; 245 * AUDIO_VOLUME_TYPE indicates which volume type want get; 246 * 247 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 248 */ 249 int32_t (*GetExtraParams)(struct AudioAdapter *adapter, enum AudioExtParamKey key, 250 const char *condition, char *value, int32_t lenth); 251 252 /** 253 * @brief Register extra audio parameters observer. 254 * 255 * @param adapter Indicates the audio adapter. 256 * @param callback Indicates param observer. 257 * @param cookie Indicates the pointer to the callback parameters; 258 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 259 */ 260 int32_t (*RegExtraParamObserver)(struct AudioAdapter *adapter, ParamCallback callback, void* cookie); 261 /** 262 * @brief Get the device status of an adapter. 263 * 264 * @param adapter Indicates the audio adapter. 265 * @param status Indicates the status of device . 266 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 267 */ 268 int32_t (*GetDeviceStatus)(struct AudioAdapter *adapter, struct AudioDeviceStatus *status); 269 }; 270 } /* end of OHOS */ 271 #endif /* AUDIO_ADAPTER_H */ 272 /** @} */ 273