1# native_avsource.h 2 3## 概述 4 5声明用于音视频媒体数据解析的接口。 6 7**引用文件：** <multimedia/player_framework/native_avsource.h> 8 9**库：** libnative_media_avsource.so 10 11**系统能力：** SystemCapability.Multimedia.Media.Spliter 12 13**起始版本：** 10 14 15**相关模块：** [AVSource](capi-avsource.md) 16 17**相关示例：** [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) 18 19## 汇总 20 21### 结构体 22 23| 名称 | typedef关键字 | 描述 | 24| -- | -- | -- | 25| [OH_AVSource](capi-avsource-oh-avsource.md) | OH_AVSource | 为媒体资源接口定义native层对象。 | 26 27### 函数 28 29| 名称 | 描述 | 30| -- | -- | 31| [OH_AVSource *OH_AVSource_CreateWithDataSource(OH_AVDataSource *dataSource)](#oh_avsource_createwithdatasource) | 为用户自定义数据源的资源对象创建OH_AVSource实例，可以通过调用[OH_AVSource_Destroy](#oh_avsource_destroy)接口释放实例。 | 32| [OH_AVSource *OH_AVSource_CreateWithDataSourceExt(OH_AVDataSourceExt *dataSource, void *userData)](#oh_avsource_createwithdatasourceext) | 为用户自定义数据源的资源对象创建OH_AVSource实例，可以通过调用[OH_AVSource_Destroy](#oh_avsource_destroy)接口释放实例。回调支持传递用户自定义数据。 | 33| [OH_AVSource *OH_AVSource_CreateWithURI(char *uri)](#oh_avsource_createwithuri) | 为统一资源标识符对应的资源对象创建OH_AVSource实例，可以通过调用[OH_AVSource_Destroy](#oh_avsource_destroy)接口释放实例。 | 34| [OH_AVSource *OH_AVSource_CreateWithFD(int32_t fd, int64_t offset, int64_t size)](#oh_avsource_createwithfd) | 为文件描述符对应的资源对象创建OH_AVSource实例。可以通过调用[OH_AVSource_Destroy](#oh_avsource_destroy)接口释放实例。Note: 该接口如果传入offset不为文件起始位置，或size不为文件大小时，可能会因数据获取不完整导致OH_AVSource创建失败、后续解封装失败等未定义错误。 | 35| [OH_AVErrCode OH_AVSource_Destroy(OH_AVSource *source)](#oh_avsource_destroy) | 销毁OH_AVSource实例并清理内部资源。Note: 同一实例只能被销毁一次。销毁的实例在被重新创建之前不能再被使用。建议实例销毁成功后将指针置为NULL。 | 36| [OH_AVFormat *OH_AVSource_GetSourceFormat(OH_AVSource *source)](#oh_avsource_getsourceformat) | 获取媒体资源文件的基础信息。需要注意的是，指向的OH_AVFormat实例在生命周期结束时需调用者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 | 37| [OH_AVFormat *OH_AVSource_GetTrackFormat(OH_AVSource *source, uint32_t trackIndex)](#oh_avsource_gettrackformat) | 获取轨道的基础信息。需要注意的是，指向的OH_AVFormat实例在生命周期结束时需调用者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 | 38| [OH_AVFormat *OH_AVSource_GetCustomMetadataFormat(OH_AVSource *source)](#oh_avsource_getcustommetadataformat) | 获取自定义元数据的基础信息。需要注意的是，指向的OH_AVFormat实例在生命周期结束时需调用者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 | 39 40## 函数说明 41 42### OH_AVSource_CreateWithDataSource() 43 44``` 45OH_AVSource *OH_AVSource_CreateWithDataSource(OH_AVDataSource *dataSource) 46``` 47 48**描述** 49 50为用户自定义数据源的资源对象创建OH_AVSource实例，可以通过调用[OH_AVSource_Destroy](#oh_avsource_destroy)接口释放实例。 51 52**系统能力：** SystemCapability.Multimedia.Media.Spliter 53 54**起始版本：** 12 55 56 57**参数：** 58 59| 参数项 | 描述 | 60| -- | -- | 61| [OH_AVDataSource](capi-codecbase-oh-avdatasource.md) *dataSource | 用户自定义数据源。 | 62 63**返回：** 64 65| 类型 | 说明 | 66| -- | -- | 67| [OH_AVSource](capi-avsource-oh-avsource.md) * | 如果执行成功，则返回一个指向OH_AVSource实例的指针，否则返回NULL。<br> 可能的故障原因：<br> 1. dataSource为nullptr。<br> 2. dataSource->size == 0。<br> 3. 设置数据源失败。<br> 4. 内存不足。<br> 5. 解码器引擎为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**描述** 76 77为用户自定义数据源的资源对象创建OH_AVSource实例，可以通过调用[OH_AVSource_Destroy](#oh_avsource_destroy)接口释放实例。<br>回调支持通过userData传递用户自定义数据。 78 79**系统能力：** SystemCapability.Multimedia.Media.Spliter 80 81**起始版本：** 20 82 83 84**参数：** 85 86| 参数项 | 描述 | 87| -- | -- | 88| [OH_AVDataSourceExt](capi-codecbase-oh-avdatasourceext.md) *dataSource | 指向数据源结构体的指针，该结构体可用于获取输入数据。 | 89| void *userData | 指向用户自定义数据的指针。 | 90 91**返回：** 92 93| 类型 | 说明 | 94| -- | -- | 95| [OH_AVSource](capi-avsource-oh-avsource.md) * | 如果执行成功，则返回一个指向OH_AVSource实例的指针，否则返回NULL。<br> 可能的故障原因：<br> 1. dataSource为nullptr。<br> 2. dataSource->size == 0。<br> 3. 设置数据源失败。<br> 4. 内存不足。<br> 5. 解码器引擎为nullptr。<br> 6. dataSource->readAt == nullptr。 | 96 97### OH_AVSource_CreateWithURI() 98 99``` 100OH_AVSource *OH_AVSource_CreateWithURI(char *uri) 101``` 102 103**描述** 104 105为统一资源标识符对应的资源对象创建OH_AVSource实例，可以通过调用[OH_AVSource_Destroy](#oh_avsource_destroy)接口释放实例。 106 107**系统能力：** SystemCapability.Multimedia.Media.Spliter 108 109**起始版本：** 10 110 111 112**参数：** 113 114| 参数项 | 描述 | 115| -- | -- | 116| char *uri | 远程媒体资源的统一资源标识符。 | 117 118**返回：** 119 120| 类型 | 说明 | 121| -- | -- | 122| [OH_AVSource](capi-avsource-oh-avsource.md) * | 执行成功返回一个指向OH_AVSource实例的指针, 否则返回NULL。<br> 可能的故障原因：<br> 1. 网络异常。<br> 2. 资源无效。<br> 3. 文件格式不支持。 | 123 124### OH_AVSource_CreateWithFD() 125 126``` 127OH_AVSource *OH_AVSource_CreateWithFD(int32_t fd, int64_t offset, int64_t size) 128``` 129 130**描述** 131 132为文件描述符对应的资源对象创建OH_AVSource实例。可以通过调用[OH_AVSource_Destroy](#oh_avsource_destroy)接口释放实例。<br>该接口如果传入offset不为文件起始位置，或size不为文件大小时，可能会因数据获取不完整导致OH_AVSource创建失败、后续解封装失败等未定义错误。 133 134**系统能力：** SystemCapability.Multimedia.Media.Spliter 135 136**起始版本：** 10 137 138 139**参数：** 140 141| 参数项 | 描述 | 142| -- | -- | 143| int32_t fd | 数据资源的文件描述符。 | 144| int64_t offset | 开始读取数据的位置。 | 145| int64_t size | 文件的字节数大小。 | 146 147**返回：** 148 149| 类型 | 说明 | 150| -- | -- | 151| [OH_AVSource](capi-avsource-oh-avsource.md) * | 执行成功返回一个指向OH_AVSource实例的指针, 否则返回NULL。<br> 可能的故障原因：<br> 1. fd无效。<br> 2. 传入offset不是文件起始位置。<br> 3. size错误。<br> 4. 资源无效。<br> 5. 文件格式不支持。 | 152 153### OH_AVSource_Destroy() 154 155``` 156OH_AVErrCode OH_AVSource_Destroy(OH_AVSource *source) 157``` 158 159**描述** 160 161销毁OH_AVSource实例并清理内部资源。同一实例只能被销毁一次。<br>销毁的实例在被重新创建之前不能再被使用。建议实例销毁成功后将指针置为NULL。 162 163**系统能力：** SystemCapability.Multimedia.Media.Spliter 164 165**起始版本：** 10 166 167 168**参数：** 169 170| 参数项 | 描述 | 171| -- | -- | 172| [OH_AVSource](capi-avsource-oh-avsource.md) *source | 指向OH_AVSource实例的指针。 | 173 174**返回：** 175 176| 类型 | 说明 | 177| -- | -- | 178| [OH_AVErrCode](_core.md#oh_averrcode-1) | AV_ERR_OK：操作成功。<br> AV_ERR_INVALID_VAL：<br>1. source指针无效，空指针。<br>2. 非OH_AVSource实例。 | 179 180### OH_AVSource_GetSourceFormat() 181 182``` 183OH_AVFormat *OH_AVSource_GetSourceFormat(OH_AVSource *source) 184``` 185 186**描述** 187 188获取媒体资源文件的基础信息。<br>需要注意的是，指向的OH_AVFormat实例在生命周期结束时需开发者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 189 190**系统能力：** SystemCapability.Multimedia.Media.Spliter 191 192**起始版本：** 10 193 194 195**参数：** 196 197| 参数项 | 描述 | 198| -- | -- | 199| [OH_AVSource](capi-avsource-oh-avsource.md) *source | 指向OH_AVSource实例的指针。 | 200 201**返回：** 202 203| 类型 | 说明 | 204| -- | -- | 205| [OH_AVFormat](_core.md#oh_avformat) * | 执行成功返回文件的基础信息，否则返回NULL。<br> 可能的故障原因：<br> 1. source指针无效。<br> 2. 空指针或非OH_AVSource实例。<br> 3. source没有初始化。 | 206 207### OH_AVSource_GetTrackFormat() 208 209``` 210OH_AVFormat *OH_AVSource_GetTrackFormat(OH_AVSource *source, uint32_t trackIndex) 211``` 212 213**描述** 214 215获取轨道的基础信息。<br>需要注意的是，指向的OH_AVFormat实例在生命周期结束时需开发者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 216 217**系统能力：** SystemCapability.Multimedia.Media.Spliter 218 219**起始版本：** 10 220 221 222**参数：** 223 224| 参数项 | 描述 | 225| -- | -- | 226| [OH_AVSource](capi-avsource-oh-avsource.md) *source | 指向OH_AVSource实例的指针。 | 227| uint32_t trackIndex | 需要获取信息的轨道的索引。 | 228 229**返回：** 230 231| 类型 | 说明 | 232| -- | -- | 233| [OH_AVFormat](_core.md#oh_avformat) * | 执行成功返回轨道的基础信息，否则返回NULL。<br> 可能的故障原因：<br> 1. source指针无效，空指针或非OH_AVSource实例。<br> 2. 轨道的索引超出范围。<br> 3. source没有初始化。 | 234 235### OH_AVSource_GetCustomMetadataFormat() 236 237``` 238OH_AVFormat *OH_AVSource_GetCustomMetadataFormat(OH_AVSource *source) 239``` 240 241**描述** 242 243获取自定义元数据的基础信息。<br>需要注意的是，指向的OH_AVFormat实例在生命周期结束时需开发者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 244 245**系统能力：** SystemCapability.Multimedia.Media.Spliter 246 247**起始版本：** 18 248 249 250**参数：** 251 252| 参数项 | 描述 | 253| -- | -- | 254| [OH_AVSource](capi-avsource-oh-avsource.md) *source | 指向OH_AVSource实例的指针。 | 255 256**返回：** 257 258| 类型 | 说明 | 259| -- | -- | 260| [OH_AVFormat](_core.md#oh_avformat) * | 执行成功返回元数据的基础信息，否则返回NULL。<br> 可能的故障原因：<br> 1. source指针无效。<br> 2. 空指针或非OH_AVSource实例。<br> 3. source没有初始化。 | 261 262 263