1# native_avsource.h 2 3## Overview 4 5The file declares the APIs for parsing audio and video media data. 6 7**File to include**: <multimedia/player_framework/native_avsource.h> 8 9**Library**: libnative_media_avsource.so 10 11**System capability**: SystemCapability.Multimedia.Media.Spliter 12 13**Since**: 10 14 15**Related module**: [AVSource](capi-avsource.md) 16 17**Sample**: [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) 18 19## Summary 20 21### Structs 22 23| Name| typedef Keyword| Description| 24| -- | -- | -- | 25| [OH_AVSource](capi-avsource-oh-avsource.md) | OH_AVSource | Describes a native object for the media source interface.| 26 27### Functions 28 29| Name| Description| 30| -- | -- | 31| [OH_AVSource *OH_AVSource_CreateWithDataSource(OH_AVDataSource *dataSource)](#oh_avsource_createwithdatasource) | Creates an OH_AVSource instance with a user-defined data source. You can release the instance by calling [OH_AVSource_Destroy](#oh_avsource_destroy).| 32| [OH_AVSource *OH_AVSource_CreateWithDataSourceExt(OH_AVDataSourceExt *dataSource, void *userData)](#oh_avsource_createwithdatasourceext) | Creates an OH_AVSource instance with a user-defined data source. You can release the instance by calling [OH_AVSource_Destroy](#oh_avsource_destroy). User-defined data can be passed to its callback functions.| 33| [OH_AVSource *OH_AVSource_CreateWithURI(char *uri)](#oh_avsource_createwithuri) | Creates an OH_AVSource instance based on a URI. You can release the instance by calling [OH_AVSource_Destroy](#oh_avsource_destroy).| 34| [OH_AVSource *OH_AVSource_CreateWithFD(int32_t fd, int64_t offset, int64_t size)](#oh_avsource_createwithfd) | Creates an OH_AVSource instance based on an FD. You can release the instance by calling [OH_AVSource_Destroy](#oh_avsource_destroy). Note: If **offset** is not the start position of the file or **size** is not the file size, undefined errors such as creation failure and demultiplexing failure may occur due to incomplete data obtained.| 35| [OH_AVErrCode OH_AVSource_Destroy(OH_AVSource *source)](#oh_avsource_destroy) | Destroys an OH_AVSource instance and clears internal resources. Note: An instance can be destroyed only once. The destroyed instance cannot be used until it is re-created. You are advised to set the pointer to NULL after the instance is destroyed.| 36| [OH_AVFormat *OH_AVSource_GetSourceFormat(OH_AVSource *source)](#oh_avsource_getsourceformat) | Obtains the basic information about a media resource file. You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends.| 37| [OH_AVFormat *OH_AVSource_GetTrackFormat(OH_AVSource *source, uint32_t trackIndex)](#oh_avsource_gettrackformat) | Obtains the basic information about a track. You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends.| 38| [OH_AVFormat *OH_AVSource_GetCustomMetadataFormat(OH_AVSource *source)](#oh_avsource_getcustommetadataformat) | Obtains the basic information about custom metadata. You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends.| 39 40## Function Description 41 42### OH_AVSource_CreateWithDataSource() 43 44``` 45OH_AVSource *OH_AVSource_CreateWithDataSource(OH_AVDataSource *dataSource) 46``` 47 48**Description** 49 50Creates an OH_AVSource instance with a user-defined data source. You can release the instance by calling [OH_AVSource_Destroy](#oh_avsource_destroy). 51 52**System capability**: SystemCapability.Multimedia.Media.Spliter 53 54**Since**: 12 55 56 57**Parameters** 58 59| Name| Description| 60| -- | -- | 61| [OH_AVDataSource](capi-codecbase-oh-avdatasource.md) *dataSource | Pointer to user-defined data source.| 62 63**Returns** 64 65| Type| Description| 66| -- | -- | 67| [OH_AVSource](capi-avsource-oh-avsource.md) * | Pointer to the OH_AVSource instance created. If the operation fails, NULL is returned.<br>The possible causes of an operation failure are as follows:<br>1. The value of **dataSource** is nullptr.<br>2. The size of the data source is 0.<br>3. Setting the data source fails.<br>4. The memory is insufficient.<br>5. The decoder engine is nullptr.<br>6. dataSource->readAt == nullptr.| 68 69### OH_AVSource_CreateWithDataSourceExt() 70 71``` 72OH_AVSource *OH_AVSource_CreateWithDataSourceExt(OH_AVDataSourceExt *dataSource, void *userData) 73``` 74 75**Description** 76 77Creates an OH_AVSource instance with a user-defined data source. You can release the instance by calling [OH_AVSource_Destroy](#oh_avsource_destroy).<br>User-defined data can be passed to its callback functions through the **userData** parameter. 78 79**System capability**: SystemCapability.Multimedia.Media.Spliter 80 81**Since**: 20 82 83 84**Parameters** 85 86| Name| Description| 87| -- | -- | 88| [OH_AVDataSourceExt](capi-codecbase-oh-avdatasourceext.md) *dataSource | Pointer to the data source struct, which is used to obtain the input data.| 89| void *userData | Pointer to user-defined data.| 90 91**Returns** 92 93| Type| Description| 94| -- | -- | 95| [OH_AVSource](capi-avsource-oh-avsource.md) * | Pointer to the OH_AVSource instance created. If the operation fails, NULL is returned.<br>The possible causes of an operation failure are as follows:<br>1. The value of **dataSource** is nullptr.<br>2. The size of the data source is 0.<br>3. Setting the data source fails.<br>4. The memory is insufficient.<br>5. The decoder engine is nullptr.<br>6. dataSource->readAt == nullptr.| 96 97### OH_AVSource_CreateWithURI() 98 99``` 100OH_AVSource *OH_AVSource_CreateWithURI(char *uri) 101``` 102 103**Description** 104 105Creates an OH_AVSource instance based on a URI. You can release the instance by calling [OH_AVSource_Destroy](#oh_avsource_destroy). 106 107**System capability**: SystemCapability.Multimedia.Media.Spliter 108 109**Since**: 10 110 111 112**Parameters** 113 114| Name| Description| 115| -- | -- | 116| char *uri | URI of the media resource.| 117 118**Returns** 119 120| Type| Description| 121| -- | -- | 122| [OH_AVSource](capi-avsource-oh-avsource.md) * | Pointer to the OH_AVSource instance created. If the operation fails, NULL is returned.<br>The possible causes of an operation failure are as follows:<br>1. The network is abnormal.<br>2. The resource is invalid.<br>3. The file format is not supported.| 123 124### OH_AVSource_CreateWithFD() 125 126``` 127OH_AVSource *OH_AVSource_CreateWithFD(int32_t fd, int64_t offset, int64_t size) 128``` 129 130**Description** 131 132Creates an OH_AVSource instance based on an FD. You can release the instance by calling [OH_AVSource_Destroy](#oh_avsource_destroy).<br>If **offset** is not the start position of the file or **size** is not the file size, undefined errors such as creation failure and demultiplexing failure may occur due to incomplete data obtained. 133 134**System capability**: SystemCapability.Multimedia.Media.Spliter 135 136**Since**: 10 137 138 139**Parameters** 140 141| Name| Description| 142| -- | -- | 143| int32_t fd | FD of a media resource file.| 144| int64_t offset | Position from which data is to read.| 145| int64_t size | File size, in bytes.| 146 147**Returns** 148 149| Type| Description| 150| -- | -- | 151| [OH_AVSource](capi-avsource-oh-avsource.md) * | Pointer to the OH_AVSource instance created. If the operation fails, NULL is returned.<br>The possible causes of an operation failure are as follows:<br>1. The FD is invalid.<br>2. The offset is not the start position of the file.<br>3. The size is incorrect.<br>4. The resource is invalid.<br>5. The file format is not supported.| 152 153### OH_AVSource_Destroy() 154 155``` 156OH_AVErrCode OH_AVSource_Destroy(OH_AVSource *source) 157``` 158 159**Description** 160 161Destroys an OH_AVSource instance and clears internal resources. An instance can be destroyed only once.<br>The destroyed instance cannot be used until it is re-created. You are advised to set the pointer to NULL after the instance is destroyed. 162 163**System capability**: SystemCapability.Multimedia.Media.Spliter 164 165**Since**: 10 166 167 168**Parameters** 169 170| Name| Description| 171| -- | -- | 172| [OH_AVSource](capi-avsource-oh-avsource.md) *source | Pointer to an OH_AVSource instance.| 173 174**Returns** 175 176| Type| Description| 177| -- | -- | 178| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**:<br>1. The value of **source** is nullptr.<br>2. The value of **source** does not point to an OH_AVSource instance.| 179 180### OH_AVSource_GetSourceFormat() 181 182``` 183OH_AVFormat *OH_AVSource_GetSourceFormat(OH_AVSource *source) 184``` 185 186**Description** 187 188Obtains the basic information about a media resource file.<br>You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends. 189 190**System capability**: SystemCapability.Multimedia.Media.Spliter 191 192**Since**: 10 193 194 195**Parameters** 196 197| Name| Description| 198| -- | -- | 199| [OH_AVSource](capi-avsource-oh-avsource.md) *source | Pointer to an OH_AVSource instance.| 200 201**Returns** 202 203| Type| Description| 204| -- | -- | 205| [OH_AVFormat](_core.md#oh_avformat) * | Basic information about the file. If the operation fails, NULL is returned.<br>The possible causes of an operation failure are as follows:<br>1. The value of **source** is nullptr.<br>2. The pointer is null or does not point to an OH_AVSource instance.<br>3. The source is not initialized.| 206 207### OH_AVSource_GetTrackFormat() 208 209``` 210OH_AVFormat *OH_AVSource_GetTrackFormat(OH_AVSource *source, uint32_t trackIndex) 211``` 212 213**Description** 214 215Obtains the basic information about a track.<br>You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends. 216 217**System capability**: SystemCapability.Multimedia.Media.Spliter 218 219**Since**: 10 220 221 222**Parameters** 223 224| Name| Description| 225| -- | -- | 226| [OH_AVSource](capi-avsource-oh-avsource.md) *source | Pointer to an OH_AVSource instance.| 227| uint32_t trackIndex | Index of the track whose information is to be obtained.| 228 229**Returns** 230 231| Type| Description| 232| -- | -- | 233| [OH_AVFormat](_core.md#oh_avformat) * | Basic information about the track. If the operation fails, NULL is returned.<br>The possible causes of an operation failure are as follows:<br>1. The value of **source** is invalid (either nullptr or a pointer to a non-OH_AVSource instance).<br>2. The track index is out of range.<br>3. The source is not initialized.| 234 235### OH_AVSource_GetCustomMetadataFormat() 236 237``` 238OH_AVFormat *OH_AVSource_GetCustomMetadataFormat(OH_AVSource *source) 239``` 240 241**Description** 242 243Obtains the basic information about custom metadata.<br>You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends. 244 245**System capability**: SystemCapability.Multimedia.Media.Spliter 246 247**Since**: 18 248 249 250**Parameters** 251 252| Name| Description| 253| -- | -- | 254| [OH_AVSource](capi-avsource-oh-avsource.md) *source | Pointer to an OH_AVSource instance.| 255 256**Returns** 257 258| Type| Description| 259| -- | -- | 260| [OH_AVFormat](_core.md#oh_avformat) * | Basic information about the metadata. If the operation fails, NULL is returned.<br>The possible causes of an operation failure are as follows:<br>1. The value of **source** is nullptr.<br>2. The pointer is null or does not point to an OH_AVSource instance.<br>3. The source is not initialized.| 261