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