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_attribute.h 29 * 30 * @brief Declares APIs for audio attributes. 31 * 32 * @since 1.0 33 * @version 1.0 34 */ 35 36 #ifndef AUDIO_ATTRIBUTE_H 37 #define AUDIO_ATTRIBUTE_H 38 39 #include "audio_types.h" 40 namespace OHOS::HDI::Audio_Bluetooth { 41 /** 42 * @brief Provides attribute-related APIs for audio rendering or capturing, including functions to 43 * obtain frame information and set audio sampling attributes. 44 * 45 * @since 1.0 46 * @version 1.0 47 */ 48 struct AudioAttribute { 49 /** 50 * @brief Obtains the audio frame size, that is, the length (in bytes) of a frame. 51 * 52 * @param handle Indicates the audio handle. 53 * @param size Indicates the pointer to the audio frame size (in bytes). 54 * @return Returns <b>0</b> if the audio frame size is obtained; returns a negative value otherwise. 55 */ 56 int32_t (*GetFrameSize)(AudioHandle handle, uint64_t *size); 57 58 /** 59 * @brief Obtains the number of audio frames in the audio buffer. 60 * 61 * @param handle Indicates the audio handle. 62 * @param count Indicates the pointer to the number of audio frames in the audio buffer. 63 * @return Returns <b>0</b> if the number of audio frames is obtained; returns a negative value otherwise. 64 */ 65 int32_t (*GetFrameCount)(AudioHandle handle, uint64_t *count); 66 67 /** 68 * @brief Sets audio sampling attributes. 69 * 70 * @param handle Indicates the audio handle. 71 * @param attrs Indicates the pointer to the audio sampling attributes to set, such as the sampling rate, 72 * sampling precision, and channel. 73 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 74 * @see GetSampleAttributes 75 */ 76 int32_t (*SetSampleAttributes)(AudioHandle handle, const struct AudioSampleAttributes *attrs); 77 78 /** 79 * @brief Obtains audio sampling attributes. 80 * 81 * @param handle Indicates the audio handle. 82 * @param attrs Indicates the pointer to the audio sampling attributes, such as the sampling rate, 83 * sampling precision, and channel. 84 * @return Returns <b>0</b> if audio sampling attributes are obtained; returns a negative value otherwise. 85 * @see SetSampleAttributes 86 */ 87 int32_t (*GetSampleAttributes)(AudioHandle handle, struct AudioSampleAttributes *attrs); 88 89 /** 90 * @brief Obtains the data channel ID of the audio. 91 * 92 * @param handle Indicates the audio handle. 93 * @param channelId Indicates the pointer to the data channel ID. 94 * @return Returns <b>0</b> if the data channel ID is obtained; returns a negative value otherwise. 95 */ 96 int32_t (*GetCurrentChannelId)(AudioHandle handle, uint32_t *channelId); 97 98 /** 99 * @brief Sets extra audio parameters. 100 * 101 * @param handle Indicates the audio handle. 102 * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters. 103 * The format is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 104 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 105 */ 106 int32_t (*SetExtraParams)(AudioHandle handle, const char *keyValueList); 107 108 /** 109 * @brief Obtains extra audio parameters. 110 * 111 * @param handle Indicates the audio handle. 112 * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters. 113 * The format is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 114 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 115 */ 116 int32_t (*GetExtraParams)(AudioHandle handle, char *keyValueList, int32_t listLenth); 117 118 /** 119 * @brief Requests a mmap buffer. 120 * 121 * @param handle Indicates the audio handle. 122 * @param reqSize Indicates the size of the request mmap buffer. 123 * @param desc Indicates the pointer to the mmap buffer descriptor. 124 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 125 */ 126 int32_t (*ReqMmapBuffer)(AudioHandle handle, int32_t reqSize, struct AudioMmapBufferDescriptor *desc); 127 128 /** 129 * @brief Obtains the read/write position of the current mmap buffer. 130 * 131 * @param handle Indicates the audio handle. 132 * @param frames Indicates the pointer to the frame where the read/write starts. 133 * @param time Indicates the pointer to the timestamp associated with the frame where the read/write starts. 134 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 135 */ 136 int32_t (*GetMmapPosition)(AudioHandle handle, uint64_t *frames, struct AudioTimeStamp *time); 137 }; 138 } 139 #endif /* AUDIO_ATTRIBUTE_H */ 140 /** @} */ 141