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/**
17 * @file native_avformat.h
18 *
19 * @brief Provides audio and video format.
20 *
21 * @kit AVCodecKit
22 * @library libnative_media_core.so
23 * @syscap SystemCapability.Multimedia.Media.Core
24 * @since 9
25 */
26
27#ifndef NATIVE_AVFORMAT_H
28#define NATIVE_AVFORMAT_H
29
30#include <stdint.h>
31#include <stdbool.h>
32#include <stdio.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/**
39 * @brief Forward declaration of OH_AVFormat.
40 *
41 * @since 9
42 */
43typedef struct OH_AVFormat OH_AVFormat;
44
45/**
46 * @brief Enumerates AVPixel Format.
47 * @syscap SystemCapability.Multimedia.Media.Core
48 * @since 9
49 * @version 1.0
50 */
51typedef enum OH_AVPixelFormat {
52    /**
53     * yuv 420 planar.
54     */
55    AV_PIXEL_FORMAT_YUVI420 = 1,
56    /**
57     *  NV12. yuv 420 semiplanar.
58     */
59    AV_PIXEL_FORMAT_NV12 = 2,
60    /**
61     *  NV21. yvu 420 semiplanar.
62     */
63    AV_PIXEL_FORMAT_NV21 = 3,
64    /**
65     * format from surface.
66     */
67    AV_PIXEL_FORMAT_SURFACE_FORMAT = 4,
68    /**
69     * RGBA8888
70     */
71    AV_PIXEL_FORMAT_RGBA = 5,
72} OH_AVPixelFormat;
73
74/**
75 * @briefCreate an OH_AVFormat handle pointer to read and write data
76 * @syscap SystemCapability.Multimedia.Media.Core
77 * @return Returns a pointer to an OH_AVFormat instance
78 * @since 9
79 * @version 1.0
80 */
81struct OH_AVFormat *OH_AVFormat_Create(void);
82
83/**
84 * @briefCreate an audio OH_AVFormat handle pointer to read and write data
85 * @syscap SystemCapability.Multimedia.Media.Core
86 * @param mimeType mime type
87 * @param sampleRate sample rate
88 * @param channelCount channel count
89 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr
90 * Possible failure causes: 1. mimeType is nullptr. 2. new format is nullptr.
91 * @since 10
92 * @version 1.0
93 */
94struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType,
95                                                  int32_t sampleRate,
96                                                  int32_t channelCount);
97
98/**
99 * @briefCreate an video OH_AVFormat handle pointer to read and write data
100 * @syscap SystemCapability.Multimedia.Media.Core
101 * @param mimeType mime type
102 * @param width width
103 * @param height height
104 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr
105 * Possible failure causes: 1. mimeType is nullptr. 2. new format is nullptr.
106 * @since 10
107 * @version 1.0
108 */
109struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType,
110                                                  int32_t width,
111                                                  int32_t height);
112
113/**
114 * @brief Destroy the specified OH_AVFormat handle resource
115 * @syscap SystemCapability.Multimedia.Media.Core
116 * @param format pointer to an OH_AVFormat instance
117 * @return void
118 * @since 9
119 * @version 1.0
120 */
121void OH_AVFormat_Destroy(struct OH_AVFormat *format);
122
123/**
124 * @brief Copy OH_AVFormat handle resource
125 * @syscap SystemCapability.Multimedia.Media.Core
126 * @param to OH_AVFormat handle pointer to receive data
127 * @param from pointer to the OH_AVFormat handle of the copied data
128 * @return The return value is TRUE for success, FALSE for failure
129 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error.
130 * @since 9
131 * @version 1.0
132 */
133bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from);
134
135/**
136 * @brief Write Int data to OH_AVFormat
137 * @syscap SystemCapability.Multimedia.Media.Core
138 * @param format pointer to an OH_AVFormat instance
139 * @param key key to write data
140 * @param value written data
141 * @return The return value is TRUE for success, FALSE for failure
142 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
143 * @since 9
144 * @version 1.0
145 */
146bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_t value);
147
148/**
149 * @brief Write Long data to OH_AVFormat
150 * @syscap SystemCapability.Multimedia.Media.Core
151 * @param format pointer to an OH_AVFormat instance
152 * @param key key to write data
153 * @param value written data
154 * @return The return value is TRUE for success, FALSE for failure
155 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
156 * @since 9
157 * @version 1.0
158 */
159bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64_t value);
160
161/**
162 * @brief Write Float data to OH_AVFormat
163 * @syscap SystemCapability.Multimedia.Media.Core
164 * @param format pointer to an OH_AVFormat instance
165 * @param key key to write data
166 * @param value written data
167 * @return The return value is TRUE for success, FALSE for failure
168 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
169 * @since 9
170 * @version 1.0
171 */
172bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, float value);
173
174/**
175 * @brief Write Double data to OH_AVFormat
176 * @syscap SystemCapability.Multimedia.Media.Core
177 * @param format pointer to an OH_AVFormat instance
178 * @param key key to write data
179 * @param value written data
180 * @return The return value is TRUE for success, FALSE for failure
181 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
182 * @since 9
183 * @version 1.0
184 */
185bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, double value);
186
187/**
188 * @brief Write String data to OH_AVFormat
189 * @syscap SystemCapability.Multimedia.Media.Core
190 * @param format pointer to an OH_AVFormat instance
191 * @param key key to write data
192 * @param value written data
193 * @return The return value is TRUE for success, FALSE for failure
194 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
195 * 4. value is nullptr.
196 * @since 9
197 * @version 1.0
198 */
199bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, const char *value);
200
201/**
202 * @brief Write a block of data of a specified length to OH_AVFormat
203 * @syscap SystemCapability.Multimedia.Media.Core
204 * @param format pointer to an OH_AVFormat instance
205 * @param key key to write data
206 * @param addr written data addr
207 * @param size written data length
208 * @return The return value is TRUE for success, FALSE for failure
209 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
210 * 4. addr is nullptr. 5. size is zero.
211 * @since 9
212 * @version 1.0
213 */
214bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const uint8_t *addr, size_t size);
215
216/**
217 * @brief Read Int data from OH_AVFormat
218 * @syscap SystemCapability.Multimedia.Media.Core
219 * @param format pointer to an OH_AVFormat instance
220 * @param key read key value
221 * @param out read data
222 * @return The return value is TRUE for success, FALSE for failure
223 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
224 * 4. out is nullptr.
225 * @since 9
226 * @version 1.0
227 */
228bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_t *out);
229
230/**
231 * @brief Read Long data from OH_AVFormat
232 * @syscap SystemCapability.Multimedia.Media.Core
233 * @param format pointer to an OH_AVFormat instance
234 * @param key read key value
235 * @param out read data
236 * @return The return value is TRUE for success, FALSE for failure
237 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
238 * 4. out is nullptr.
239 * @since 9
240 * @version 1.0
241 */
242bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64_t *out);
243
244/**
245 * @brief Read Float data from OH_AVFormat
246 * @syscap SystemCapability.Multimedia.Media.Core
247 * @param format pointer to an OH_AVFormat instance
248 * @param key read key value
249 * @param out read data
250 * @return The return value is TRUE for success, FALSE for failure
251 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
252 * 4. out is nullptr.
253 * @since 9
254 * @version 1.0
255 */
256bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, float *out);
257
258/**
259 * @brief Read Double data from OH_AVFormat
260 * @syscap SystemCapability.Multimedia.Media.Core
261 * @param format pointer to an OH_AVFormat instance
262 * @param key read key value
263 * @param out read data
264 * @return The return value is TRUE for success, FALSE for failure
265 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
266 * 4. out is nullptr.
267 * @since 9
268 * @version 1.0
269 */
270bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, double *out);
271
272/**
273 * @brief Read String data from OH_AVFormat
274 * @syscap SystemCapability.Multimedia.Media.Core
275 * @param format pointer to an OH_AVFormat instance
276 * @param key read key value
277 * @param out The read string pointer, the data life cycle pointed to is updated with GetString,
278 * and Format is destroyed. If the caller needs to hold it for a long time, it must copy the memory
279 * @return The return value is TRUE for success, FALSE for failure
280 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
281 * 4. out is nullptr. 5. malloc out string nullptr.
282 * @since 9
283 * @version 1.0
284 */
285bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, const char **out);
286
287/**
288 * @brief Read a block of data of specified length from OH_AVFormat
289 * @syscap SystemCapability.Multimedia.Media.Core
290 * @param format pointer to an OH_AVFormat instance
291 * @param key Key value for reading and writing data
292 * @param addr The life cycle is held by the format, with the destruction of the format,
293 * if the caller needs to hold it for a long time, it must copy the memory
294 * @param size Length of read and write data
295 * @return The return value is TRUE for success, FALSE for failure
296 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr.
297 * 4. addr is nullptr. 5. size is nullptr.
298 * @since 9
299 * @version 1.0
300 */
301bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size);
302
303/**
304 * @brief Output the information contained in OH_AVFormat as a string.
305 * @syscap SystemCapability.Multimedia.Media.Core
306 * @param format pointer to an OH_AVFormat instance
307 * @return Returns a string consisting of key and data for success, nullptr for failure
308 * Possible failure causes: 1. input format is nullptr. 2. malloc dump info nullptr.
309 * @since 9
310 * @version 1.0
311 */
312const char *OH_AVFormat_DumpInfo(struct OH_AVFormat *format);
313
314#ifdef __cplusplus
315}
316#endif
317
318#endif // NATIVE_AVFORMAT_H