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 To create an OH_AVSource instance for the resource object corresponding to a unified resource identifier, 69 * The instance can be released by calling the interface {@link OH_AVSource_Destroy}. 70 * @syscap SystemCapability.Multimedia.Media.Spliter 71 * @param uri An URI for a remote media resource. 72 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns NULL. 73 * Possible failure causes: 74 * 1. network anomaly. 75 * 2. resource is invalid. 76 * 3. file format is not supported. 77 * @since 10 78 */ 79 OH_AVSource *OH_AVSource_CreateWithURI(char *uri); 80 81 /** 82 * @brief Create an OH_AVSource instance for the resource object corresponding to the fileDescriptor. 83 * The instance can be released by calling the interface {@link OH_AVSource_Destroy}. 84 * If the input offset is not the starting position of the file, or the size is not the size of the file, 85 * it may result in undefined errors such as create OH_AVSource failure and 86 * subsequent demuxer failure due to incomplete data acquisition. 87 * @syscap SystemCapability.Multimedia.Media.Spliter 88 * @param fd The fileDescriptor of data source. 89 * @param offset The offset into the file to start reading. 90 * @param size The file size in bytes. 91 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns NULL. 92 * Possible failure causes: 93 * 1. fd is invalid. 94 * 2. input offset is not start pos of the file. 95 * 3. size error. 96 * 4. resource is invalid. 97 * 5. file format is unsupported. 98 * @since 10 99 */ 100 OH_AVSource *OH_AVSource_CreateWithFD(int32_t fd, int64_t offset, int64_t size); 101 102 /** 103 * @brief Destroy the OH_AVSource instance and clean up the internal resources. 104 * The same instance can only be destroyed once. The destroyed instance cannot be used again until it is recreated. 105 * Suggest setting the pointer to NULL after the instance is successfully destroyed. 106 * @syscap SystemCapability.Multimedia.Media.Spliter 107 * @param source Pointer to an OH_AVSource instance. 108 * @return Returns AV_ERR_OK if the execution is successful, 109 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 110 * {@link AV_ERR_INVALID_VAL} 111 * 1. source is invalid; 112 * 2. NULL or non OH_AVSource instance. 113 * @since 10 114 */ 115 OH_AVErrCode OH_AVSource_Destroy(OH_AVSource *source); 116 117 /** 118 * @brief Get the format info of source. 119 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 120 * to be manually released by the caller. 121 * @syscap SystemCapability.Multimedia.Media.Spliter 122 * @param source Pointer to an OH_AVSource instance. 123 * @return Returns the source's format info if the execution is successful, otherwise returns NULL. 124 * Possible failure causes: 125 * 1. source is invalid; 126 * 2. NULL or non OH_AVSource instance; 127 * 3. the source has not been initialized. 128 * @since 10 129 */ 130 OH_AVFormat *OH_AVSource_GetSourceFormat(OH_AVSource *source); 131 132 /** 133 * @brief Get the format info of track. 134 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 135 * to be manually released by the caller. 136 * @syscap SystemCapability.Multimedia.Media.Spliter 137 * @param source Pointer to an OH_AVSource instance. 138 * @param trackIndex The track index to get format. 139 * @return Returns the track's format info if the execution is successful, otherwise returns NULL. 140 * Possible failure causes: 141 * 1. source is invalid; 142 * 2. trackIndex is out of range; 143 * 3. the source has not been initialized. 144 * @since 10 145 */ 146 OH_AVFormat *OH_AVSource_GetTrackFormat(OH_AVSource *source, uint32_t trackIndex); 147 148 /** 149 * @brief Get the format info of custom metadata. 150 * 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 * 154 * @syscap SystemCapability.Multimedia.Media.Spliter 155 * @param source Pointer to an OH_AVSource instance. 156 * @return Returns the metadata's format info if the execution is successful, otherwise returns nullptr. 157 * Possible failure causes: 158 * 1. source is invalid. 159 * @since 18 160 */ 161 OH_AVFormat *OH_AVSource_GetCustomMetadataFormat(OH_AVSource *source); 162 163 #ifdef __cplusplus 164 } 165 #endif 166 167 #endif // NATIVE_AVSOURCE_H 168 /** @} */