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 AVSource 18 * @{ 19 * 20 * @brief The AVSource module provides functions for constructing media resource object functionality. 21 * 22 * @syscap SystemCapability.Multimedia.Media.Spliter 23 * @since 10 24 */ 25 26 /** 27 * @file native_avsource.h 28 * 29 * @brief Declare the interface for parsing audio and video media data. 30 * 31 * @kit AVCodecKit 32 * @library libnative_media_avsource.so 33 * @syscap SystemCapability.Multimedia.Media.Spliter 34 * @since 10 35 */ 36 37 #ifndef NATIVE_AVSOURCE_H 38 #define NATIVE_AVSOURCE_H 39 40 #include <stdint.h> 41 #include "native_avcodec_base.h" 42 #include "native_averrors.h" 43 #include "native_avformat.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 typedef struct OH_AVSource OH_AVSource; 50 51 /** 52 * @brief Create OH_AVSource instance for user-defined data source resource objects. 53 * The instance can be released by calling the interface {@link OH_AVSource_Destroy}. 54 * @syscap SystemCapability.Multimedia.Media.Spliter 55 * @param dataSource User customized media resource. 56 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns NULL. 57 * Possible failure causes: 58 * 1. dataSource is NULL. 59 * 2. dataSource->size == 0. 60 * 3. set data source failed. 61 * 4. out of memory. 62 * 5. demuxer engine is NULL. 63 * @since 12 64 */ 65 OH_AVSource *OH_AVSource_CreateWithDataSource(OH_AVDataSource *dataSource); 66 67 /** 68 * @brief Creates an OH_AVSource instance with dataSource and userData. 69 * The instance can be released by calling the interface {@link OH_AVSource_Destroy}. 70 * @syscap SystemCapability.Multimedia.Media.Spliter 71 * @param dataSource A pointer to the data source structure, which can obtain the input data. 72 * @param userData A pointer to user-defined data. 73 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns nullptr. 74 * Possible failure causes: 75 * 1. dataSource is nullptr. 76 * 2. dataSource->size == 0. 77 * 3. set data source failed. 78 * 4. out of memory. 79 * 5. demuxer engine is nullptr. 80 * @since 20 81 */ 82 OH_AVSource *OH_AVSource_CreateWithDataSourceExt(OH_AVDataSourceExt *dataSource, void* userData); 83 84 /** 85 * @brief To create an OH_AVSource instance for the resource object corresponding to a unified resource identifier, 86 * The instance can be released by calling the interface {@link OH_AVSource_Destroy}. 87 * @syscap SystemCapability.Multimedia.Media.Spliter 88 * @param uri An URI for a remote media resource. 89 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns NULL. 90 * Possible failure causes: 91 * 1. network anomaly. 92 * 2. resource is invalid. 93 * 3. file format is not supported. 94 * @since 10 95 */ 96 OH_AVSource *OH_AVSource_CreateWithURI(char *uri); 97 98 /** 99 * @brief Create an OH_AVSource instance for the resource object corresponding to the fileDescriptor. 100 * The instance can be released by calling the interface {@link OH_AVSource_Destroy}. 101 * If the input offset is not the starting position of the file, or the size is not the size of the file, 102 * it may result in undefined errors such as create OH_AVSource failure and 103 * subsequent demuxer failure due to incomplete data acquisition. 104 * @syscap SystemCapability.Multimedia.Media.Spliter 105 * @param fd The fileDescriptor of data source. 106 * @param offset The offset into the file to start reading. 107 * @param size The file size in bytes. 108 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns NULL. 109 * Possible failure causes: 110 * 1. fd is invalid. 111 * 2. input offset is not start pos of the file. 112 * 3. size error. 113 * 4. resource is invalid. 114 * 5. file format is unsupported. 115 * @since 10 116 */ 117 OH_AVSource *OH_AVSource_CreateWithFD(int32_t fd, int64_t offset, int64_t size); 118 119 /** 120 * @brief Destroy the OH_AVSource instance and clean up the internal resources. 121 * The same instance can only be destroyed once. The destroyed instance cannot be used again until it is recreated. 122 * Suggest setting the pointer to NULL after the instance is successfully destroyed. 123 * @syscap SystemCapability.Multimedia.Media.Spliter 124 * @param source Pointer to an OH_AVSource instance. 125 * @return Returns AV_ERR_OK if the execution is successful, 126 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 127 * {@link AV_ERR_INVALID_VAL} 128 * 1. source is invalid; 129 * 2. NULL or non OH_AVSource instance. 130 * @since 10 131 */ 132 OH_AVErrCode OH_AVSource_Destroy(OH_AVSource *source); 133 134 /** 135 * @brief Get the format info of source. 136 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 137 * to be manually released by the caller. 138 * @syscap SystemCapability.Multimedia.Media.Spliter 139 * @param source Pointer to an OH_AVSource instance. 140 * @return Returns the source's format info if the execution is successful, otherwise returns NULL. 141 * Possible failure causes: 142 * 1. source is invalid; 143 * 2. NULL or non OH_AVSource instance; 144 * 3. the source has not been initialized. 145 * @since 10 146 */ 147 OH_AVFormat *OH_AVSource_GetSourceFormat(OH_AVSource *source); 148 149 /** 150 * @brief Get the format info of track. 151 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 152 * to be manually released by the caller. 153 * @syscap SystemCapability.Multimedia.Media.Spliter 154 * @param source Pointer to an OH_AVSource instance. 155 * @param trackIndex The track index to get format. 156 * @return Returns the track's format info if the execution is successful, otherwise returns NULL. 157 * Possible failure causes: 158 * 1. source is invalid; 159 * 2. trackIndex is out of range; 160 * 3. the source has not been initialized. 161 * @since 10 162 */ 163 OH_AVFormat *OH_AVSource_GetTrackFormat(OH_AVSource *source, uint32_t trackIndex); 164 165 /** 166 * @brief Get the format info of custom metadata. 167 * 168 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 169 * to be manually released by the caller. 170 * 171 * @syscap SystemCapability.Multimedia.Media.Spliter 172 * @param source Pointer to an OH_AVSource instance. 173 * @return Returns the metadata's format info if the execution is successful, otherwise returns nullptr. 174 * Possible failure causes: 175 * 1. source is invalid. 176 * @since 18 177 */ 178 OH_AVFormat *OH_AVSource_GetCustomMetadataFormat(OH_AVSource *source); 179 180 #ifdef __cplusplus 181 } 182 #endif 183 184 #endif // NATIVE_AVSOURCE_H 185 /** @} */