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 * @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 } OH_AVPixelFormat; 79 80 /** 81 * @briefCreate an OH_AVFormat handle pointer to read and write data 82 * @syscap SystemCapability.Multimedia.Media.Core 83 * @return Returns a pointer to an OH_AVFormat instance 84 * @since 9 85 * @version 1.0 86 */ 87 struct OH_AVFormat *OH_AVFormat_Create(void); 88 89 /** 90 * @brief Create an audio OH_AVFormat handle pointer to read and write data. 91 * @syscap SystemCapability.Multimedia.Media.Core 92 * @param mimeType mime type 93 * @param sampleRate sample rate 94 * @param channelCount channel count 95 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise NULL 96 * Possible failure causes: 1. mimeType is NULL; 2. new format is NULL. 97 * @since 10 98 * @version 1.0 99 */ 100 struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType, 101 int32_t sampleRate, 102 int32_t channelCount); 103 104 /** 105 * @brief Create an video OH_AVFormat handle pointer to read and write data. 106 * @syscap SystemCapability.Multimedia.Media.Core 107 * @param mimeType mime type 108 * @param width width 109 * @param height height 110 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise NULL 111 * Possible failure causes: 1. mimeType is NULL; 2. new format is NULL. 112 * @since 10 113 * @version 1.0 114 */ 115 struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, 116 int32_t width, 117 int32_t height); 118 119 /** 120 * @brief Destroy the OH_AVFormat instance, can not be destoryed repeatedly. 121 * @syscap SystemCapability.Multimedia.Media.Core 122 * @param format pointer to an OH_AVFormat instance 123 * @return void 124 * @since 9 125 * @version 1.0 126 */ 127 void OH_AVFormat_Destroy(struct OH_AVFormat *format); 128 129 /** 130 * @brief Copy OH_AVFormat handle resource. 131 * @syscap SystemCapability.Multimedia.Media.Core 132 * @param to OH_AVFormat handle pointer to receive data 133 * @param from pointer to the OH_AVFormat handle of the copied data 134 * @return The return value is TRUE for success, FALSE for failure 135 * Possible failure causes: 136 * 1. input parameter is NULL; 137 * 2. structure verification failed of the input OH_AVFormat. 138 * @since 9 139 * @version 1.0 140 */ 141 bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); 142 143 /** 144 * @brief Set a value of Int type to the key of OH_AVFormat. 145 * @syscap SystemCapability.Multimedia.Media.Core 146 * @param format pointer to an OH_AVFormat instance 147 * @param key key to write data 148 * @param value written data 149 * @return The return value is TRUE for success, FALSE for failure 150 * Possible failure causes: 151 * 1. input format is NULL; 152 * 2. structure verification failed of the input format; 153 * 3. input key is NULL; 154 * 4. value type corresponding to the key is incorrect. 155 * @since 9 156 * @version 1.0 157 */ 158 bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_t value); 159 160 /** 161 * @brief Set a value of Long type to the key of OH_AVFormat. 162 * @syscap SystemCapability.Multimedia.Media.Core 163 * @param format pointer to an OH_AVFormat instance 164 * @param key key to write data 165 * @param value written data 166 * @return The return value is TRUE for success, FALSE for failure 167 * Possible failure causes: 168 * 1. input format is NULL; 169 * 2. structure verification failed of the input format; 170 * 3. input key is NULL; 171 * 4. value type corresponding to the key is incorrect. 172 * @since 9 173 * @version 1.0 174 */ 175 bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64_t value); 176 177 /** 178 * @brief Set a value of Float type to the key of OH_AVFormat. 179 * @syscap SystemCapability.Multimedia.Media.Core 180 * @param format pointer to an OH_AVFormat instance 181 * @param key key to write data 182 * @param value written data 183 * @return The return value is TRUE for success, FALSE for failure 184 * Possible failure causes: 185 * 1. input format is NULL; 186 * 2. structure verification failed of the input format; 187 * 3. input key is NULL; 188 * 4. value type corresponding to the key is incorrect. 189 * @since 9 190 * @version 1.0 191 */ 192 bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, float value); 193 194 /** 195 * @brief Set a value of Double type to the key of OH_AVFormat. 196 * @syscap SystemCapability.Multimedia.Media.Core 197 * @param format pointer to an OH_AVFormat instance 198 * @param key key to write data 199 * @param value written data 200 * @return The return value is TRUE for success, FALSE for failure 201 * Possible failure causes: 202 * 1. input format is NULL; 203 * 2. structure verification failed of the input format; 204 * 3. input key is NULL; 205 * 4. value type corresponding to the key is incorrect. 206 * @since 9 207 * @version 1.0 208 */ 209 bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, double value); 210 211 /** 212 * @brief Set a value of String type to the key of OH_AVFormat. 213 * @syscap SystemCapability.Multimedia.Media.Core 214 * @param format pointer to an OH_AVFormat instance 215 * @param key key to write data 216 * @param value written data 217 * @return The return value is TRUE for success, FALSE for failure 218 * Possible failure causes: 219 * 1. input format is NULL; 220 * 2. structure verification failed of the input format; 221 * 3. input key is NULL; 222 * 4. input value is NULL; 223 * 5. value type corresponding to the key is incorrect; 224 * @since 9 225 * @version 1.0 226 */ 227 bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, const char *value); 228 229 /** 230 * @brief Write a block of data of a specified length to OH_AVFormat. 231 * @syscap SystemCapability.Multimedia.Media.Core 232 * @param format pointer to an OH_AVFormat instance 233 * @param key key to write data 234 * @param addr written data addr, the lifecycle is managed by the invoker 235 * @param size written data length, range is(0, 1)MB 236 * @return The return value is TRUE for success, FALSE for failure 237 * Possible failure causes: 238 * 1. input format is NULL; 239 * 2. structure verification failed of the input format; 240 * 3. input key is NULL; 241 * 4. input addr is NULL; 242 * 5. size is 0 or exceeds the upper limit, which is 1MB; 243 * 6. value type corresponding to the key is incorrect. 244 * @since 9 245 * @version 1.0 246 */ 247 bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const uint8_t *addr, size_t size); 248 249 /** 250 * @brief Get the Int value from the key of OH_AVFormat. 251 * @syscap SystemCapability.Multimedia.Media.Core 252 * @param format pointer to an OH_AVFormat instance 253 * @param key read key value 254 * @param out read data 255 * @return The return value is TRUE for success, FALSE for failure 256 * Possible failure causes: 257 * 1. input format is NULL; 258 * 2. structure verification failed of the input format; 259 * 3. input key is NULL; 260 * 4. input out is NULL; 261 * 5. the obtained key does not exist or is not set. 262 * @since 9 263 * @version 1.0 264 */ 265 bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_t *out); 266 267 /** 268 * @brief Get the Long value from the key of OH_AVFormat. 269 * @syscap SystemCapability.Multimedia.Media.Core 270 * @param format pointer to an OH_AVFormat instance 271 * @param key read key value 272 * @param out read data 273 * @return The return value is TRUE for success, FALSE for failure 274 * Possible failure causes: 275 * 1. input format is NULL; 276 * 2. structure verification failed of the input format; 277 * 3. input key is NULL; 278 * 4. input out is NULL; 279 * 5. the obtained key does not exist or is not set. 280 * @since 9 281 * @version 1.0 282 */ 283 bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64_t *out); 284 285 /** 286 * @brief Get the Float value from the key of OH_AVFormat. 287 * @syscap SystemCapability.Multimedia.Media.Core 288 * @param format pointer to an OH_AVFormat instance 289 * @param key read key value 290 * @param out read data 291 * @return The return value is TRUE for success, FALSE for failure 292 * Possible failure causes: 293 * 1. input format is NULL; 294 * 2. structure verification failed of the input format; 295 * 3. input key is NULL; 296 * 4. input out is NULL; 297 * 5. the obtained key does not exist or is not set. 298 * @since 9 299 * @version 1.0 300 */ 301 bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, float *out); 302 303 /** 304 * @brief Get the Double value from the key of OH_AVFormat. 305 * @syscap SystemCapability.Multimedia.Media.Core 306 * @param format pointer to an OH_AVFormat instance 307 * @param key read key value 308 * @param out read data 309 * @return The return value is TRUE for success, FALSE for failure 310 * Possible failure causes: 311 * 1. input format is NULL; 312 * 2. structure verification failed of the input format; 313 * 3. input key is NULL; 314 * 4. input out is NULL; 315 * 5. the obtained key does not exist or is not set. 316 * @since 9 317 * @version 1.0 318 */ 319 bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, double *out); 320 321 /** 322 * @brief Get the String value from the key of OH_AVFormat. 323 * @syscap SystemCapability.Multimedia.Media.Core 324 * @param format pointer to an OH_AVFormat instance 325 * @param key read key value 326 * @param out The read string pointer, the data life cycle pointed to is updated with GetString, 327 * and Format is destroyed. If the caller needs to hold it for a long time, it must copy the memory 328 * @return The return value is TRUE for success, FALSE for failure 329 * Possible failure causes: 330 * 1. input format is NULL; 331 * 2. structure verification failed of the input format; 332 * 3. input key is NULL; 333 * 4. input out is NULL; 334 * 5. the resources of out string generated by malloc is insufficient; 335 * 6. the obtained key does not exist or is not set. 336 * @since 9 337 * @version 1.0 338 */ 339 bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, const char **out); 340 341 /** 342 * @brief Read a block of data of specified length from OH_AVFormat 343 * @syscap SystemCapability.Multimedia.Media.Core 344 * @param format pointer to an OH_AVFormat instance 345 * @param key Key value for reading data 346 * @param addr The life cycle is held by the format, with the destruction of the format, 347 * if the caller needs to hold it for a long time, it must copy the memory 348 * @param size Length of read data 349 * @return The return value is TRUE for success, FALSE for failure 350 * Possible failure causes: 351 * 1. input format is NULL; 352 * 2. structure verification failed of the input format; 353 * 3. input key is NULL; 354 * 4. input addr is NULL; 355 * 5. input size is NULL; 356 * 6. the obtained key does not exist or is not set. 357 * @since 9 358 * @version 1.0 359 */ 360 bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size); 361 362 /** 363 * @brief Return a string consisting of key and values contained in OH_AVFormat. 364 * the max string that can be returned is 1024 bytes, 365 * and the string pointer is released when the format is destroyed. 366 * @syscap SystemCapability.Multimedia.Media.Core 367 * @param format pointer to an OH_AVFormat instance 368 * @return Returns a string consisting of key and data for success, NULL for failure 369 * Possible failure causes: 1. input format is NULL; 2. system resources are insufficient. 370 * @since 9 371 * @version 1.0 372 */ 373 const char *OH_AVFormat_DumpInfo(struct OH_AVFormat *format); 374 375 #ifdef __cplusplus 376 } 377 #endif 378 379 #endif // NATIVE_AVFORMAT_H 380 /** @} */