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_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 
41 namespace OHOS {
42 /**
43  * @brief Provides attribute-related APIs for audio rendering or capturing, including functions to
44  * obtain frame information and set audio sampling attributes.
45  *
46  * @since 1.0
47  * @version 1.0
48  */
49 struct AudioAttribute {
50     /**
51      * @brief Obtains the audio frame size, that is, the length (in bytes) of a frame.
52      *
53      * @param handle Indicates the audio handle.
54      * @param size Indicates the pointer to the audio frame size (in bytes).
55      * @return Returns <b>0</b> if the audio frame size is obtained; returns a negative value otherwise.
56      */
57     int32_t (*GetFrameSize)(AudioHandle handle, uint64_t *size);
58 
59     /**
60      * @brief Obtains the number of audio frames in the audio buffer.
61      *
62      * @param handle Indicates the audio handle.
63      * @param count Indicates the pointer to the number of audio frames in the audio buffer.
64      * @return Returns <b>0</b> if the number of audio frames is obtained; returns a negative value otherwise.
65      */
66     int32_t (*GetFrameCount)(AudioHandle handle, uint64_t *count);
67 
68     /**
69      * @brief Sets audio sampling attributes.
70      *
71      * @param handle Indicates the audio handle.
72      * @param attrs Indicates the pointer to the audio sampling attributes to set, such as the sampling rate,
73      * sampling precision, and channel.
74      * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
75      * @see GetSampleAttributes
76      */
77     int32_t (*SetSampleAttributes)(AudioHandle handle, const struct AudioSampleAttributes *attrs);
78 
79     /**
80      * @brief Obtains audio sampling attributes.
81      *
82      * @param handle Indicates the audio handle.
83      * @param attrs Indicates the pointer to the audio sampling attributes, such as the sampling rate,
84      * sampling precision, and channel.
85      * @return Returns <b>0</b> if audio sampling attributes are obtained; returns a negative value otherwise.
86      * @see SetSampleAttributes
87      */
88     int32_t (*GetSampleAttributes)(AudioHandle handle, struct AudioSampleAttributes *attrs);
89 
90     /**
91      * @brief Obtains the data channel ID of the audio.
92      *
93      * @param handle Indicates the audio handle.
94      * @param channelId Indicates the pointer to the data channel ID.
95      * @return Returns <b>0</b> if the data channel ID is obtained; returns a negative value otherwise.
96      */
97     int32_t (*GetCurrentChannelId)(AudioHandle handle, uint32_t *channelId);
98 
99     /**
100      * @brief Sets extra audio parameters.
101      *
102      * @param handle Indicates the audio handle.
103      * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters.
104      * The format is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
105      * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
106      */
107     int32_t (*SetExtraParams)(AudioHandle handle, const char *keyValueList);
108 
109     /**
110      * @brief Obtains extra audio parameters.
111      *
112      * @param handle Indicates the audio handle.
113      * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters.
114      * The format is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
115      * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
116      */
117     int32_t (*GetExtraParams)(AudioHandle handle, char *keyValueList, int32_t listLenth);
118 
119     /**
120      * @brief Requests a mmap buffer.
121      *
122      * @param handle Indicates the audio handle.
123      * @param reqSize Indicates the size of the request mmap buffer.
124      * @param desc Indicates the pointer to the mmap buffer descriptor.
125      * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
126      */
127     int32_t (*ReqMmapBuffer)(AudioHandle handle, int32_t reqSize, struct AudioMmapBufferDescriptor *desc);
128 
129     /**
130      * @brief Obtains the read/write position of the current mmap buffer.
131      *
132      * @param handle Indicates the audio handle.
133      * @param frames Indicates the pointer to the frame where the read/write starts.
134      * @param time Indicates the pointer to the timestamp associated with the frame where the read/write starts.
135      * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
136      */
137     int32_t (*GetMmapPosition)(AudioHandle handle, uint64_t *frames, struct AudioTimeStamp *time);
138 
139     /**
140      * @brief Add the audio effect which the effectid indicated.
141      *
142      * @param handle Indicates the audio handle.
143      * @param effectid Indicates the audio effect instance identifier which is going to be added.
144      * @return Returns <b>0</b> if the audio effect were added succesffully; returns a negative value otherwise.
145      */
146     int32_t (*AddAudioEffect)(AudioHandle handle, uint64_t effectid);
147 
148     /**
149      * @brief Remove the audio effect which the effectid indicated.
150      *
151      * @param handle Indicates the audio handle.
152      * @param effectid Indicates the audio effect which is going to be removed.
153      * @return Returns <b>0</b> if the audio effect were removed succesffully; returns a negative value otherwise.
154      */
155     int32_t (*RemoveAudioEffect)(AudioHandle handle, uint64_t effectid);
156 
157 	/**
158      * @brief Get the buffer size of render or capturer
159      *
160      * @param handle Indicates the audio handle.
161      * @param bufferSize Indicates the buffer size (in bytes) queried from the vendor
162      * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
163      */
164     int32_t (*GetFrameBufferSize)(AudioHandle handle, uint64_t *bufferSize);
165 };
166 } /* end of OHOS */
167 #endif /* AUDIO_ATTRIBUTE_H */
168 /** @} */
169