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
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 */
48struct 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     * @brief Add the audio effect which the effectid indicated.
140     *
141     * @param handle Indicates the audio handle.
142     * @param effectid Indicates the audio effect instance identifier which is going to be added.
143     * @return Returns <b>0</b> if the audio effect were added succesffully; returns a negative value otherwise.
144     */
145    int32_t (*AddAudioEffect)(AudioHandle handle, uint64_t effectid);
146
147    /**
148     * @brief Remove the audio effect which the effectid indicated.
149     *
150     * @param handle Indicates the audio handle.
151     * @param effectid Indicates the audio effect which is going to be removed.
152     * @return Returns <b>0</b> if the audio effect were removed succesffully; returns a negative value otherwise.
153     */
154    int32_t (*RemoveAudioEffect)(AudioHandle handle, uint64_t effectid);
155
156	/**
157     * @brief Get the buffer size of render or capturer
158     *
159     * @param handle Indicates the audio handle.
160     * @param bufferSize Indicates the buffer size (in bytes) queried from the vendor
161     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
162     */
163    int32_t (*GetFrameBufferSize)(AudioHandle handle, uint64_t *bufferSize);
164};
165
166#endif /* AUDIO_ATTRIBUTE_H */
167/** @} */
168