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 ICodecComponent.idl
31 *
32 * @brief Declares the APIs for codec components.
33 *
34 * You can use these APIs to obtain component information, send commands to components,
35 * set component parameters, and control and transfer buffer data.
36 * After creating a component, you can use these APIs to implement encoding and decoding.
37 *
38 * @since 4.1
39 * @version 2.0
40 */
41
42/**
43 * @brief Defines the path for the package of the Codec module APIs.
44 *
45 * @since 4.1
46 * @version 2.0
47 */
48package ohos.hdi.codec.v2_0;
49
50import ohos.hdi.codec.v2_0.CodecTypes;
51import ohos.hdi.codec.v2_0.ICodecCallback;
52
53/**
54 * @brief Defines the APIs for codec components.
55 *
56 * The APIs can be used to:
57 * - Obtain the component version.
58 * - Obtain and set component parameters.
59 * - Send a command to a component and obtain the component state.
60 * - Set callbacks.
61 * - Set or release the buffer used by a component.
62 * - Manage the input and output buffers for encoding and decoding.
63 * For details, see the description of the APIs.
64 */
65
66interface ICodecComponent {
67
68    /**
69     * @brief Obtains the version of this codec component.
70     *
71     *
72     * @param verInfo Indicates the pointer to the component version information. For details, see {@link CompVerInfo}.
73     *
74     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
75     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
76     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
77     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
78     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
79     *
80     * @since 4.1
81     */
82    GetComponentVersion([out] struct CompVerInfo verInfo);
83
84	/**
85     * @brief Sends a command to this component.
86     *
87     * If the command is used to set the component state, a callback will be invoked to return the result.
88     * There is no callback invoked for other commands.
89     *
90     * @param cmd Indicates the command to send. For details, see {@link CodecCommandType}.
91     * @param param Indicates the parameter carried in the command.
92     * - If <b>cmd</b> is <b>CODEC_COMMAND_STATE_SET</b>, <b>param</b> can be set to any value of {@link CodecStateType}.
93     * - If <b>cmd</b> is <b>CODEC_COMMAND_FLUSH</b>, <b>CODEC_COMMAND_PORT_DISABLE</b>, <b>CODEC_COMMAND_PORT_ENABLE</b>,
94     * or <b>CODEC_COMMAND_MARK_BUFFER</b>, <b>param</b> is the target port.
95     * @param cmdData Indicates the pointer to the <b>OMX_MARKTYPE</b> structure when <b>cmd</b>
96     * is <b>CODEC_COMMAND_MARK_BUFFER</b>.
97     *
98     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
99     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
100     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
101     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
102     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
103     *
104     * @since 4.1
105     */
106    SendCommand([in] enum CodecCommandType cmd, [in] unsigned int param, [in] byte[] cmdData);
107
108    /**
109     * @brief Obtains the parameter settings of this component.
110     *
111     * For the component in a state other than OMX_StateInvalid, you can use this API to obtain the
112     * component's parameter settings. For details about the component states, see {@link OMX_STATETYPE}.
113     *
114     * @param index Indicates the index of the structure to fill. For details,
115     * see <b>OMX_INDEXTYPE</b> defined by OMX IL.
116     * @param inParamStruct Indicates the pointer to the application allocated structure to be filled by the component.
117     * @param outParamStruct Indicates the pointer to the application allocated structure filled by the component.
118     *
119     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
120     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
121     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
122     * @return Returns other values if the underlying layer returns a failure. For details about
123     * the error codes, see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
124     *
125     * @since 4.1
126     */
127    GetParameter([in] unsigned int index, [in] byte[] inParamStruct, [out] byte[] outParamStruct);
128
129    /**
130     * @brief Sets parameters for this component, that is, sends an initialization
131     * parameter structure to the component.
132     *
133     * You can use this API to set component parameters when:
134     * - The component is in the OMX_StateLoaded state (the component has been loaded).
135     * - The component is in the OMX_StateWaitForResources state (the component is waiting for required resources).
136     * - The component or port is disabled.
137     * For details about the component states, see {@link OMX_STATETYPE}.
138     *
139     * @param index Indicates the index of the structure to set. For details, see <b>OMX_INDEXTYPE</b> defined by OMX IL.
140     * @param paramStruct Indicates the pointer to the application allocated structure used to set
141     * parameters for this component.
142     *
143     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
144     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
145     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
146     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
147     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
148     *
149     * @since 4.1
150     */
151    SetParameter([in] unsigned int index, [in] byte[] paramStruct);
152
153    /**
154     * @brief Obtains the configuration of this component.
155     *
156     * You can use this API to obtain the component configuration after a component is loaded.
157     *
158     * @param index Indicates the index of the structure to fill. For details, see {@link OMX_INDEXTYPE}.
159     * @param inCfgStruct Indicates the pointer to the application allocated structure to be filled by the component.
160     * @param outCfgStruct Indicates the pointer to the application allocated structure filled by the component.
161     *
162     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
163     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
164     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
165     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
166     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
167     *
168     * @since 4.1
169     */
170    GetConfig([in] unsigned int index, [in] byte[] inCfgStruct, [out] byte[] outCfgStruct);
171
172    /**
173     * @brief Sets the component configuration.
174     *
175     * You can use this API to set the component configuration after a component is loaded.
176     *
177     * @param index Indicates the index of the structure to set. For details, see {@link OMX_INDEXTYPE}.
178     * @param cfgStruct Indicates the pointer to the application allocated structure used to set the component.
179     *
180     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
181     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
182     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
183     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
184     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
185     *
186     * @since 4.1
187     */
188    SetConfig([in] unsigned int index, [in] byte[] cfgStruct);
189
190    /**
191     * @brief Obtains the extended index of this component based on a given string.
192     *
193     * The extended string can be converted into an OpenMAX IL structure index, which is used (as an input parameter)
194     * in {@link GetParameter} or {@link SetParameter}.
195     *
196     * @param paramName Indicates the string that can be converted into the structure index.
197     * @param indexType Indicates the structure index obtained. For details, see {@link OMX_INDEXTYPE}.
198     *
199     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
200     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
201     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
202     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
203     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
204     *
205     * @since 4.1
206     */
207    GetExtensionIndex([in] String paramName, [out] unsigned int indexType);
208
209    /**
210     * @brief Obtains the current state of this component.
211     *
212     *
213     *
214     * @param state Indicates the pointer to the state obtained. For details about the component
215     * states, see {@link CodecStateType}.
216     *
217     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
218     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
219     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
220     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
221     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
222     *
223     * @since 4.1
224     */
225    GetState([out] enum CodecStateType state);
226
227    /**
228     * @brief Sets up tunneling for this component.
229     *
230     * For a component in the OMX_StateLoaded state (the component is loaded), you can use this API
231     * to determine whether
232     * tunneling is possible and if yes, to set up the tunneling.
233     * For details about the component states, see {@link OMX_STATETYPE}.
234     *
235     * @param port Indicates the port on the component used for the setting.
236     * @param tunneledComp Indicates the handle of the tunnel component.
237     * @param tunneledPort Indicates the port on the component to be used for tunneling.
238     * @param inTunnelSetup Indicates the pointer to the tunnel setup structure {@link OMX_TUNNELSETUPTYPE} to set.
239     * @param outTunnelSetup Indicates the pointer to the tunnel setup structure {@link OMX_TUNNELSETUPTYPE} set.
240     *
241     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
242     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
243     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
244     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
245     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
246     *
247     * @since 4.1
248     */
249    ComponentTunnelRequest([in] unsigned int port, [in] int tunneledComp, [in] unsigned int tunneledPort, [in]
250    struct CodecTunnelSetupType inTunnelSetup, [out] struct CodecTunnelSetupType outTunnelSetup);
251
252    /**
253     * @brief Requests the component to use a buffer that is already allocated by another component.
254     *
255     * This API is used when:
256     * - The component is in the OMX_StateLoaded state (the component is loaded) and has received a request for
257     * changing the state to OMX_StateIdle.
258     * - The component is in the OMX_StateWaitForResources state, the required resources are available, and the
259     * component is ready to enter the OMX_StateIdle state.
260     * - The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port.
261     * For details about the component states, see {@link OMX_STATETYPE}.
262     *
263     * @param portIndex Indicates the component port.
264     * @param inBuffer Indicates the pointer to the structure of the buffer to be used. For details, see {@link OmxCodecBuffer}.
265     * @param outBuffer Indicates the pointer to the structure of the buffer to be used. For details, see {@link OmxCodecBuffer}.
266     *
267     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
268     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
269     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
270     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
271     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
272     *
273     * @since 4.1
274     */
275    UseBuffer([in] unsigned int portIndex, [in] struct OmxCodecBuffer inBuffer, [out] struct OmxCodecBuffer outBuffer);
276
277    /**
278     * @brief Requests the component to allocate a new buffer.
279     *
280     * This API is used to request a new buffer from a component when:
281     * - The component is in the OMX_StateLoaded state and has received a request for changing the
282     * state to OMX_StateIdle.
283     * - The component is in the OMX_StateWaitForResources state, the required resources are available,
284     * and the component is ready to enter the OMX_StateIdle state.
285     * - The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port.
286     * For details about the component states, see {@link OMX_STATETYPE}.
287     *
288     * @param portIndex Indicates the component port.
289     * @param inBuffer Indicates the pointer to the structure of the buffer to be allocated. For details about
290     * the structure, see {@link OmxCodecBuffer}.
291     * @param outBuffer Indicates the pointer to the structure of the buffer allocated. For details about the
292     * structure, see {@link OmxCodecBuffer}.
293     *
294     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
295     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
296     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
297     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
298     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
299     *
300     * @since 4.1
301     */
302    AllocateBuffer([in] unsigned int portIndex, [in] struct OmxCodecBuffer inBuffer,
303    [out] struct OmxCodecBuffer outBuffer);
304
305    /**
306     * @brief Releases a buffer.
307     *
308     * This API is used when:
309     * - The component is in the OMX_StateIdle state and has received a request for changing the
310     * state to OMX_StateLoaded.
311     * - The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port.
312     * For details about the component states, see {@link OMX_STATETYPE}.
313     * - This API can be called at any time. However, if it is not called in any of the previous conditions,
314     * the component may report an <b>OMX_ErrorPortUnpopulated</b> event.
315     *
316     * @param portIndex Indicates the component port.
317     * @param buffer Indicates the pointer to the structure of the buffer to release. For details about the
318     * structure, see {@link OmxCodecBuffer}.
319     *
320     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
321     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
322     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
323     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
324     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
325     *
326     * @since 4.1
327     */
328    FreeBuffer([in] unsigned int portIndex, [in] struct OmxCodecBuffer buffer);
329
330    /**
331     * @brief Empties a buffer.
332     *
333     * This API can be called when the component is in the OMX_StateExecuting or OMX_StatePause state. For details
334     * about the component states, see {@link OMX_STATETYPE}.
335     *
336     * @param buffer Indicates the pointer to the structure of the buffer to empty. For details about the structure,
337     * see {@link OmxCodecBuffer}.
338     *
339     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
340     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
341     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
342     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
343     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
344     *
345     * @since 4.1
346     */
347    EmptyThisBuffer([in] struct OmxCodecBuffer buffer);
348
349    /**
350     * @brief Fills a buffer with the encoding and decoding output by this component.
351     *
352     * This API can be called when the component is in the OMX_StateExecuting or OMX_StatePause state. For details
353     * about the component states, see {@link OMX_STATETYPE}.
354     *
355     * @param buffer Indicates the pointer to the structure of the buffer to be filled. For details about the
356     * structure, see {@link OmxCodecBuffer}.
357     *
358     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
359     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
360     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
361     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
362     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
363     *
364     * @since 4.1
365     */
366    FillThisBuffer([in] struct OmxCodecBuffer buffer);
367
368    /**
369     * @brief Sets callbacks for this component.
370     *
371     * The callbacks will be invoked to report an event or report available input or output information when the
372     * component is in the OMX_StateLoaded state. For details about the component states, see {@link OMX_STATETYPE}.
373     *
374     * @param callbacks Indicates the pointer to the {@link ICodecCallback} object.
375     * @param appData Indicates the pointer to an application-defined value that will be returned by the callback.
376     *
377     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
378     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
379     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
380     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
381     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
382     *
383     * @since 4.1
384     */
385    SetCallbacks([in] ICodecCallback callbacks, [in] long appData);
386
387    /**
388     * @brief Deinitializes this component.
389     *
390     * This API will deinitialize and close a component in the OMX_StateLoaded state. For details about the
391     * component states, see {@link OMX_STATETYPE}.
392     *
393     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
394     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
395     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
396     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
397     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
398     *
399     * @since 4.1
400     */
401    ComponentDeInit();
402
403    /**
404     * @brief Uses the image provided by EGL as a buffer on the specified port.
405     *
406     * This API is used when:
407     * - The component is in the OMX_StateLoaded state and has received a request for changing the
408     * state to OMX_StateIdle.
409     * - The component is in the OMX_StateWaitForResources state, the required resources are available,
410     * and the component is ready to enter the OMX_StateIdle state.
411     * - The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port.
412     * For details about the component states, see {@link OMX_STATETYPE}.
413     *
414     * @param portIndex Indicates the component port.
415     * @param inBuffer Indicates the pointer to the {@link OmxCodecBuffer} structure.
416     * @param outBuffer Indicates the pointer to the {@link OmxCodecBuffer} structure.
417     * @param eglImage Indicates the pointer to the image allocated by EGL.
418     *
419     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
420     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
421     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
422     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
423     * see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
424     *
425     * @since 4.1
426     */
427    UseEglImage([in] unsigned int portIndex, [in] struct OmxCodecBuffer inBuffer, [out] struct OmxCodecBuffer
428    outBuffer, [in] byte[] eglImage);
429
430    /**
431     * @brief Obtains the component role based on the index.
432     *
433     *
434     *
435     * @param role Indicates the role name obtained.
436     * @param index Indicates the index of the role. A component supports multiple roles.
437     *
438     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
439     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
440     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
441     * @return Returns other values if the underlying layer returns a failure. For details about the error
442     * codes, see <b>OMX_ERRORTYPE</b> defined by OpenMAX IL.
443     *
444     * @since 4.1
445     */
446    ComponentRoleEnum([out] unsigned char[] role, [in] unsigned int index);
447}