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
41namespace 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 */
49struct 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