1 /* 2 * Copyright (C) 2023-2025 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 Core 18 * @{ 19 * 20 * @brief The Core module provides basic backbone capabilities for media frameworks, 21 * including functions such as memory, error codes, and media data structures. 22 * 23 * @syscap SystemCapability.Multimedia.Media.Core 24 * @since 9 25 */ 26 27 /** 28 * @file native_avformat.h 29 * 30 * @brief Declared functions and enumerations related to OH_AVFormat. 31 * 32 * @kit AVCodecKit 33 * @library libnative_media_core.so 34 * @syscap SystemCapability.Multimedia.Media.Core 35 * @since 9 36 */ 37 38 #ifndef NATIVE_AVFORMAT_H 39 #define NATIVE_AVFORMAT_H 40 41 #include <stdint.h> 42 #include <stdbool.h> 43 #include <stdio.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 typedef struct OH_AVFormat OH_AVFormat; 50 51 /** 52 * @brief Enumerates AVPixel Format. 53 * @syscap SystemCapability.Multimedia.Media.Core 54 * @since 9 55 * @version 1.0 56 */ 57 typedef enum OH_AVPixelFormat { 58 /** 59 * yuv 420 planar. 60 */ 61 AV_PIXEL_FORMAT_YUVI420 = 1, 62 /** 63 * NV12. yuv 420 semiplanar. 64 */ 65 AV_PIXEL_FORMAT_NV12 = 2, 66 /** 67 * NV21. yvu 420 semiplanar. 68 */ 69 AV_PIXEL_FORMAT_NV21 = 3, 70 /** 71 * format from surface. 72 */ 73 AV_PIXEL_FORMAT_SURFACE_FORMAT = 4, 74 /** 75 * RGBA8888 76 */ 77 AV_PIXEL_FORMAT_RGBA = 5, 78 /** RGBA1010102 79 * since 20 80 */ 81 AV_PIXEL_FORMAT_RGBA1010102 = 6, 82 } OH_AVPixelFormat; 83 84 /** 85 * @briefCreate an OH_AVFormat handle pointer to read and write data 86 * @syscap SystemCapability.Multimedia.Media.Core 87 * @return Returns a pointer to an OH_AVFormat instance 88 * @since 9 89 * @version 1.0 90 */ 91 struct OH_AVFormat *OH_AVFormat_Create(void); 92 93 /** 94 * @brief Create an audio OH_AVFormat handle pointer to read and write data. 95 * @syscap SystemCapability.Multimedia.Media.Core 96 * @param mimeType mime type 97 * @param sampleRate sample rate 98 * @param channelCount channel count 99 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise NULL 100 * Possible failure causes: 1. mimeType is NULL; 2. new format is NULL. 101 * @since 10 102 * @version 1.0 103 */ 104 struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType, 105 int32_t sampleRate, 106 int32_t channelCount); 107 108 /** 109 * @brief Create an video OH_AVFormat handle pointer to read and write data. 110 * @syscap SystemCapability.Multimedia.Media.Core 111 * @param mimeType mime type 112 * @param width width 113 * @param height height 114 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise NULL 115 * Possible failure causes: 1. mimeType is NULL; 2. new format is NULL. 116 * @since 10 117 * @version 1.0 118 */ 119 struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, 120 int32_t width, 121 int32_t height); 122 123 /** 124 * @brief Destroy the OH_AVFormat instance, can not be destoryed repeatedly. 125 * @syscap SystemCapability.Multimedia.Media.Core 126 * @param format pointer to an OH_AVFormat instance 127 * @return void 128 * @since 9 129 * @version 1.0 130 */ 131 void OH_AVFormat_Destroy(struct OH_AVFormat *format); 132 133 /** 134 * @brief Copy OH_AVFormat handle resource. 135 * @syscap SystemCapability.Multimedia.Media.Core 136 * @param to OH_AVFormat handle pointer to receive data 137 * @param from pointer to the OH_AVFormat handle of the copied data 138 * @return The return value is TRUE for success, FALSE for failure 139 * Possible failure causes: 140 * 1. input parameter is NULL; 141 * 2. structure verification failed of the input OH_AVFormat. 142 * @since 9 143 * @version 1.0 144 */ 145 bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); 146 147 /** 148 * @brief Set a value of Int type to the key of OH_AVFormat. 149 * @syscap SystemCapability.Multimedia.Media.Core 150 * @param format pointer to an OH_AVFormat instance 151 * @param key key to write data 152 * @param value written data 153 * @return The return value is TRUE for success, FALSE for failure 154 * Possible failure causes: 155 * 1. input format is NULL; 156 * 2. structure verification failed of the input format; 157 * 3. input key is NULL; 158 * 4. value type corresponding to the key is incorrect. 159 * @since 9 160 * @version 1.0 161 */ 162 bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_t value); 163 164 /** 165 * @brief Set a value of Long type to the key of OH_AVFormat. 166 * @syscap SystemCapability.Multimedia.Media.Core 167 * @param format pointer to an OH_AVFormat instance 168 * @param key key to write data 169 * @param value written data 170 * @return The return value is TRUE for success, FALSE for failure 171 * Possible failure causes: 172 * 1. input format is NULL; 173 * 2. structure verification failed of the input format; 174 * 3. input key is NULL; 175 * 4. value type corresponding to the key is incorrect. 176 * @since 9 177 * @version 1.0 178 */ 179 bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64_t value); 180 181 /** 182 * @brief Set a value of Float type to the key of OH_AVFormat. 183 * @syscap SystemCapability.Multimedia.Media.Core 184 * @param format pointer to an OH_AVFormat instance 185 * @param key key to write data 186 * @param value written data 187 * @return The return value is TRUE for success, FALSE for failure 188 * Possible failure causes: 189 * 1. input format is NULL; 190 * 2. structure verification failed of the input format; 191 * 3. input key is NULL; 192 * 4. value type corresponding to the key is incorrect. 193 * @since 9 194 * @version 1.0 195 */ 196 bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, float value); 197 198 /** 199 * @brief Set a value of Double type to the key of OH_AVFormat. 200 * @syscap SystemCapability.Multimedia.Media.Core 201 * @param format pointer to an OH_AVFormat instance 202 * @param key key to write data 203 * @param value written data 204 * @return The return value is TRUE for success, FALSE for failure 205 * Possible failure causes: 206 * 1. input format is NULL; 207 * 2. structure verification failed of the input format; 208 * 3. input key is NULL; 209 * 4. value type corresponding to the key is incorrect. 210 * @since 9 211 * @version 1.0 212 */ 213 bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, double value); 214 215 /** 216 * @brief Set a value of String type to the key of OH_AVFormat. 217 * @syscap SystemCapability.Multimedia.Media.Core 218 * @param format pointer to an OH_AVFormat instance 219 * @param key key to write data 220 * @param value written data 221 * @return The return value is TRUE for success, FALSE for failure 222 * Possible failure causes: 223 * 1. input format is NULL; 224 * 2. structure verification failed of the input format; 225 * 3. input key is NULL; 226 * 4. input value is NULL; 227 * 5. value type corresponding to the key is incorrect; 228 * @since 9 229 * @version 1.0 230 */ 231 bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, const char *value); 232 233 /** 234 * @brief Write a block of data of a specified length to OH_AVFormat. 235 * @syscap SystemCapability.Multimedia.Media.Core 236 * @param format pointer to an OH_AVFormat instance 237 * @param key key to write data 238 * @param addr written data addr, the lifecycle is managed by the invoker 239 * @param size written data length, range is(0, 1)MB 240 * @return The return value is TRUE for success, FALSE for failure 241 * Possible failure causes: 242 * 1. input format is NULL; 243 * 2. structure verification failed of the input format; 244 * 3. input key is NULL; 245 * 4. input addr is NULL; 246 * 5. size is 0 or exceeds the upper limit, which is 1MB; 247 * 6. value type corresponding to the key is incorrect. 248 * @since 9 249 * @version 1.0 250 */ 251 bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const uint8_t *addr, size_t size); 252 253 /** 254 * @brief Write a list of int32_t data of a specified length to OH_AVFormat. 255 * 256 * @syscap SystemCapability.Multimedia.Media.Core 257 * @param format pointer to an OH_AVFormat instance 258 * @param key key to write data 259 * @param addr written data addr 260 * @param size written data length 261 * @return The return value is TRUE for success, FALSE for failure 262 * Possible failure causes: 263 * 1. input format is NULL. 264 * 2. input format's magic error. 265 * 3. key is nullptr. 266 * 4. addr is nullptr. 267 * 5. size is zero. 268 * @since 20 269 */ 270 bool OH_AVFormat_SetIntBuffer(struct OH_AVFormat *format, const char *key, const int32_t *addr, size_t size); 271 272 /** 273 * @brief Get the Int value from the key of 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 read data 278 * @return The return value is TRUE for success, FALSE for failure 279 * Possible failure causes: 280 * 1. input format is NULL; 281 * 2. structure verification failed of the input format; 282 * 3. input key is NULL; 283 * 4. input out is NULL; 284 * 5. the obtained key does not exist or is not set. 285 * @since 9 286 * @version 1.0 287 */ 288 bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_t *out); 289 290 /** 291 * @brief Get the Long value from the key of OH_AVFormat. 292 * @syscap SystemCapability.Multimedia.Media.Core 293 * @param format pointer to an OH_AVFormat instance 294 * @param key read key value 295 * @param out read data 296 * @return The return value is TRUE for success, FALSE for failure 297 * Possible failure causes: 298 * 1. input format is NULL; 299 * 2. structure verification failed of the input format; 300 * 3. input key is NULL; 301 * 4. input out is NULL; 302 * 5. the obtained key does not exist or is not set. 303 * @since 9 304 * @version 1.0 305 */ 306 bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64_t *out); 307 308 /** 309 * @brief Get the Float value from the key of OH_AVFormat. 310 * @syscap SystemCapability.Multimedia.Media.Core 311 * @param format pointer to an OH_AVFormat instance 312 * @param key read key value 313 * @param out read data 314 * @return The return value is TRUE for success, FALSE for failure 315 * Possible failure causes: 316 * 1. input format is NULL; 317 * 2. structure verification failed of the input format; 318 * 3. input key is NULL; 319 * 4. input out is NULL; 320 * 5. the obtained key does not exist or is not set. 321 * @since 9 322 * @version 1.0 323 */ 324 bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, float *out); 325 326 /** 327 * @brief Get the Double value from the key of OH_AVFormat. 328 * @syscap SystemCapability.Multimedia.Media.Core 329 * @param format pointer to an OH_AVFormat instance 330 * @param key read key value 331 * @param out read data 332 * @return The return value is TRUE for success, FALSE for failure 333 * Possible failure causes: 334 * 1. input format is NULL; 335 * 2. structure verification failed of the input format; 336 * 3. input key is NULL; 337 * 4. input out is NULL; 338 * 5. the obtained key does not exist or is not set. 339 * @since 9 340 * @version 1.0 341 */ 342 bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, double *out); 343 344 /** 345 * @brief Get the String value from the key of OH_AVFormat. 346 * @syscap SystemCapability.Multimedia.Media.Core 347 * @param format pointer to an OH_AVFormat instance 348 * @param key read key value 349 * @param out The read string pointer, the data life cycle pointed to is updated with GetString, 350 * and Format is destroyed. If the caller needs to hold it for a long time, it must copy the memory 351 * @return The return value is TRUE for success, FALSE for failure 352 * Possible failure causes: 353 * 1. input format is NULL; 354 * 2. structure verification failed of the input format; 355 * 3. input key is NULL; 356 * 4. input out is NULL; 357 * 5. the resources of out string generated by malloc is insufficient; 358 * 6. the obtained key does not exist or is not set. 359 * @since 9 360 * @version 1.0 361 */ 362 bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, const char **out); 363 364 /** 365 * @brief Read a block of data of specified length from OH_AVFormat 366 * @syscap SystemCapability.Multimedia.Media.Core 367 * @param format pointer to an OH_AVFormat instance 368 * @param key Key value for reading data 369 * @param addr The life cycle is held by the format, with the destruction of the format, 370 * if the caller needs to hold it for a long time, it must copy the memory 371 * @param size Length of read data 372 * @return The return value is TRUE for success, FALSE for failure 373 * Possible failure causes: 374 * 1. input format is NULL; 375 * 2. structure verification failed of the input format; 376 * 3. input key is NULL; 377 * 4. input addr is NULL; 378 * 5. input size is NULL; 379 * 6. the obtained key does not exist or is not set. 380 * @since 9 381 * @version 1.0 382 */ 383 bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size); 384 385 /** 386 * @brief Read an array of int32_t values from an OH_AVFormat object. 387 * 388 * Note that the obtained buffer's lifetime bound to the OH_AVFormat object, 389 * it's automatically invalidated when the format object is destroyed.\n 390 * Applications must explicitly copy the data to newly allocated memory if 391 * the data needs to outlive the OH_AVFormat instance.\n 392 * 393 * @syscap SystemCapability.Multimedia.Media.Core 394 * @param format pointer to an OH_AVFormat instance 395 * @param key Data identifier key 396 * @param addr Pointer to receive the data buffer reference 397 * @param size Pointer to receive the element count 398 * @return The return value is TRUE for success, FALSE for failure 399 * Possible failure causes: 400 * 1. input format is nullptr. 401 * 2. input format's magic error. 402 * 3. key is nullptr. 403 * 4. addr is nullptr. 404 * 5. size is nullptr. 405 * @since 20 406 */ 407 bool OH_AVFormat_GetIntBuffer(struct OH_AVFormat *format, const char *key, int32_t **addr, size_t *size); 408 409 /** 410 * @brief Return a string consisting of key and values contained in OH_AVFormat. 411 * the max string that can be returned is 1024 bytes, 412 * and the string pointer is released when the format is destroyed. 413 * @syscap SystemCapability.Multimedia.Media.Core 414 * @param format pointer to an OH_AVFormat instance 415 * @return Returns a string consisting of key and data for success, NULL for failure 416 * Possible failure causes: 1. input format is NULL; 2. system resources are insufficient. 417 * @since 9 418 * @version 1.0 419 */ 420 const char *OH_AVFormat_DumpInfo(struct OH_AVFormat *format); 421 422 #ifdef __cplusplus 423 } 424 #endif 425 426 #endif // NATIVE_AVFORMAT_H 427 /** @} */