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 /** 50 * @brief Forward declaration of OH_AVSource. 51 * 52 * @since 10 53 */ 54 typedef struct OH_AVSource OH_AVSource; 55 56 /** 57 * @brief Creates an OH_AVSource instance that models the media with dataSource. 58 * @syscap SystemCapability.Multimedia.Media.Spliter 59 * @param dataSource An Struct for a remote media resource. 60 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns nullptr. 61 * Possible failure causes: 62 * 1. dataSource is nullptr. 63 * 2. dataSource->size == 0. 64 * 3. set data source failed. 65 * 4. out of memory. 66 * 5. demuxer engine is nullptr. 67 * @since 12 68 */ 69 OH_AVSource *OH_AVSource_CreateWithDataSource(OH_AVDataSource *dataSource); 70 71 /** 72 * @brief Creates an OH_AVSource instance with dataSource and userData. 73 * @syscap SystemCapability.Multimedia.Media.Spliter 74 * @param dataSource A pointer to the data source structure, which can obtain the input data. 75 * @param userData A pointer to user-defined data. 76 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns nullptr. 77 * Possible failure causes: 78 * 1. dataSource is nullptr. 79 * 2. dataSource->size == 0. 80 * 3. set data source failed. 81 * 4. out of memory. 82 * 5. demuxer engine is nullptr. 83 * @since 20 84 */ 85 OH_AVSource *OH_AVSource_CreateWithDataSourceExt(OH_AVDataSourceExt *dataSource, void *userData); 86 87 /** 88 * @brief Creates an OH_AVSource instance that models the media at the URI. 89 * @syscap SystemCapability.Multimedia.Media.Spliter 90 * @param uri An URI for a remote media resource. 91 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns nullptr. 92 * Possible failure causes: 93 * 1. network anomaly. 94 * 2. resource is invalid. 95 * 3. file format is not supported. 96 * @since 10 97 */ 98 OH_AVSource *OH_AVSource_CreateWithURI(char *uri); 99 100 /** 101 * @brief Creates an OH_AVSource instance that models the media at the FileDescriptor. 102 * @syscap SystemCapability.Multimedia.Media.Spliter 103 * @param fd The fileDescriptor of data source. 104 * @param offset The offset into the file to start reading. 105 * @param size The file size in bytes. 106 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns nullptr. 107 * Possible failure causes: 108 * 1. fd is invalid. 109 * 2. offset is not start pos of resource. 110 * 3. size error. 111 * 4. resource is invalid. 112 * 5. file format is not supported. 113 * @since 10 114 */ 115 OH_AVSource *OH_AVSource_CreateWithFD(int32_t fd, int64_t offset, int64_t size); 116 117 /** 118 * @brief Destroy the OH_AVSource instance and free the internal resources. 119 * @syscap SystemCapability.Multimedia.Media.Spliter 120 * @param source Pointer to an OH_AVSource instance. 121 * @return Returns AV_ERR_OK if the execution is successful, 122 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 123 * {@link AV_ERR_INVALID_VAL} source is invalid. 124 * @since 10 125 */ 126 OH_AVErrCode OH_AVSource_Destroy(OH_AVSource *source); 127 128 /** 129 * @brief Get the format info of source. 130 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 131 * to be manually released by the caller. 132 * @syscap SystemCapability.Multimedia.Media.Spliter 133 * @param source Pointer to an OH_AVSource instance. 134 * @return Returns the source's format info if the execution is successful, otherwise returns nullptr. 135 * Possible failure causes: 136 * 1. source is invalid. 137 * @since 10 138 */ 139 OH_AVFormat *OH_AVSource_GetSourceFormat(OH_AVSource *source); 140 141 /** 142 * @brief Get the format info of track. 143 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 144 * to be manually released by the caller. 145 * @syscap SystemCapability.Multimedia.Media.Spliter 146 * @param source Pointer to an OH_AVSource instance. 147 * @param trackIndex The track index to get format. 148 * @return Returns the track's format info if the execution is successful, otherwise returns nullptr. 149 * Possible failure causes: 150 * 1. source is invalid. 151 * 2. trackIndex is out of range. 152 * @since 10 153 */ 154 OH_AVFormat *OH_AVSource_GetTrackFormat(OH_AVSource *source, uint32_t trackIndex); 155 156 /** 157 * @brief Get the format info of custom metadata. 158 * 159 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 160 * to be manually released by the caller. 161 * 162 * @syscap SystemCapability.Multimedia.Media.Spliter 163 * @param source Pointer to an OH_AVSource instance. 164 * @return Returns the metadata's format info if the execution is successful, otherwise returns nullptr. 165 * Possible failure causes: 166 * 1. source is invalid. 167 * @since 18 168 */ 169 OH_AVFormat *OH_AVSource_GetCustomMetadataFormat(OH_AVSource *source); 170 171 #ifdef __cplusplus 172 } 173 #endif 174 175 #endif // NATIVE_AVSOURCE_H 176 /** @} */