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 * @file native_avsource.h
18 *
19 * @brief Provides audio and video suorce capabilities.
20 *
21 * @kit AVCodecKit
22 * @library libnative_media_avsource.so
23 * @syscap SystemCapability.Multimedia.Media.Spliter
24 * @since 10
25 */
26
27#ifndef NATIVE_AVSOURCE_H
28#define NATIVE_AVSOURCE_H
29
30#include <stdint.h>
31#include "native_avcodec_base.h"
32#include "native_averrors.h"
33#include "native_avformat.h"
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/**
40 * @brief Forward declaration of OH_AVSource.
41 *
42 * @since 10
43 */
44typedef struct OH_AVSource OH_AVSource;
45
46/**
47 * @brief Creates an OH_AVSource instance that models the media with dataSource.
48 * @syscap SystemCapability.Multimedia.Media.Spliter
49 * @param dataSource An Struct for a remote media resource.
50 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns nullptr.
51 * Possible failure causes:
52 *  1. dataSource is nullptr.
53 *  2. dataSource->size == 0.
54 *  3. set data source failed.
55 *  4. out of memory.
56 *  5. demuxer engine is nullptr.
57 * @since 12
58*/
59OH_AVSource *OH_AVSource_CreateWithDataSource(OH_AVDataSource *dataSource);
60
61/**
62 * @brief Creates an OH_AVSource instance that models the media at the URI.
63 * @syscap SystemCapability.Multimedia.Media.Spliter
64 * @param uri An URI for a remote media resource.
65 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns nullptr.
66 * Possible failure causes:
67 *  1. network anomaly.
68 *  2. resource is invalid.
69 *  3. file format is not supported.
70 * @since 10
71*/
72OH_AVSource *OH_AVSource_CreateWithURI(char *uri);
73
74/**
75 * @brief Creates an OH_AVSource instance that models the media at the FileDescriptor.
76 * @syscap SystemCapability.Multimedia.Media.Spliter
77 * @param fd The fileDescriptor of data source.
78 * @param offset The offset into the file to start reading.
79 * @param size The file size in bytes.
80 * @return Returns a pointer to an OH_AVSource instance if the execution is successful, otherwise returns nullptr.
81 * Possible failure causes:
82 *  1. fd is invalid.
83 *  2. offset is not start pos of resource.
84 *  3. size error.
85 *  4. resource is invalid.
86 *  5. file format is not supported.
87 * @since 10
88*/
89OH_AVSource *OH_AVSource_CreateWithFD(int32_t fd, int64_t offset, int64_t size);
90
91/**
92 * @brief Destroy the OH_AVSource instance and free the internal resources.
93 * @syscap SystemCapability.Multimedia.Media.Spliter
94 * @param source Pointer to an OH_AVSource instance.
95 * @return Returns AV_ERR_OK if the execution is successful,
96 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
97 *          {@link AV_ERR_INVALID_VAL} source is invalid.
98 * @since 10
99*/
100OH_AVErrCode OH_AVSource_Destroy(OH_AVSource *source);
101
102/**
103 * @brief Get the format info of source.
104 * @syscap SystemCapability.Multimedia.Media.Spliter
105 * @param source Pointer to an OH_AVSource instance.
106 * @return Returns the source's format info if the execution is successful, otherwise returns nullptr.
107 * Possible failure causes:
108 *  1. source is invalid.
109 * @since 10
110*/
111OH_AVFormat *OH_AVSource_GetSourceFormat(OH_AVSource *source);
112
113/**
114 * @brief Get the format info of track.
115 * @syscap SystemCapability.Multimedia.Media.Spliter
116 * @param source Pointer to an OH_AVSource instance.
117 * @param trackIndex The track index to get format.
118 * @return Returns the track's format info if the execution is successful, otherwise returns nullptr.
119 * Possible failure causes:
120 *  1. source is invalid.
121 *  2. trackIndex is out of range.
122 * @since 10
123*/
124OH_AVFormat *OH_AVSource_GetTrackFormat(OH_AVSource *source, uint32_t trackIndex);
125
126#ifdef __cplusplus
127}
128#endif
129
130#endif // NATIVE_AVSOURCE_H