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 #include "audio_capture.h" 42 43 /** 44 * @brief Provides audio adapter capabilities, including initializing ports, creating rendering and capturing tasks, 45 * and obtaining the port capability set. 46 * 47 * @see AudioRender 48 * @see AudioCapture 49 * @since 1.0 50 * @version 1.0 51 */ 52 struct AudioAdapter { 53 /** 54 * @brief Initializes all ports of an audio adapter. 55 * 56 * Call this function before calling other driver functions to check whether the initialization is complete. 57 * If the initialization is not complete, wait for a while (for example, 100 ms) and perform the check again 58 * until the port initialization is complete. 59 * 60 * @param adapter Indicates the pointer to the audio adapter to operate. 61 * @return Returns <b>0</b> if the initialization is successful; returns a negative value otherwise. 62 */ 63 int32_t (*InitAllPorts)(struct AudioAdapter *adapter); 64 65 /** 66 * @brief Creates an <b>AudioRender</b> object. 67 * 68 * @param adapter Indicates the pointer to the audio adapter to operate. 69 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 70 * @param attrs Indicates the pointer to the audio sampling attributes to open. 71 * @param render Indicates the double pointer to the <b>AudioRender</b> object. 72 * @return Returns <b>0</b> if the <b>AudioRender</b> object is created successfully; 73 * returns a negative value otherwise. 74 * @see GetPortCapability 75 * @see DestroyRender 76 */ 77 int32_t (*CreateRender)(struct AudioAdapter *adapter, const struct AudioDeviceDescriptor *desc, 78 const struct AudioSampleAttributes *attrs, struct AudioRender **render); 79 80 /** 81 * @brief Destroys an <b>AudioRender</b> object. 82 * 83 * @attention Do not destroy the object during audio rendering. 84 * 85 * @param adapter Indicates the pointer to the audio adapter to operate. 86 * @param render Indicates the pointer to the <b>AudioRender</b> object to operate. 87 * @return Returns <b>0</b> if the <b>AudioRender</b> object is destroyed; returns a negative value otherwise. 88 * @see CreateRender 89 */ 90 int32_t (*DestroyRender)(struct AudioAdapter *adapter, struct AudioRender *render); 91 92 /** 93 * @brief Creates an <b>AudioCapture</b> object. 94 * 95 * @param adapter Indicates the pointer to the audio adapter to operate. 96 * @param desc Indicates the pointer to the descriptor of the audio adapter to start. 97 * @param attrs Indicates the pointer to the audio sampling attributes to open. 98 * @param capture Indicates the double pointer to the <b>AudioCapture</b> object. 99 * @return Returns <b>0</b> if the <b>AudioCapture</b> object is created successfully; 100 * returns a negative value otherwise. 101 * @see GetPortCapability 102 * @see DestroyCapture 103 */ 104 int32_t (*CreateCapture)(struct AudioAdapter *adapter, const struct AudioDeviceDescriptor *desc, 105 const struct AudioSampleAttributes *attrs, struct AudioCapture **capture); 106 107 /** 108 * @brief Destroys an <b>AudioCapture</b> object. 109 * 110 * @attention Do not destroy the object during audio capturing. 111 * 112 * @param adapter Indicates the pointer to the audio adapter to operate. 113 * @param capture Indicates the pointer to the <b>AudioCapture</b> object to operate. 114 * @return Returns <b>0</b> if the <b>AudioCapture</b> object is destroyed; returns a negative value otherwise. 115 * @see CreateCapture 116 */ 117 int32_t (*DestroyCapture)(struct AudioAdapter *adapter, struct AudioCapture *capture); 118 119 /** 120 * @brief Obtains the capability set of the port driver for the audio adapter. 121 * 122 * @param adapter Indicates the pointer to the audio adapter to operate. 123 * @param port Indicates the pointer to the port. 124 * @param capability Indicates the pointer to the capability set to obtain. 125 * @return Returns <b>0</b> if the capability set is successfully obtained; returns a negative value otherwise. 126 */ 127 int32_t (*GetPortCapability)(struct AudioAdapter *adapter, const struct AudioPort *port, 128 struct AudioPortCapability *capability); 129 130 /** 131 * @brief Sets the passthrough data transmission mode of the audio port driver. 132 * 133 * @param adapter Indicates the pointer to the audio adapter to operate. 134 * @param port Indicates the pointer to the port. 135 * @param mode Indicates the passthrough transmission mode to set. 136 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 137 * @see GetPassthroughMode 138 */ 139 int32_t (*SetPassthroughMode)(struct AudioAdapter *adapter, const struct AudioPort *port, 140 enum AudioPortPassthroughMode mode); 141 142 /** 143 * @brief Obtains the passthrough data transmission mode of the audio port driver. 144 * 145 * @param adapter Indicates the pointer to the audio adapter to operate. 146 * @param port Indicates the pointer to the port. 147 * @param mode Indicates the pointer to the passthrough transmission mode to obtain. 148 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 149 * @see SetPassthroughMode 150 */ 151 int32_t (*GetPassthroughMode)(struct AudioAdapter *adapter, const struct AudioPort *port, 152 enum AudioPortPassthroughMode *mode); 153 }; 154 155 #endif /* AUDIO_ADAPTER_H */ 156 /** @} */ 157