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 Codec
18 * @{
19 *
20 * @brief Defines APIs of the Codec module.
21 *
22 * The Codec module provides APIs for initializing the custom data and audio and video codecs,
23 * setting codec parameters, and controlling and transferring data.
24 *
25 * @since 4.1
26 * @version 2.0
27 */
28
29/**
30 * @file ICodecCallback.idl
31 *
32 * @brief Defines the callbacks used to report codec events and processing results of the input and output buffers.
33 *
34 *
35 *
36 * @since 4.1
37 * @version 2.0
38 */
39
40/**
41 * @brief Defines the path for the package of the Codec module APIs.
42 *
43 * @since 4.1
44 * @version 2.0
45 */
46package ohos.hdi.codec.v2_0;
47
48import ohos.hdi.codec.v2_0.CodecTypes;
49
50/**
51 * @brief Defines the callbacks of the Codec module.
52 *
53 * The following callbacks are provided:
54 * - Callback used to report component error events, command completion events, and port setting events.
55 * For details, see {@link EventHandler}.
56 * - Callback invoked when the input port has data processed in the buffer. For details, see {@link EmptyBufferDone}.
57 * - Callback invoked when the output port has data filled into the buffer. For details, see {@link FillBufferDone}.
58 * The callbacks are registered by using:
59 * - {@link CreateComponent} when a component is created.
60 * - {@link SetCallbacks} when the component is in the OMX_StateLoaded state.
61 */
62
63
64[callback] interface ICodecCallback {
65
66    /**
67     * @brief Reports an event, such as an error, a command completion event, and port setting changes.
68     *
69     * - When <b>event</b> is <b>CODEC_EVENT_CMD_COMPLETE</b> and <b>eventData</b> is null,
70     * <b>data2</b> indicates a state if <b>data1</b> is <b>CODEC_COMMAND_STATE_SET</b> and indicates a port if
71     * <b>data1</b> is any <b>CodecCommandType</b> other than <b>CODEC_COMMAND_STATE_SET</b>.
72     * - When <b>event</b> is <b>CODEC_EVENT_ERROR</b>, <b>data1</b> indicates an error code and <b>data2</b>
73     * and <b>eventData</b> are both <b>0</b>.
74     * - When <b>event</b> is <b>CODEC_EVENT_MARK</b>, <b>data1</b> and <b>data2</b> are both <b>0</b> and
75     * <b>eventData</b> points to the mark.
76     * - When <b>event</b> is <b>CODEC_EVENT_PORT_SETTINGS_CHANGED</b>, <b>data1</b> indicates a port and <b>data2</b>
77     * and <b>eventData</b> are <b>0</b>.
78     * - When <b>event</b> is <b>CODEC_EVENT_BUFFER_FLAG</b>, <b>data1</b> indicates a port, <b>data2</b> indicates a
79     * flag, and <b>eventData</b> is <b>0</b>.
80     * - When <b>event</b> is <b>CODEC_EVENT_RESOURCES_ACQUIRED</b> or <b>CODEC_EVENT_DYNAMIC_RESOURCES_AVAILABLE</b>,
81     * <b>data1</b>, <b>data2</b>, and <b>eventData</b> are <b>0</b>.
82     *
83     * @param event Indicates the type of the event to report. For details, see {@link CodecEventType}.
84     * @param info Indicates the pointer to the information to report. For details, see {@link EventInfo}.
85     *
86     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
87     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
88     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
89     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
90     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
91     *
92     * @since 4.1
93     */
94    EventHandler([in] enum CodecEventType event, [in] struct EventInfo info);
95
96    /**
97     * @brief Reports an event indicating that the encoding or decoding in the input buffer is complete.
98     *
99     *
100     * @param appData Indicates the application data. Generally, it is an upper-layer instance
101     * passed in for the callback.
102     * @param buffer Indicates information about the input buffer that was emptied. For details,
103     * see {@link OmxCodecBuffer}.
104     *
105     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
106     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
107     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
108     * @return Returns other values if the underlying layer returns a failure. For details about the
109     * error codes, see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
110     *
111     * @since 4.1
112     */
113    EmptyBufferDone([in] long appData, [in] struct OmxCodecBuffer buffer);
114
115    /**
116     * @brief Reports an event indicating that the output buffer is filled.
117     *
118     *
119     * @param appData Indicates the application data. Generally, it is an upper-layer instance
120     * passed in for the callback.
121     * @param buffer Indicates information about the buffer that was filled. For details, see {@link OmxCodecBuffer}.
122     *
123     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
124     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
125     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
126     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
127     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
128     *
129     * @since 4.1
130     */
131    FillBufferDone([in] long appData, [in] struct OmxCodecBuffer buffer);
132}
133