1 /* 2 * Copyright (c) 2020-2021 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 namespace OHOS::HDI::Audio_Bluetooth { 42 /** 43 * @brief Provides audio adapter capabilities, including initializing ports, creating rendering and capturing tasks, 44 * and obtaining the port capability set. 45 * 46 * @see AudioRender 47 * @see AudioCapture 48 * @since 1.0 49 * @version 1.0 50 */ 51 struct AudioAdapter { 52 /** 53 * @brief Initializes all ports of an audio adapter. 54 * 55 * Call this function before calling other driver functions to check whether the initialization is complete. 56 * If the initialization is not complete, wait for a while (for example, 100 ms) and perform the check again 57 * until the port initialization is complete. 58 * 59 * @param adapter Indicates the pointer to the audio adapter to operate. 60 * @return Returns <b>0</b> if the initialization is successful; returns a negative value otherwise. 61 */ 62 int32_t (*InitAllPorts)(struct AudioAdapter *adapter); 63 64 /** 65 * @brief Creates an <b>AudioRender</b> object. 66 * 67 * @param adapter Indicates the pointer to the audio adapter to operate. 68 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 69 * @param attrs Indicates the pointer to the audio sampling attributes to open. 70 * @param render Indicates the double pointer to the <b>AudioRender</b> object. 71 * @return Returns <b>0</b> if the <b>AudioRender</b> object is created successfully; 72 * returns a negative value otherwise. 73 * @see GetPortCapability 74 * @see DestroyRender 75 */ 76 int32_t (*CreateRender)(struct AudioAdapter *adapter, const struct AudioDeviceDescriptor *desc, 77 const struct AudioSampleAttributes *attrs, struct AudioRender **render); 78 79 /** 80 * @brief Destroys an <b>AudioRender</b> object. 81 * 82 * @attention Do not destroy the object during audio rendering. 83 * 84 * @param adapter Indicates the pointer to the audio adapter to operate. 85 * @param render Indicates the pointer to the <b>AudioRender</b> object to operate. 86 * @return Returns <b>0</b> if the <b>AudioRender</b> object is destroyed; returns a negative value otherwise. 87 * @see CreateRender 88 */ 89 int32_t (*DestroyRender)(struct AudioAdapter *adapter, struct AudioRender *render); 90 91 /** 92 * @brief Obtains the capability set of the port driver for the audio adapter. 93 * 94 * @param adapter Indicates the pointer to the audio adapter to operate. 95 * @param port Indicates the pointer to the port. 96 * @param capability Indicates the pointer to the capability set to obtain. 97 * @return Returns <b>0</b> if the capability set is successfully obtained; returns a negative value otherwise. 98 */ 99 int32_t (*GetPortCapability)(struct AudioAdapter *adapter, const struct AudioPort *port, 100 struct AudioPortCapability *capability); 101 102 /** 103 * @brief Sets the passthrough data transmission mode of the audio port driver. 104 * 105 * @param adapter Indicates the pointer to the audio adapter to operate. 106 * @param port Indicates the pointer to the port. 107 * @param mode Indicates the passthrough transmission mode to set. 108 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 109 * @see GetPassthroughMode 110 */ 111 int32_t (*SetPassthroughMode)(struct AudioAdapter *adapter, const struct AudioPort *port, 112 enum AudioPortPassthroughMode mode); 113 114 /** 115 * @brief Obtains the passthrough data transmission mode of the audio port driver. 116 * 117 * @param adapter Indicates the pointer to the audio adapter to operate. 118 * @param port Indicates the pointer to the port. 119 * @param mode Indicates the pointer to the passthrough transmission mode to obtain. 120 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 121 * @see SetPassthroughMode 122 */ 123 int32_t (*GetPassthroughMode)(struct AudioAdapter *adapter, const struct AudioPort *port, 124 enum AudioPortPassthroughMode *mode); 125 126 /** 127 * @brief Sets extra audio parameters. 128 * 129 * @param adapter Indicates the audio adapter. 130 * @param key Indicates what kind of parameter type will be set. 131 * @param condition Indicates the specific extend parameter condition of AudioExtParamKey. 132 * @param value Indicates the value of the specified condition. 133 * 134 * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 135 * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this: 136 * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i> 137 * EVENT_TYPE indicates sub volume event type: SetVolume = 1; SetMute = 4; 138 * VOLUME_GROUP_ID indicates which volume group will be set; 139 * AUDIO_VOLUME_TYPE indicates which volume type will be set; 140 * 141 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 142 */ 143 int32_t (*SetExtraParams)(struct AudioAdapter *adapter, enum AudioExtParamKey key, 144 const char *condition, const char *value); 145 146 /** 147 * @brief Get extra audio parameters. 148 * 149 * @param adapter Indicates the audio adapter. 150 * @param key Indicates what kind of parameter type will be get. 151 * @param condition Indicates the specific extend parameter condition of AudioExtParamKey. 152 * @param value Indicates the value of the specified condition. 153 * @param lenth Indicates the length of the value pointer. 154 * 155 * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 156 * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this: 157 * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i> 158 * EVENT_TYPE indicates sub volume event type: GetVolume = 1; GetMinVolume = 2; GetMaxVolume = 3; IsStreamMute = 4; 159 * VOLUME_GROUP_ID indicates which volume group want get; 160 * AUDIO_VOLUME_TYPE indicates which volume type want get; 161 * 162 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 163 */ 164 int32_t (*GetExtraParams)(struct AudioAdapter *adapter, enum AudioExtParamKey key, 165 const char *condition, char *value, int32_t lenth); 166 }; 167 } 168 #endif /* AUDIO_ADAPTER_H */ 169 /** @} */ 170