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_avdemuxer.h
18 *
19 * @brief Provides audio and video demuxer capabilities.
20 *
21 * @kit AVCodecKit
22 * @library libnative_media_avdemuxer.so
23 * @syscap SystemCapability.Multimedia.Media.Spliter
24 * @since 10
25 */
26
27#ifndef NATIVE_AVDEMUXER_H
28#define NATIVE_AVDEMUXER_H
29
30#include <stdint.h>
31#include "native_avcodec_base.h"
32#include "native_avsource.h"
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/**
39 * @brief Forward declaration of OH_AVDemuxer.
40 *
41 * @since 10
42 */
43typedef struct OH_AVDemuxer OH_AVDemuxer;
44/**
45 * @brief Forward declaration of DRM_MediaKeySystemInfo.
46 *
47 * @since 11
48 */
49typedef struct DRM_MediaKeySystemInfo DRM_MediaKeySystemInfo;
50
51/**
52* @brief Callback for getting media key system information from media source.
53* @since 11
54* @version 1.0
55*/
56typedef void (*DRM_MediaKeySystemInfoCallback)(DRM_MediaKeySystemInfo* mediaKeySystemInfo);
57
58/**
59 * @brief Call back will be invoked when updating DRM information.
60 * @param demuxer Player OH_AVDemuxer.
61 * @param mediaKeySystemInfo DRM information.
62 * @return DRM_ERR_INVALID_VAL when the params checked failure, return DRM_ERR_OK when function called successfully.
63 * @since 12
64 */
65typedef void (*Demuxer_MediaKeySystemInfoCallback)(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo);
66
67/**
68 * @brief Creates an OH_AVDemuxer instance for getting samples from source.
69 * Free the resources of the instance by calling OH_AVDemuxer_Destroy.
70 * @syscap SystemCapability.Multimedia.Media.Spliter
71 * @param source Pointer to an OH_AVSource instance.
72 * @return Returns a pointer to an OH_AVDemuxer instance if the execution is successful, otherwise returns nullptr.
73 * Possible failure causes:
74 *  1. source is invalid.
75 * @since 10
76*/
77OH_AVDemuxer *OH_AVDemuxer_CreateWithSource(OH_AVSource *source);
78
79/**
80 * @brief Destroy the OH_AVDemuxer instance and free the internal resources.
81 * The same instance can only be destroyed once. The destroyed instance
82 * should not be used before it is created again. It is recommended setting
83 * the instance pointer to NULL right after the instance is destroyed successfully.
84 * @syscap SystemCapability.Multimedia.Media.Spliter
85 * @param demuxer Pointer to an OH_AVDemuxer instance.
86 * @return Returns AV_ERR_OK if the execution is successful,
87 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
88 *          {@link AV_ERR_INVALID_VAL} demuxer is invalid.
89 * @since 10
90*/
91OH_AVErrCode OH_AVDemuxer_Destroy(OH_AVDemuxer *demuxer);
92
93/**
94 * @brief The specified track is selected and the demuxer will read samples from
95 * this track. Multiple tracks are selected by calling this interface multiple times
96 * with different track indexes. Only the selected tracks are valid when calling
97 * OH_AVDemuxer_ReadSample to read samples. The interface returns AV_ERR_OK and the
98 * track is selected only once if the same track is selected multiple times.
99 * @syscap SystemCapability.Multimedia.Media.Spliter
100 * @param demuxer Pointer to an OH_AVDemuxer instance.
101 * @param trackIndex The index of the selected track.
102 * @return Returns AV_ERR_OK if the execution is successful,
103 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
104 *          {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized,
105 *                                     trackIndex is out of range, track is not supported to be read.
106 * @since 10
107*/
108OH_AVErrCode OH_AVDemuxer_SelectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex);
109
110/**
111 * @brief The specified selected track is unselected. The unselected track's sample
112 * can not be read from demuxer. Multiple selected tracks are unselected by calling
113 * this interface multiple times with different track indexes. The interface returns
114 * AV_ERR_OK and the track is unselected only once if the same track is unselected
115 * multiple times.
116 * @syscap SystemCapability.Multimedia.Media.Spliter
117 * @param demuxer Pointer to an OH_AVDemuxer instance.
118 * @param trackIndex The index of the unselected track.
119 * @return Returns AV_ERR_OK if the execution is successful,
120 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
121 *          {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized.
122 * @since 10
123*/
124OH_AVErrCode OH_AVDemuxer_UnselectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex);
125
126/**
127 * @brief Get the current encoded sample and sample-related information from the specified
128 * track. The track index must be selected before reading sample. The demuxer will advance
129 * automatically after calling this interface.
130 * @syscap SystemCapability.Multimedia.Media.Spliter
131 * @param demuxer Pointer to an OH_AVDemuxer instance.
132 * @param trackIndex The index of the track from which read an encoded sample.
133 * @param sample The OH_AVMemory handle pointer to the buffer storing the sample data.
134 * @param info The OH_AVCodecBufferAttr handle pointer to the buffer storing sample information.
135 * @return Returns AV_ERR_OK if the execution is successful,
136 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
137 *          {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized, sample is invalid,
138 *                                     trackIndex is out of range.
139 *          {@link AV_ERR_OPERATE_NOT_PERMIT} trackIndex has not been selected.
140 *          {@link AV_ERR_NO_MEMORY} capability of sample is not enough to store all frame data.
141 *          {@link AV_ERR_UNKNOWN} failed to read or parse frame from file.
142 * @deprecated since 11
143 * @useinstead OH_AVDemuxer_ReadSampleBuffer
144 * @since 10
145*/
146OH_AVErrCode OH_AVDemuxer_ReadSample(OH_AVDemuxer *demuxer, uint32_t trackIndex,
147    OH_AVMemory *sample, OH_AVCodecBufferAttr *info);
148
149/**
150 * @brief Get the current encoded sample and sample-related information from the specified
151 * track. The track index must be selected before reading sample. The demuxer will advance
152 * automatically after calling this interface.
153 * @syscap SystemCapability.Multimedia.Media.Spliter
154 * @param demuxer Pointer to an OH_AVDemuxer instance.
155 * @param trackIndex The index of the track from which read an encoded sample.
156 * @param sample The OH_AVBuffer handle pointer to the buffer storing the sample data and corresponding attribute.
157 * @return Returns AV_ERR_OK if the execution is successful,
158 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
159 *          {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized, sample is invalid,
160 *                                     trackIndex is out of range.
161 *          {@link AV_ERR_OPERATE_NOT_PERMIT} trackIndex has not been selected.
162 *          {@link AV_ERR_NO_MEMORY} capability of sample is not enough to store frame data.
163 *          {@link AV_ERR_UNKNOWN} failed to read or parse frame from file.
164 * @since 11
165*/
166OH_AVErrCode OH_AVDemuxer_ReadSampleBuffer(OH_AVDemuxer *demuxer, uint32_t trackIndex,
167    OH_AVBuffer *sample);
168
169/**
170 * @brief All selected tracks seek near to the requested time according to the seek mode.
171 * @syscap SystemCapability.Multimedia.Media.Spliter
172 * @param demuxer Pointer to an OH_AVDemuxer instance.
173 * @param millisecond The millisecond for seeking, the timestamp is the position of
174 * the file relative to the start of the file.
175 * @param mode The mode for seeking. See {@link OH_AVSeekMode}.
176 * @return Returns AV_ERR_OK if the execution is successful,
177 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
178 *          {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized,
179 *                                     millisecond is out of range.
180 *          {@link AV_ERR_OPERATE_NOT_PERMIT} trackIndex has not been selected, resource is unseekable.
181 *          {@link AV_ERR_UNKNOWN} failed to seek.
182 * @since 10
183*/
184OH_AVErrCode OH_AVDemuxer_SeekToTime(OH_AVDemuxer *demuxer, int64_t millisecond, OH_AVSeekMode mode);
185
186/**
187 * @brief Method to set player media key system info callback.
188 * @syscap SystemCapability.Multimedia.Media.Spliter
189 * @param demuxer Pointer to an OH_AVDemuxer instance
190 * @param callback object pointer.
191 * @return {@link AV_ERR_OK} 0 - Success
192 *         {@link AV_ERR_OPERATE_NOT_PERMIT} 2 - If the demuxer engine is not inited or init failed.
193 *         {@link AV_ERR_INVALID_VAL} 3 - If the demuxer instance is nullptr or invalid.
194 * @since 11
195 */
196OH_AVErrCode OH_AVDemuxer_SetMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer,
197    DRM_MediaKeySystemInfoCallback callback);
198
199/**
200 * @brief Method to set player media key system info callback.
201 * @syscap SystemCapability.Multimedia.Media.Spliter
202 * @param demuxer Pointer to an OH_AVDemuxer instance
203 * @param callback object pointer.
204 * @return {@link AV_ERR_OK} 0 - Success
205 *         {@link AV_ERR_OPERATE_NOT_PERMIT} 2 - If the demuxer engine is not inited or init failed.
206 *         {@link AV_ERR_INVALID_VAL} 3 - If the demuxer instance is nullptr or invalid.
207 * @since 12
208 */
209OH_AVErrCode OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer,
210    Demuxer_MediaKeySystemInfoCallback callback);
211
212/**
213 * @brief Obtains media key system info to create media key session.
214 * @syscap SystemCapability.Multimedia.Media.Spliter
215 * @param demuxer Pointer to an OH_AVDemuxer instance
216 * @param mediaKeySystemInfo Indicates the media key system info which ram space allocated by callee and
217 * released by caller.
218 * @return {@link AV_ERR_OK} 0 - Success
219 *         {@link AV_ERR_OPERATE_NOT_PERMIT} 2 - If the demuxer engine is not inited or init failed.
220 *         {@link AV_ERR_INVALID_VAL} 3 - If the demuxer instance is nullptr or invalid
221 *          or the mediaKeySystemInfo is nullptr.
222 * @since 11
223 */
224OH_AVErrCode OH_AVDemuxer_GetMediaKeySystemInfo(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo);
225
226#ifdef __cplusplus
227}
228#endif
229
230#endif // NATIVE_AVDEMUXER_H
231