// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
//

/**
 @file
 @internalTechnology
 @prototype
*/

#ifndef MILCOMPONENTIF_H
#define MILCOMPONENTIF_H

#include <e32base.h>
#include "ilifbase.h"
#include "tilstruct.h"

class MILIfObserver;
class MILComponentPortIf;

/**
IL Component interface class
*/
class MILComponentIf
	{
public:

	/**
	Synchronous method which creates the physical IL Component.
	
	@param  aComponentName
			The string identifying the name of the component.
	@param  aComponentObserver
			The class to receive asynchronous component events.
	@leave 	System wide error.
	*/
	virtual void CreateComponentL(const TDesC8& aComponentName, MILIfObserver& aComponentObserver) = 0;

	/**
	Synchronous method which creates the physical IL Component.
	
	@param  aComponentUID
			The UIF identifying a particular component implementation.
	@param  aComponentObserver
			The class to receive asynchronous component events.
	@leave 	System wide error.
	*/
	virtual void CreateComponentL(const TUid& aComponentUID, MILIfObserver& aComponentObserver) = 0;

	/**
	Called by the IL client to release the component associated to this interface
	*/
	virtual void ReleaseComponent() = 0;
	
	/**
	Synchronous method which returns the input ports a component holds. 
	The array is cleared before appending ports.
	
	@param  aComponentPorts
			The array to which the input ports will be appended.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt GetComponentInputPorts(RPointerArray<MILComponentPortIf>& aComponentPorts) const = 0;

	/**
	Synchronous method which returns the output ports a component holds.
	The array is cleared before appending ports.
	
	@param  aComponentPorts
			The array to which the output ports will be appended.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt GetComponentOutputPorts(RPointerArray<MILComponentPortIf>& aComponentPorts) const = 0;

	/**
	Synchronous method which sets the configuration for a Component.
	Note that in the omx implementation of this interface this function will be used for both SetParameter()
	and SetConfig()

	@param  aConfig
			The reference to the structure that contains the configuration data.
	@param  aComponentPort
			The component's port to be configured when needed, otherwise NULL.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.	
	@see TILStruct
	*/
	virtual TInt SetConfig(const TILStruct& aConfig, const MILComponentPortIf* aComponentPort = NULL) = 0;
	
	/**
	Synchronous method which gets a configuration structure from a component.
	Note that in the omx implementation of this interface this function will be used for both GetParameter()
	and GetConfig()
	
	@param  aConfig
			The reference to the structure that is to contain the configuration information.
	@param  aComponentPort
			The component's port to be queried when needed, otherwise NULL.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.	
	@see TILStruct
	*/
	virtual TInt GetConfig(TILStruct& aConfig, const MILComponentPortIf* aComponentPort = NULL) const = 0;	
	
	/**
	Asynchronous method which instructs the Component to start the initialization. 
	An event is sent to the component's observer on completion.
	
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	@see MILIfObserver::MsgFromILComponent()
	*/
	virtual TInt Initialize() = 0;

	/**
	Asynchronous method which instructs the Component to start the execution. 
	An event is sent to the component's observer on completion.
	
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	@see MILIfObserver::MsgFromILComponent()
	*/
	virtual TInt Execute() = 0; 

	/**
	Asynchronous method which pauses the current on-going task.
	An event is sent to the component's observer on completion.
	
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	@see MILIfObserver::MsgFromILComponent()
	*/
	virtual TInt Pause() = 0;

	/**
	Asynchronous method which stops the current on-going task. 
	An event is sent to the component's observer on completion.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	@see MILIfObserver::MsgFromILComponent()
	*/
	virtual TInt Stop() = 0;

	/**
	Asynchronous method which moves the component back to its uninitialized state. 
	An event is sent to the component's observer on completion.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	@see MILIfObserver::MsgFromILComponent()
	*/
	virtual TInt UnInitialize() = 0;

	/**
	Synchronous method which returns the current state of the Component.
	
	@param  aState
 			The current state of the Component.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt GetState(TILComponentState& aState) const = 0;

	/**
	Synchronous method which sends a command to the component.
	
	@param  aCommand
			The reference to the structure that is to contain the command to be executed by the component.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	@see TILCommand
	*/
	virtual TInt SendCommand(const TILCommand& aCommand) = 0;

	/**	
	Asynchronous function used to flush all component ports. 
	An event is sent to the component's observer on completion.
	
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt FlushAllPorts() = 0;

	/**	
	Called by the IL client to query the component about the roles it supports. 
	A component role  is a string identifying the behaviour of the component.
	
	@param  aComponentRole
			The pointer to the string returned identifying the role of the component.
	@param  aIndex
			The index of the component's role being queried.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt ComponentRoleEnum(TPtr8& aComponentRole, TUint32 aIndex) const = 0;
 

	/**	
	Called by the IL client to query the component's version.
	
	@param  aVersion
			The reference to the structure that is to contain the version of the component
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	@see TILComponentVersion
	*/
	virtual TInt GetComponentVersion(TILComponentVersion& aVersion) const = 0;

	/**
	Synchronous method which uses a standardized OpenMAX or vendor-specific extension string 
	to set a particular component configuration.
	Note that in the OMX implementation of this interface this function will be used for both 
	SetParameter() and SetConfig().
	
	@param  aParameterName
			The string that identifies the data container.
	@param  aConfig
			The reference to the structure that allows access to the data container used for this 
			particular component configuration
	@param  aComponentPort
			The component's port to which the config command is targeted to.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.	
	@see TILStruct
	*/
	virtual TInt SetExtConfig(const TDesC8& aParameterName, const TILStruct& aConfig, const MILComponentPortIf* aComponentPort = NULL) = 0;
	
	/**
	Synchronous method which uses a standardized OpenMAX or vendor-specific extension string 
	to get a particular component configuration.
	
	@param  aParameterName
			The string that identifies the data container.
	@param  aConfig
			The reference to the structure to access the component's configuration data.
	@param  aComponentPort
			The component's port to which the config command is targeted to.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.	
	@see TILStruct
	*/
	virtual TInt GetExtConfig(const TDesC8& aParameterName, TILStruct& aConfig, const MILComponentPortIf* aComponentPort = NULL) const = 0;
	
	
	/**
	Synchronous method to set a particular instance of this interface to the specific role passed as a parameter. 
	A single implementation of this API may support various component roles. It is necessary for the 
	implementation to know what type of component is configuring so that the appropriate translation of 
	configuration parameters can be chosen.
	The role UIDs may be defined by the client application and can be mapped be the implementation of this API
	to roles the components under this layer understand.

	@param  aFormat
			The UID identifying the role to be played by the implementation of this API.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.	
	*/
	virtual TInt SetComponentIfRole(const TUid& aComponentRole) = 0;

	/**
	Synchronous method to set a particular instance of this interface to the specific role passed as a parameter. 
	A single implementation of this API may support various component roles. It is necessary for the 
	implementation to know what type of component is configuring so that the appropriate translation of 
	configuration parameters can be chosen.
	Usually the component role names are defined by a known standard body. For instance role names are defined
	for OpenMAX IL Standard Components by Khronos Group.
	
	@param  aComponentRole
			The string identifying the role to be played by the implementation of this API.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.	
	*/
	virtual TInt SetComponentIfRole(const TDesC8& aComponentRole) = 0;

	/**
	Synchronous method to query about the particular role the interface is set to.
	A single implementation of this API can support various roles, however the role of the interface
	is that of the physical component instantiated under this interface.
	The role of the interface is set by the client after the component creation by calling SetComponentIfRole.
	The role UIDs may be defined by the client application and can be mapped be the implementation of this API
	to roles the components under this layer understand.
	
	@param  aComponentRole
			The UID identifying this interface's role which is to be passed back to the caller.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.	
	*/
	virtual TInt GetComponentIfRole(TUid& aComponentRole) const = 0;

	/**
	Synchronous method to query about the particular role the interface is set to.
	A single implementation of this API can support various roles, however the role of the interface
	is that of the [hysical component instantiated under this interface.
	The role of the interface is set by the client after the component creation by calling SetComponentIfRole.
	Usually the component role names are defined by a known standard body. For instance role names are defined
	for OpenMAX IL Standard Components by Khronos Group.

	@param  aComponentRole
			The string identifying this interface's role which is to be passed back to the caller.
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.	
	*/
	virtual TInt GetComponentIfRole(TDes8& aComponentRole) const = 0;

	/**
	Synchronous method used to identify a particular interface implementation. 
	It takes as a parameter the UID identifying the type of the interface requested and 
	it returns a pointer to the specified interface or NULL if it does not exist. 
	Must be cast to correct type by the user

	@param  aInterfaceId
			The UID associated with the interface requested.
	@return A pointer to the specified interface or NULL if it has not be implemented.	
	*/
	virtual TAny* CustomInterface(TUid aInterfaceId) = 0;

	};

	
#endif // MILCOMPONENTIF_H