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