/*
* Copyright (c) 2002-2004 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:
*
*/



#ifndef __MMF_HW_DEVICE_H__
#define __MMF_HW_DEVICE_H__

#include <e32base.h>
#include <ecom/implementationinformation.h>
#include <mmf/common/mmfutilities.h> //TFourCC
#include <mmf/server/mmfhwdevicecmds.h>
#include <mmf/server/taskconfig.h>

/**
@publishedPartner
@released

The connection type defines what the stream will connect to,
either gpp, dsp node, or dsp device.
*/
typedef enum TConnectionType_tag
	{
	/** Gpp
	*/
    EConnectionGpp,
    /** dsp node
	*/
    EConnectionTask,
    /** dsp device
	*/
    EConnectionDevice
	} TConnectionType ;

/**
@publishedPartner
@released

Connection Type
*/
typedef struct TStreamConnection_tag
	{
	/** connection id
	*/
    TInt               iId ;
    /** connection type
    */
    TConnectionType    iType ;
	} TStreamConnection;

const TUint KMaxDeviceNameLength = 128;

enum TSamplingFreq { ESampFreq8k, ESampFreq11025k, ESampFreq16k, ESampFreq2205k, ESampFreq32k, ESampFreq441k, ESampFreq48k, ESampFreq12k, ESampFreq24k, ESampFreq64k};

/**
@publishedPartner
@released

Type class for stream connection parameters.
This structure defines the connection parameters that are required to
be filled in by the HwDevice observer.  The connection type defines
what the stream will connect to, either gpp, dsp node, or dsp device.
*/
class TConnection
	{
	public:
	/** Connection type.
	*/
    TStreamConnection           iConnection;
	/** Name of the device if needed.
	*/
    TBuf8<KMaxDeviceNameLength> iDeviceName;
	};

// Forward reference
class MMMFHwDeviceObserver;

/**
@publishedPartner
@released

Type class for Hardware initialization parameters.
The implementation specific initialization attributes are passed in this
structure. Elements common to all HwDevices are defined here. These are
the pointer to the observer and stream connection identification for the
HwDevice.

These stream connections are defined as follows:
- SrcStream is the source data stream to the HwDevice for a decoder/player.
- OutStream is the counterpart stream of data out of the HwDevice of
processed source data.
- InStream is the input stream of data to the HwDevice for an
encoder/recorder. 
- DestStream is the destination data stream of
this InStream after it has been processed.

The last element is a pointer to a buffer of the rest of the initialization
data for the HwDevice. This data will vary for different HwDevices.
However, the first element is always the number of internal connections (TUint8)
required by the HwDevice. Following this, is an element (TUint8) for each of
the required connection ID's. The elements following this are only known by
the HwDevice.
*/
class THwDeviceInitParams
	{
	public:
		THwDeviceInitParams() : iHwDeviceInitArgsPtr(0,0){};
		/** Pointer to an observer.
		*/
		MMMFHwDeviceObserver* iHwDeviceObserver;
		/** Source stream attributes.
		*/
		TConnection           iSrcStream;
		/** Destination stream attributes.
		*/
		TConnection           iDestStream;
		/** Input stream attributes.
		*/
		TConnection           iInStream;
		/** Output stream attributes.
		*/
		TConnection           iOutStream;
		/** Pointer to a buffer.
		*/
		TPtr8                 iHwDeviceInitArgsPtr;
	};


/**
@publishedPartner
@released

The observer class interface for a hardware device listener class.

MMMFHwDeviceObserver provides a generic interface which should be implemented
by the classes that are interested in receiving events from the CMMFHwDevice
implementation class.
*/
class MMMFHwDeviceObserver
	{
public:

	/**
	Handles CMMFHwDevice object’s data request event.

	This function is called by the CMMFHwDevice implementation class when it
	needs data for decoding.

	@param  aHwDataBuffer
	        The buffer to fill the data.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt FillThisHwBuffer(CMMFBuffer& aHwDataBuffer) = 0;

	/**
	Handles CMMFHwDevice object’s data request event.
	
	This function is called by the CMMFHwDevice implementation class when it
	fills encoded data into a buffer.

	@param  aHwDataBuffer
	        The buffer with encoded data.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt EmptyThisHwBuffer(CMMFBuffer& aHwDataBuffer) = 0;

	/**
	Handles the CMMFHwDevice object’s message event.

	This function is called by the CMMFHwDevice implementation class when a
	message is generated and passed back to the observer.

	@param  aMessageType
	        The type of message. Defines the contents of aMsg.
	@param  aMsg
	        The message packed in a descriptor.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt MsgFromHwDevice(TUid aMessageType, const TDesC8& aMsg)=0;

	/**
	Called by a CMMFHwDevice derived class when it stops a decoding/encoding task.
	*/
	virtual void Stopped() = 0;

	/**
	Called by a CMMFHwDevice derived class when it stops a decoding/encoding task.
	*/
	virtual void Error(TInt aError=KErrNone) = 0;
	};

/*
 *
 *	KMmfUidPluginInterfaceHwDevice
 *
 *	This UID is the INTERFACE_UID for CMMFHwDevice.  It is used to search for hardware device plugins in plugin DLLs.
 *	All hardware device plugin DLLs must include interface_uid = KMmfUidPluginInterfaceHwDevice in their .rss files.
 *
 */

/**
@publishedPartner
@released

ECom plugin class for a hardware device that decodes (plays) source data in a certain
FourCC coding type to another FourCC coding type or encodes (records) data from a certain
FourCC coding type to a another FourCC coding type.

The hardware device can be instantiated in 3 different ways:

1.	NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType)

This instantiate a hardware device that can encode or decode the aSrcDatatype to a aDstDataType.

2.	NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier)

This is similar to the above but is used where there may be multiple hardware devices that
perform the same conversion. Third party developers may use their own
hardware device implementations and can ensure the controller uses their implementation by setting
the preferred supplier to themselves.

3.	NewL(TUid aUid)

This is used to explicitly instantiate a hardware device where the UID is known.

4.	NewL(TFileName aFileName)

This is used to create an instance of a HwDevice implementation by loading the library

CMMFHwDevice provides a generic interface that every Hardware Device that decodes and/or encodes has to implement.
Based on parameters specified in Start, the device implementation will start decoding or encoding.
The source and destination of the decoding/encoding operations should be set up before starting the task by sending
THwDeviceInitParams to the Init() function.
*/
class CMMFHwDevice  : public CBase
	{
public:
	static CMMFHwDevice* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType);
	static CMMFHwDevice* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier);
	inline static CMMFHwDevice* NewL(TUid aUid);
	static CMMFHwDevice* NewL(TFileName aFileName);

	/**
	Starts Encoding or Decoding task(s) based on the parameter specified.

	@param  aFuncCmd
	        The device function specifying the requested service i.e. decode or encode.
	@param  aFlowCmd
	        The device flow directions for the requested service.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt Start(TDeviceFunc aFuncCmd, TDeviceFlow aFlowCmd) = 0;

	/**
	Stops the current on-going task.

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

	/**
	Temporarily suspends the current task of decoding or encoding.

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

	/**
	Initializes the hardware device tasks.

	@param  aDevInfo
	        The device initialization parameters.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt Init(THwDeviceInitParams& aDevInfo) = 0;

	/**
	Retrieves a custom interface to the device.

	@param  aInterfaceId
	        The interface UID, defined with the custom interface.

	@return A pointer to the interface implementation, or NULL if the device does not
	        implement the interface requested. The return value must be cast to the
	        correct type by the user.
	*/
	virtual TAny* CustomInterface(TUid aInterfaceId) = 0;

	/**
	Call this function to notify hardware device implementation that
	data is available in aFillBufferPtr for decoding.

	@param  aFillBufferPtr
	        The data buffer filled by the observer.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt ThisHwBufferFilled(CMMFBuffer& aFillBufferPtr) = 0;

	/**
	Call this function to notify hardware device implementation that
	data in aEmptyBufferPtr from encoding is processed.

	@param  aEmptyBufferPtr
	        The data buffer processed by the observer.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.
	*/
	virtual TInt ThisHwBufferEmptied(CMMFBuffer& aEmptyBufferPtr) = 0;

	/**
    Used to configure the sample rate and stereo mode of a CMMFHwDevice plugin.

	The configuration of HwDevices is device specific and is not used in any of the reference
	devices that return KErrNotSupported.

	@param  aConfig
	        The device configuration.
	*/
	virtual TInt SetConfig(TTaskConfig& aConfig) = 0;

	/**
	Call this function to stop and then delete a codec. This is used to allow resources to be freed 
	when using a DSP or similar hardware.

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

	/**
	Call this function to delete a codec. 

	This is used to allow resources to be freed when using a DSP or similar hardware.

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

	/**
	Destructor.

	The destructor is called by ECom framework allowing derived classes
	to clean up the implementation specific resources.
	*/
	inline virtual ~CMMFHwDevice();

private:
	static void SelectByPreference( RImplInfoPtrArray& aPlugInArray, const TDesC& aPreferredSupplier ) ;

protected:
	/**
	A pointer to the hardware device observer.
	*/
	MMMFHwDeviceObserver* iHwDeviceObserver;

//Attributes
private:
	TUid iDtor_ID_Key;
	};
	
#include <mmf/server/mmfhwdevice.inl>

#endif