1/*
2 * Copyright (C) 2023 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#ifndef NATIVE_AVCODEC_AUDIODECODER_H
17#define NATIVE_AVCODEC_AUDIODECODER_H
18
19#include <stdint.h>
20#include <stdio.h>
21#include "native_avcodec_base.h"
22
23#ifdef __cplusplus
24extern "C" {
25#endif
26
27/**
28 * @brief Creates an audio decoder instance from the mime type, which is recommended in most cases.
29 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
30 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE}
31 * @return Returns a Pointer to an OH_AVCodec instance
32 * @deprecated since 11
33 * @useinstead OH_AudioCodec_CreateByMime
34 * @since 9
35 * @version 1.0
36 */
37OH_AVCodec *OH_AudioDecoder_CreateByMime(const char *mime);
38
39/**
40 * @brief Create an audio decoder instance through the audio decoder name.
41 * The premise of using this interface is to know the exact name of the decoder.
42 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
43 * @param name Audio codec name
44 * @return Returns a Pointer to an OH_AVCodec instance
45 * @deprecated since 11
46 * @useinstead OH_AudioCodec_CreateByName
47 * @since 9
48 * @version 1.0
49 */
50OH_AVCodec *OH_AudioDecoder_CreateByName(const char *name);
51
52/**
53 * @brief Clear the internal resources of the decoder and destroy the decoder instance
54 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
55 * @param codec Pointer to an OH_AVCodec instance
56 * @return Returns AV_ERR_OK if the execution is successful,
57 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
58 * @deprecated since 11
59 * @useinstead OH_AudioCodec_Destroy
60 * @since 9
61 * @version 1.0
62 */
63OH_AVErrCode OH_AudioDecoder_Destroy(OH_AVCodec *codec);
64
65/**
66 * @brief Set the asynchronous callback function so that your application
67 * can respond to the events generated by the audio decoder. This interface must be called before Prepare is called.
68 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
69 * @param codec Pointer to an OH_AVCodec instance
70 * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback}
71 * @param userData User specific data
72 * @return Returns AV_ERR_OK if the execution is successful,
73 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
74 * @deprecated since 11
75 * @useinstead OH_AudioCodec_RegisterCallback
76 * @since 9
77 * @version 1.0
78 */
79OH_AVErrCode OH_AudioDecoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData);
80
81/**
82 * @brief To configure the audio decoder, typically, you need to configure the description information of the decoded
83 * audio track, which can be extracted from the OH_AVSource. This interface must be called before Prepare is called.
84 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
85 * @param codec Pointer to an OH_AVCodec instance
86 * @param format A pointer to an OH_AVFormat giving a description of the audio track to be decoded
87 * @return Returns AV_ERR_OK if the execution is successful,
88 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
89 * @deprecated since 11
90 * @useinstead OH_AudioCodec_Configure
91 * @since 9
92 * @version 1.0
93 */
94OH_AVErrCode OH_AudioDecoder_Configure(OH_AVCodec *codec, OH_AVFormat *format);
95
96/**
97 * @brief To prepare the internal resources of the decoder, the Configure interface must be called
98 * before calling this interface.
99 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
100 * @param codec Pointer to an OH_AVCodec instance
101 * @return Returns AV_ERR_OK if the execution is successful,
102 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
103 * @deprecated since 11
104 * @useinstead OH_AudioCodec_Prepare
105 * @since 9
106 * @version 1.0
107 */
108OH_AVErrCode OH_AudioDecoder_Prepare(OH_AVCodec *codec);
109
110/**
111 * @brief Start the decoder, this interface must be called after the Prepare is successful.
112 * After being successfully started, the decoder will start reporting NeedInputData events.
113 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
114 * @param codec Pointer to an OH_AVCodec instance
115 * @return Returns AV_ERR_OK if the execution is successful,
116 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
117 * @deprecated since 11
118 * @useinstead OH_AudioCodec_Start
119 * @since 9
120 * @version 1.0
121 */
122OH_AVErrCode OH_AudioDecoder_Start(OH_AVCodec *codec);
123
124/**
125 * @brief Stop the decoder. After stopping, you can re-enter the Started state through Start,
126 * but it should be noted that need to re-enter if the decoder has been input before
127 * Codec-Specific-Data.
128 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
129 * @param codec Pointer to an OH_AVCodec instance
130 * @return Returns AV_ERR_OK if the execution is successful,
131 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
132 * @deprecated since 11
133 * @useinstead OH_AudioCodec_Stop
134 * @since 9
135 * @version 1.0
136 */
137OH_AVErrCode OH_AudioDecoder_Stop(OH_AVCodec *codec);
138
139/**
140 * @brief Clear the input and output data buffered in the decoder. After this interface is called, all the Buffer
141 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access
142 * the Buffers corresponding to these indexes.
143 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
144 * @param codec Pointer to an OH_AVCodec instance
145 * @return Returns AV_ERR_OK if the execution is successful,
146 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
147 * @deprecated since 11
148 * @useinstead OH_AudioCodec_Flush
149 * @since 9
150 * @version 1.0
151 */
152OH_AVErrCode OH_AudioDecoder_Flush(OH_AVCodec *codec);
153
154/**
155 * @brief Reset the decoder. To continue decoding, you need to call the Configure interface again to
156 * configure the decoder instance.
157 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
158 * @param codec Pointer to an OH_AVCodec instance
159 * @return Returns AV_ERR_OK if the execution is successful,
160 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
161 * @deprecated since 11
162 * @useinstead OH_AudioCodec_Reset
163 * @since 9
164 * @version 1.0
165 */
166
167OH_AVErrCode OH_AudioDecoder_Reset(OH_AVCodec *codec);
168
169/**
170 * @brief Get the description information of the output data of the decoder, refer to {@link OH_AVFormat} for details.
171 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to
172 * be manually released by the caller
173 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
174 * @param codec Pointer to an OH_AVCodec instance
175 * @return Returns the OH_AVFormat handle pointer, the life cycle is refreshed with the next GetOutputMediaDescription,
176 * or destroyed with OH_AVCodec;
177 * @deprecated since 11
178 * @useinstead OH_AudioCodec_GetOutputDescription
179 * @since 9
180 * @version 1.0
181 */
182OH_AVFormat *OH_AudioDecoder_GetOutputDescription(OH_AVCodec *codec);
183
184/**
185 * @brief Set dynamic parameters to the decoder. Note: This interface can only be called after the decoder is started.
186 * At the same time, incorrect parameter settings may cause decoding failure.
187 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
188 * @param codec Pointer to an OH_AVCodec instance
189 * @param format OH_AVFormat handle pointer
190 * @return Returns AV_ERR_OK if the execution is successful,
191 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
192 * @deprecated since 11
193 * @useinstead OH_AudioCodec_SetParameter
194 * @since 9
195 * @version 1.0
196 */
197OH_AVErrCode OH_AudioDecoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format);
198
199/**
200 * @brief Submit the input buffer filled with data to the audio decoder. The {@link OH_AVCodecOnNeedInputData} callback
201 * will report the available input buffer and the corresponding index value. Once the buffer with the specified index
202 * is submitted to the audio decoder, the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputData}
203 * callback is received again reporting that the buffer with the same index is available. In addition, for some
204 * decoders, it is required to input Codec-Specific-Data to the decoder at the beginning to initialize the decoding
205 * process of the decoder.
206 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
207 * @param codec Pointer to an OH_AVCodec instance
208 * @param index Enter the index value corresponding to the Buffer
209 * @param attr Information describing the data contained in the Buffer
210 * @return Returns AV_ERR_OK if the execution is successful,
211 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
212 * @deprecated since 11
213 * @useinstead OH_AudioCodec_PushInputBuffer
214 * @since 9
215 * @version 1.0
216 */
217OH_AVErrCode OH_AudioDecoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr);
218
219/**
220 * @brief Return the processed output Buffer to the decoder.
221 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
222 * @param codec Pointer to an OH_AVCodec instance
223 * @param index The index value corresponding to the output Buffer
224 * @return Returns AV_ERR_OK if the execution is successful,
225 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
226 * @deprecated since 11
227 * @useinstead OH_AudioCodec_FreeOutputBuffer
228 * @since 9
229 * @version 1.0
230 */
231OH_AVErrCode OH_AudioDecoder_FreeOutputData(OH_AVCodec *codec, uint32_t index);
232
233/**
234 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app
235 * switchback from the background
236 * @syscap SystemCapability.Multimedia.Media.AudioDecoder
237 * @param codec Pointer to an OH_AVCodec instance
238 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid,
239 * false if the codec instance is invalid
240 * @return Returns AV_ERR_OK if the execution is successful,
241 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
242 * @deprecated since 11
243 * @useinstead OH_AudioCodec_IsValid
244 * @since 10
245 */
246OH_AVErrCode OH_AudioDecoder_IsValid(OH_AVCodec *codec, bool *isValid);
247
248#ifdef __cplusplus
249}
250#endif
251#endif // NATIVE_AVCODEC_AUDIODECODER_H