1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 

    17 /**

    18 @file

    19 @internalComponent

    20 */

    21 

    22 

    23 #ifndef OMXILPORTMANAGERIF_H

    24 #define OMXILPORTMANAGERIF_H

    25 

    26 #include <openmax/il/khronos/v1_x/OMX_Component.h>

    27 

    28 // Forward declarations

    29 class COmxILProcessingFunction;

    30 class MOmxILCallbackManagerIf;

    31 class COmxILPort;

    32 

    33 /**

    34    OpenMAX IL Port Manager Interface to be used by Port Manager

    35    implementations.

    36  */

    37 class MOmxILPortManagerIf

    38 	{

    39 

    40 public:

    41 

    42 	virtual ~MOmxILPortManagerIf();

    43 

    44 	/**

    45 	   This method is used at component's construction time, i.e., in a factory

    46 	   method of the final component implementation. The main component object

    47 	   uses this method to add the component's ports to its port manager

    48 	   instance. This is the only method that needs to be exported by Port

    49 	   Manager's implementations. All other Port Managers public methods are

    50 	   for internal use in the component framework.

    51 

    52 	   @param aPort The pointer of the port instance to be added.

    53 

    54 	   @param aDirection The direction of the port being added.

    55 

    56 	   @return A Symbian error code indicating if the function call was

    57 	   successful.  KErrNone on success, otherwise another of the system-wide

    58 	   error codes.

    59 	*/

    60 	virtual TInt AddPort(const COmxILPort* aPort,

    61 						 OMX_DIRTYPE aDirection) = 0;

    62 

    63 

    64 /**

    65    Port Manager's interface for OpenMAX IL Standard API component

    66    functions. These are for interal use in the component framework and should

    67    not be exported by Port Manager implementations.

    68 

    69    */

    70 

    71 

    72 	/**

    73 	   Port Manager's version of the GetParameter OpenMAX IL component

    74 	   API

    75 

    76 	   @param aParamIndex The index of the OpenMAX IL param structure.

    77 

    78 	   @param apComponentParameterStructure The pointer to the IL

    79 	   client-allocated param structure to be filled by the Port Manager

    80 	   (tipically delegated to the port)

    81 

    82 	   @return OMX_ERRORTYPE

    83 	*/

    84 	virtual OMX_ERRORTYPE GetParameter(

    85 		OMX_INDEXTYPE aParamIndex,

    86 		TAny* apComponentParameterStructure) const = 0;

    87 

    88 	/**

    89 	   Port Manager's version of the SetParameter OpenMAX IL component

    90 	   API

    91 

    92 	   @param aParamIndex The index of the OpenMAX IL param structure.

    93 

    94 	   @param apComponentParameterStructure The pointer to the IL

    95 	   client-allocated param structure to be set into the port

    96 

    97 	   @param aPortIsDisabled This is an indication from the FSM to the Port

    98 	   Manager of whether the port should or should not be currently disabled

    99 	   for this OpenMAX IL API to succeed. If aPortIsDisabled is OMX_TRUE and

   100 	   the port is enabled this API is not allowed in the current state and the

   101 	   Port Manager must return OMX_ErrorIncorrectStateOperation. Default value

   102 	   is OMX_FALSE.

   103 

   104 	   @return OMX_ERRORTYPE

   105 	*/

   106 	virtual OMX_ERRORTYPE SetParameter(OMX_INDEXTYPE aParamIndex,

   107 							   const TAny* apComponentParameterStructure,

   108 							   OMX_BOOL aPortIsDisabled = OMX_FALSE) = 0;

   109 

   110 	/**

   111 	   Port Manager's version of the GetConfig OpenMAX IL component

   112 	   API

   113 

   114 	   @param aParamIndex The index of the OpenMAX IL config structure.

   115 

   116 	   @param apComponentParameterStructure The pointer to the config structure

   117 	   to be filled by the Port Manager (tipically delegated to the port)

   118 

   119 	   @return OMX_ERRORTYPE

   120 	*/

   121 	virtual OMX_ERRORTYPE GetConfig(OMX_INDEXTYPE aConfigIndex,

   122 							TAny* apComponentConfigStructure) const = 0;

   123 

   124 	/**

   125 	   Port Manager's version of the SetConfig OpenMAX IL component

   126 	   API

   127 

   128 	   @param aParamIndex The index of the OpenMAX IL config structure.

   129 

   130 	   @param apComponentParameterStructure The pointer to the config structure

   131 	   to be set into the port

   132 

   133 	   @return OMX_ERRORTYPE

   134 	*/

   135 	virtual OMX_ERRORTYPE SetConfig(OMX_INDEXTYPE aConfigIndex,

   136 							const TAny* apComponentConfigStructure) = 0;

   137 

   138 	/**

   139 	   Port Manager's version of the GetExtensionIndex OpenMAX IL component

   140 	   API

   141 

   142 	   @param aParameterName An OMX_STRING value that shall be less than 128

   143 	   characters long including the trailing null byte. The Port Manager will

   144 	   translate this string into a configuration index.

   145 

   146 	   @param apIndexType A pointer to the OMX_INDEXTYPE structure that is to

   147 	   receive the index value.

   148 

   149 	   @return OMX_ERRORTYPE

   150 	*/

   151 	virtual OMX_ERRORTYPE GetExtensionIndex(OMX_STRING aParameterName,

   152 									OMX_INDEXTYPE* apIndexType) const = 0;

   153 

   154 

   155 	/**

   156 	   Port Manager's version of the AllocateBuffer/UseBuffer OpenMAX IL component

   157 	   APIs

   158 

   159 	   @param appBufferHdr A pointer to a pointer of an OMX_BUFFERHEADERTYPE

   160 	   structure that receives the pointer to the buffer header.

   161 

   162 	   @param aPortIndex The index of the port that will use the specified

   163 	   buffer.

   164 

   165 	   @param apAppPrivate A pointer that refers to an implementation-specific

   166 	   memory area that is under responsibility of the supplier of the buffer

   167 

   168 	   @param aSizeBytes The buffer size in bytes

   169 

   170 	   @param apBuffer A pointer to the memory buffer area to be used

   171 

   172 	   @param [out] aPortPopulationCompleted This is an indication from the

   173 	   Port Manager to the FSM of whether the port population has completed or

   174 	   not.

   175 

   176 	   @param aPortIsDisabled This is an indication from the FSM to the Port

   177 	   Manager of whether the port should or should not be currently disabled

   178 	   for this OpenMAX IL API to succeed. If aPortIsDisabled is OMX_TRUE and

   179 	   the port is enabled this API is not allowed in the current state and the

   180 	   Port Manager must return OMX_ErrorIncorrectStateOperation. Default value

   181 	   is OMX_FALSE.

   182 

   183 	   @return OMX_ERRORTYPE

   184 	*/

   185 	virtual OMX_ERRORTYPE PopulateBuffer(OMX_BUFFERHEADERTYPE** appBufferHdr,

   186 								 OMX_U32 aPortIndex,

   187 								 OMX_PTR apAppPrivate,

   188 								 OMX_U32 aSizeBytes,

   189 								 OMX_U8* apBuffer,

   190 								 TBool& aPortPopulationCompleted,

   191 								 OMX_BOOL aPortIsDisabled = OMX_FALSE) = 0;

   192 

   193 	/**

   194 	   Port Manager's version of the FreeBuffer OpenMAX IL component

   195 	   API

   196 

   197 	   @param aPortIndex The index of the port that is using the specified

   198 	   buffer

   199 

   200 	   @param apBufferHeader A pointer to an OMX_BUFFERHEADERTYPE structure

   201 

   202 	   @param aPortDepopulationCompleted This is a g

   203 

   204 	   @param aPortIsDisabled This is an indication from the FSM to the Port

   205 	   Manager of whether the port should or should not be currently disabled

   206 	   for this OpenMAX IL API to succeed. If aPortIsDisabled is OMX_TRUE and

   207 	   the port is enabled this API is not allowed in the current state and the

   208 	   Port Manager must return OMX_ErrorIncorrectStateOperation. Default value

   209 	   is OMX_FALSE.

   210 

   211 	   @return OMX_ERRORTYPE

   212 	*/

   213 	virtual OMX_ERRORTYPE FreeBuffer(OMX_U32 aPortIndex,

   214 							 OMX_BUFFERHEADERTYPE* apBufferHeader,

   215 							 TBool& aPortDepopulationCompleted,

   216 							 OMX_BOOL aPortIsDisabled = OMX_FALSE) = 0;

   217 

   218 	/**

   219 	   Port Manager's version of the EmptyThisBuffer/FillThisBuffer OpenMAX IL

   220 	   component APIs. This is to be used by the FSM in any state except

   221 	   substates OMX_StateExecuting to OMX_StateIdle and OMX_StatePause to

   222 	   OMX_StateIdle, in which case BufferReturnIndication should be used.

   223 

   224 	   @param apBufferHeader A pointer to an OMX_BUFFERHEADERTYPE structure

   225 

   226 	   @param aDirection The direction of the port that received the

   227 	   EmptyThisBuffer/FillThisBuffer call

   228 

   229 	   @param aPortIsDisabled This is an indication from the FSM to the Port

   230 	   Manager of whether the port should or should not be currently disabled

   231 	   for this OpenMAX IL API to succeed. If aPortIsDisabled is OMX_TRUE and

   232 	   the port is enabled this API is not allowed in the current state and the

   233 	   Port Manager must return OMX_ErrorIncorrectStateOperation. Default value

   234 	   is OMX_FALSE.

   235 

   236 	   @return OMX_ERRORTYPE

   237 	*/

   238 	virtual OMX_ERRORTYPE BufferIndication(

   239 		OMX_BUFFERHEADERTYPE* apBufferHeader,

   240 		OMX_DIRTYPE aDirection,

   241 		OMX_BOOL aPortIsDisabled = OMX_FALSE) = 0;

   242 

   243 	/**

   244 	   Port Manager's version of the EmptyThisBuffer/FillThisBuffer OpenMAX IL

   245 	   component APIs. This is to be used by the FSM when the component is in

   246 	   substates OMX_StateExecuting to OMX_StateIdle and OMX_StatePause to

   247 	   OMX_StateIdle.

   248 

   249 	   @param apBufferHeader A pointer to an OMX_BUFFERHEADERTYPE structure

   250 

   251 	   @param aDirection The direction of the port that received the

   252 	   EmptyThisBuffer/FillThisBuffer call

   253 

   254 	   @param [out] aAllBuffersReturned ETrue if all buffers have already been

   255 	   returned to ports managed by the Port Manager. This is an indication to

   256 	   the FSM that the component is ready to be complete the transition to

   257 	   OMX_StateIdle.

   258 

   259 	   @return OMX_ERRORTYPE

   260 	*/

   261 	virtual OMX_ERRORTYPE BufferReturnIndication(

   262 		OMX_BUFFERHEADERTYPE* apBufferHeader,

   263 		OMX_DIRTYPE aDirection,

   264 		TBool& aAllBuffersReturned) = 0;

   265 

   266 	/**

   267 	   Port Manager's version of the ComponentTunnelRequest OpenMAX IL

   268 	   component API. This is to be used by the FSM when the component is in

   269 	   substates OMX_StateExecuting to OMX_StateIdle and OMX_StatePause to

   270 	   OMX_StateIdle.

   271 

   272 	   @param aPortIndex The index of the local port that is going to be tunnelled

   273 

   274 	   @param aTunneledComp The handle of the other component that participates

   275 	   in the tunnel. When this parameter is NULL, the port specified in aPortIndex

   276 	   should be configured for non-tunneled communication with the IL client.

   277 

   278 	   @param aTunneledPort The index of the remote port to be tunnelled with

   279 

   280 	   @param apTunnelSetup The structure that contains data for the tunneling

   281 	   negotiation between components.

   282 

   283 	   @param aPortIsDisabled This is an indication from the FSM to the Port

   284 	   Manager of whether the port should or should not be currently disabled

   285 	   for this OpenMAX IL API to succeed. If aPortIsDisabled is OMX_TRUE and

   286 	   the port is enabled this API is not allowed in the current state and the

   287 	   Port Manager must return OMX_ErrorIncorrectStateOperation. Default value

   288 	   is OMX_FALSE.

   289 

   290 	   @return OMX_ERRORTYPE

   291 	*/

   292 	virtual OMX_ERRORTYPE TunnelRequest(OMX_U32 aPortIndex,

   293 										OMX_HANDLETYPE aTunneledComp,

   294 										OMX_U32 aTunneledPort,

   295 										OMX_TUNNELSETUPTYPE* apTunnelSetup,

   296 										OMX_BOOL aPortIsDisabled = OMX_FALSE) = 0;

   297 

   298 

   299 /**

   300    Other Port Manager's interface, with no direct mapping to OpenMAX IL

   301    APIs. These are also for interal use in the component framework and should

   302    not be exported by Port Manager implementations.

   303 

   304    */

   305 

   306 	/**

   307 	   This is and indication from the FSM to the Port Manager that the

   308 	   component is transitioning from OMX_StateLoaded to OMX_StateIdle and

   309 	   that the Port Manager shall initiate the allocation of buffers in

   310 	   tunnelled supplier ports.

   311 

   312 	   @param [out] aComponentPopulationCompleted This is an indication from

   313 	   the Port Manager to the FSM of whether the population has completed in

   314 	   all ports, suppliers and non-suppliers.

   315 

   316 	   @param aPortIndex The index of the port to start populating. OMX_ALL by default.

   317 

   318 	   @return OMX_ERRORTYPE

   319 	*/

   320 	virtual OMX_ERRORTYPE TunnellingBufferAllocation(

   321 		TBool& aComponentPopulationCompleted,

   322 		TUint32 aPortIndex = OMX_ALL) = 0;

   323 

   324 	/**

   325 	   This is and indication from the FSM to the Port Manager that the

   326 	   component is transitioning to from OMX_StateExecuting or OMX_StatePause

   327 	   to OMX_StateIdle and that the Port Manager shall initiate the de-allocation

   328 	   of buffers in tunnelled supplier ports.

   329 

   330 	   @param [out] aComponentDePopulationCompleted This is an indication from

   331 	   the Port Manager to the FSM of whether the de-population has completed in

   332 	   all ports, suppliers and non-suppliers.

   333 

   334 	   @return OMX_ERRORTYPE

   335 	*/

   336 	virtual OMX_ERRORTYPE TunnellingBufferDeallocation(

   337 		TBool& aComponentDePopulationCompleted) = 0;

   338 

   339 	/**

   340 	   This is and indication from the FSM to the Port Manager that the

   341 	   component is transitioning to from OMX_StateIdle to OMX_StatePause or

   342 	   OMX_StateExecuting and that the Port Manager shall initiate the data

   343 	   flow in the tunnel (supplier input ports buffers are sent to the Callback Manager

   344 	   and supplier ouput ports buffers to the Processing Function)

   345 

   346 	   @param aPortIndex The index of the port that this function applies

   347 	   to. OMX_ALL if applies to all tunnelled supplier ports in the component.

   348 

   349 	   @param aSuppliersAndNonSuppliers This overrides the default behaviour of

   350 	   this function, i.e., initiating the data flow for the supplier

   351 	   ports. This is an indication to the Port Manager that non-supplier ports

   352 	   should be included too.

   353 

   354 	   @return OMX_ERRORTYPE

   355 	*/

   356 	virtual OMX_ERRORTYPE InitiateTunnellingDataFlow(

   357 		OMX_U32 aPortIndex = OMX_ALL,

   358 		OMX_BOOL aSuppliersAndNonSuppliers = OMX_FALSE) = 0;

   359 

   360 

   361 	/**

   362 	   This is and indication from the FSM to the Port Manager that the

   363 	   component has received a command to flush buffers.

   364 

   365 	   @param aPortIndex The index of the port that this function applies

   366 	   to. OMX_ALL if applies to all tunnelled supplier ports in the component.

   367 

   368 	   @param aEjectBuffers This is an indication to the Port Manager of

   369 	   whether owned buffers should be circulated or not as a consequence of

   370 	   flushing. The default is ETrue (buffers are ejected, ie sent to the

   371 	   Processing Function or the Callback Manager as needed). The FSM may

   372 	   override this default behaviour by using EFalse, e.g. if a flush command

   373 	   is received when the component is already in OMX_StateIdle state.

   374 

   375 	   @return OMX_ERRORTYPE

   376 	*/

   377 	virtual OMX_ERRORTYPE BufferFlushIndicationFlushCommand(

   378 		TUint32 aPortIndex, TBool aEjectBuffers = ETrue) = 0;

   379 

   380 	/**

   381 	   This is and indication from the FSM to the Port Manager that the

   382 	   component needs to flush buffers as a consequence of a transition to

   383 	   OMX_StateIdle from OMX_StateExecuting or OMX_StatePause.

   384 

   385 	   @param [out] aAllBuffersReturnedToSuppliers This is an indication from

   386 	   the Port Manager to the FSM that all buffers have been sent/received

   387 	   to/from suppliers/non-suppliers and that the component is ready to

   388 	   complete the transition to OMX_StateIdle.

   389 

   390 	   @return OMX_ERRORTYPE

   391 	*/

   392 	virtual OMX_ERRORTYPE BufferFlushIndicationPauseOrExeToIdleCommand(

   393 		TBool& aAllBuffersReturnedToSuppliers) = 0;

   394 

   395 	/**

   396 	   This is and indication from the FSM to the Port Manager that it needs to

   397 	   enable some port.

   398 

   399 	   @param aPortIndex The index of the port to be enabled. OMX_ALL if all ports.

   400 

   401 	   @param aIndicationIsFinal When this is ETrue, this is an indication from

   402 	   the FSM to the Port Manager that the current state of the component does

   403 	   not require the allocation of buffers (e.g. OMX_StateLoaded) and the

   404 	   port should complete the transition to enabled and forward the command

   405 	   complete event to the IL Client.

   406 

   407 	   @return OMX_ERRORTYPE

   408 	*/

   409 	virtual OMX_ERRORTYPE PortEnableIndication(

   410 		TUint32 aPortIndex,

   411 		TBool aIndicationIsFinal) = 0;

   412 

   413 	/**

   414 	   This is and indication from the FSM to the Port Manager that it needs to

   415 	   disable some port.

   416 

   417 	   @param aPortIndex The index of the port to be disabled. OMX_ALL if all ports.

   418 

   419 	   @return OMX_ERRORTYPE

   420 	*/

   421 	virtual OMX_ERRORTYPE PortDisableIndication(

   422 		TUint32 aPortIndex) = 0;

   423 

   424 	/**

   425 	   This is and indication from the FSM to the Port Manager that there is a

   426 	   buffer mark command to be applied to some port.

   427 

   428 	   @param aPortIndex The index of the port that receives the buffer mark command.

   429 

   430 	   @param ipMarkData The pointer to the buffer mark data

   431 

   432 	   @return OMX_ERRORTYPE

   433 	*/

   434 	virtual OMX_ERRORTYPE BufferMarkIndication(OMX_U32 aPortIndex,

   435 									   OMX_PTR ipMarkData) = 0;

   436 

   437 	/**

   438 	   This is an indication to the Port Manager that there is a request to

   439 	   change the role of the component and that the component's ports need to

   440 	   be adjusted to it.

   441 

   442 	   @param aComponentRoleIndex This is the index from the internal list of

   443 	   roles supported by the component

   444 

   445 	   @return OMX_ERRORTYPE

   446 	*/

   447 	virtual OMX_ERRORTYPE ComponentRoleIndication(

   448 		TUint aComponentRoleIndex) = 0;

   449 

   450 	/**

   451 	   This is an indication to the Port Manager that there is a port that

   452 	   needs to be reconfigured.

   453 

   454 	   @param aPortIndex The index of the port to be reconfigured.

   455 

   456 	   @param aPortSettingsIndex This is an index of the port structure to be

   457 	   reconfigured

   458 

   459 	   @param aPortSettings This is a descriptor that contains the information

   460 	   to be passed to the port that is to be reconfigured

   461 

   462 	   @param [out] aEventForILClient This is the event returned by the port

   463 	   after reconfiguration so the caller can forward that to the IL Client.

   464 

   465 	   @return OMX_ERRORTYPE

   466 	*/

   467 	virtual OMX_ERRORTYPE PortSettingsChangeIndication(

   468 		OMX_U32 aPortIndex,

   469 		TUint aPortSettingsIndex,

   470 		const TDesC8& aPortSettings,

   471 		OMX_EVENTTYPE& aEventForILClient) = 0;

   472 

   473 	/**

   474 	   Returns ETrue is all ports are currently populated

   475 	*/

   476 	virtual TBool AllPortsPopulated() const = 0;

   477 

   478 	/**

   479 	   Returns ETrue is all ports are currently depopulated

   480 	*/

   481 	virtual TBool AllPortsDePopulated() const = 0;

   482 

   483 	/**

   484 	   Returns ETrue is all buffer headers are currently with the Port Manager

   485 	*/

   486 	virtual TBool AllBuffersAtHome() const = 0;

   487 

   488 

   489 private:

   490 

   491 	/**

   492 	   Virtual constructor. This is mostly for reference. Port Managers should

   493 	   follow the below contruction interface.

   494 

   495 	   @param   aProcessingFunction The component's processing function

   496 

   497 	   @param   aCallbacks The component's callback manager

   498 

   499 	   @param   aOmxVersion The IL Spec version in use

   500 

   501 	   @param   aNumberOfAudioPorts Number of audio ports in the component

   502 

   503 	   @param   aStartAudioPortNumber The start index for audio ports

   504 

   505 	   @param   aNumberOfImagePorts Number of image ports in the component

   506 

   507 	   @param   aStartImagePortNumber The start index for image ports

   508 

   509 	   @param   aNumberOfVideoPorts Number of video ports in the component

   510 

   511 	   @param   aStartVideoPortNumber The start index for video ports

   512 

   513 	   @param   aNumberOfOtherPorts Number of other ports in the component

   514 

   515 	   @param   aStartOtherPortNumber The start index for other ports

   516 

   517 	   @param aImmediateReturnTimeBuffer This only applies to components with a

   518 	   clock client port. Indicates whether the Port Manager must forward an

   519 	   arriving clock buffer to the Callback Manager (ETrue) or to the

   520 	   Processing Function (EFalse) . If the clock buffer is to be forwarded to

   521 	   the Processing Function, this will happen using the BufferIndication

   522 	   function of the component's PF. Otherwise, PF's MediaTimeIndication is

   523 	   used instead.

   524 	*/

   525 	virtual void ConstructL(COmxILProcessingFunction& aProcessingFunction,

   526 							MOmxILCallbackManagerIf& aCallbacks,

   527 							const OMX_VERSIONTYPE& aOmxVersion,

   528 							OMX_U32 aNumberOfAudioPorts,

   529 							OMX_U32 aStartAudioPortNumber,

   530 							OMX_U32 aNumberOfImagePorts,

   531 							OMX_U32 aStartImagePortNumber,

   532 							OMX_U32 aNumberOfVideoPorts,

   533 							OMX_U32 aStartVideoPortNumber,

   534 							OMX_U32 aNumberOfOtherPorts,

   535 							OMX_U32 aStartOtherPortNumber,

   536 							OMX_BOOL aImmediateReturnTimeBuffer = OMX_TRUE) = 0;

   537 

   538 	};

   539 

   540 #include "omxilportmanagerif.inl"

   541 

   542 #endif // OMXILPORTMANAGERIF_H