sl@0: /*
sl@0: * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description:
sl@0: *
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: #ifndef __MMF_HW_DEVICE_H__
sl@0: #define __MMF_HW_DEVICE_H__
sl@0: 
sl@0: #include <e32base.h>
sl@0: #include <ecom/implementationinformation.h>
sl@0: #include <mmf/common/mmfutilities.h> //TFourCC
sl@0: #include <mmf/server/mmfhwdevicecmds.h>
sl@0: #include <mmf/server/taskconfig.h>
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: The connection type defines what the stream will connect to,
sl@0: either gpp, dsp node, or dsp device.
sl@0: */
sl@0: typedef enum TConnectionType_tag
sl@0: 	{
sl@0: 	/** Gpp
sl@0: 	*/
sl@0:     EConnectionGpp,
sl@0:     /** dsp node
sl@0: 	*/
sl@0:     EConnectionTask,
sl@0:     /** dsp device
sl@0: 	*/
sl@0:     EConnectionDevice
sl@0: 	} TConnectionType ;
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Connection Type
sl@0: */
sl@0: typedef struct TStreamConnection_tag
sl@0: 	{
sl@0: 	/** connection id
sl@0: 	*/
sl@0:     TInt               iId ;
sl@0:     /** connection type
sl@0:     */
sl@0:     TConnectionType    iType ;
sl@0: 	} TStreamConnection;
sl@0: 
sl@0: const TUint KMaxDeviceNameLength = 128;
sl@0: 
sl@0: enum TSamplingFreq { ESampFreq8k, ESampFreq11025k, ESampFreq16k, ESampFreq2205k, ESampFreq32k, ESampFreq441k, ESampFreq48k, ESampFreq12k, ESampFreq24k, ESampFreq64k};
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Type class for stream connection parameters.
sl@0: This structure defines the connection parameters that are required to
sl@0: be filled in by the HwDevice observer.  The connection type defines
sl@0: what the stream will connect to, either gpp, dsp node, or dsp device.
sl@0: */
sl@0: class TConnection
sl@0: 	{
sl@0: 	public:
sl@0: 	/** Connection type.
sl@0: 	*/
sl@0:     TStreamConnection           iConnection;
sl@0: 	/** Name of the device if needed.
sl@0: 	*/
sl@0:     TBuf8<KMaxDeviceNameLength> iDeviceName;
sl@0: 	};
sl@0: 
sl@0: // Forward reference
sl@0: class MMMFHwDeviceObserver;
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: Type class for Hardware initialization parameters.
sl@0: The implementation specific initialization attributes are passed in this
sl@0: structure. Elements common to all HwDevices are defined here. These are
sl@0: the pointer to the observer and stream connection identification for the
sl@0: HwDevice.
sl@0: 
sl@0: These stream connections are defined as follows:
sl@0: - SrcStream is the source data stream to the HwDevice for a decoder/player.
sl@0: - OutStream is the counterpart stream of data out of the HwDevice of
sl@0: processed source data.
sl@0: - InStream is the input stream of data to the HwDevice for an
sl@0: encoder/recorder. 
sl@0: - DestStream is the destination data stream of
sl@0: this InStream after it has been processed.
sl@0: 
sl@0: The last element is a pointer to a buffer of the rest of the initialization
sl@0: data for the HwDevice. This data will vary for different HwDevices.
sl@0: However, the first element is always the number of internal connections (TUint8)
sl@0: required by the HwDevice. Following this, is an element (TUint8) for each of
sl@0: the required connection ID's. The elements following this are only known by
sl@0: the HwDevice.
sl@0: */
sl@0: class THwDeviceInitParams
sl@0: 	{
sl@0: 	public:
sl@0: 		THwDeviceInitParams() : iHwDeviceInitArgsPtr(0,0){};
sl@0: 		/** Pointer to an observer.
sl@0: 		*/
sl@0: 		MMMFHwDeviceObserver* iHwDeviceObserver;
sl@0: 		/** Source stream attributes.
sl@0: 		*/
sl@0: 		TConnection           iSrcStream;
sl@0: 		/** Destination stream attributes.
sl@0: 		*/
sl@0: 		TConnection           iDestStream;
sl@0: 		/** Input stream attributes.
sl@0: 		*/
sl@0: 		TConnection           iInStream;
sl@0: 		/** Output stream attributes.
sl@0: 		*/
sl@0: 		TConnection           iOutStream;
sl@0: 		/** Pointer to a buffer.
sl@0: 		*/
sl@0: 		TPtr8                 iHwDeviceInitArgsPtr;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: The observer class interface for a hardware device listener class.
sl@0: 
sl@0: MMMFHwDeviceObserver provides a generic interface which should be implemented
sl@0: by the classes that are interested in receiving events from the CMMFHwDevice
sl@0: implementation class.
sl@0: */
sl@0: class MMMFHwDeviceObserver
sl@0: 	{
sl@0: public:
sl@0: 
sl@0: 	/**
sl@0: 	Handles CMMFHwDevice object’s data request event.
sl@0: 
sl@0: 	This function is called by the CMMFHwDevice implementation class when it
sl@0: 	needs data for decoding.
sl@0: 
sl@0: 	@param  aHwDataBuffer
sl@0: 	        The buffer to fill the data.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt FillThisHwBuffer(CMMFBuffer& aHwDataBuffer) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Handles CMMFHwDevice object’s data request event.
sl@0: 	
sl@0: 	This function is called by the CMMFHwDevice implementation class when it
sl@0: 	fills encoded data into a buffer.
sl@0: 
sl@0: 	@param  aHwDataBuffer
sl@0: 	        The buffer with encoded data.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt EmptyThisHwBuffer(CMMFBuffer& aHwDataBuffer) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Handles the CMMFHwDevice object’s message event.
sl@0: 
sl@0: 	This function is called by the CMMFHwDevice implementation class when a
sl@0: 	message is generated and passed back to the observer.
sl@0: 
sl@0: 	@param  aMessageType
sl@0: 	        The type of message. Defines the contents of aMsg.
sl@0: 	@param  aMsg
sl@0: 	        The message packed in a descriptor.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt MsgFromHwDevice(TUid aMessageType, const TDesC8& aMsg)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Called by a CMMFHwDevice derived class when it stops a decoding/encoding task.
sl@0: 	*/
sl@0: 	virtual void Stopped() = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Called by a CMMFHwDevice derived class when it stops a decoding/encoding task.
sl@0: 	*/
sl@0: 	virtual void Error(TInt aError=KErrNone) = 0;
sl@0: 	};
sl@0: 
sl@0: /*
sl@0:  *
sl@0:  *	KMmfUidPluginInterfaceHwDevice
sl@0:  *
sl@0:  *	This UID is the INTERFACE_UID for CMMFHwDevice.  It is used to search for hardware device plugins in plugin DLLs.
sl@0:  *	All hardware device plugin DLLs must include interface_uid = KMmfUidPluginInterfaceHwDevice in their .rss files.
sl@0:  *
sl@0:  */
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @released
sl@0: 
sl@0: ECom plugin class for a hardware device that decodes (plays) source data in a certain
sl@0: FourCC coding type to another FourCC coding type or encodes (records) data from a certain
sl@0: FourCC coding type to a another FourCC coding type.
sl@0: 
sl@0: The hardware device can be instantiated in 3 different ways:
sl@0: 
sl@0: 1.	NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType)
sl@0: 
sl@0: This instantiate a hardware device that can encode or decode the aSrcDatatype to a aDstDataType.
sl@0: 
sl@0: 2.	NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier)
sl@0: 
sl@0: This is similar to the above but is used where there may be multiple hardware devices that
sl@0: perform the same conversion. Third party developers may use their own
sl@0: hardware device implementations and can ensure the controller uses their implementation by setting
sl@0: the preferred supplier to themselves.
sl@0: 
sl@0: 3.	NewL(TUid aUid)
sl@0: 
sl@0: This is used to explicitly instantiate a hardware device where the UID is known.
sl@0: 
sl@0: 4.	NewL(TFileName aFileName)
sl@0: 
sl@0: This is used to create an instance of a HwDevice implementation by loading the library
sl@0: 
sl@0: CMMFHwDevice provides a generic interface that every Hardware Device that decodes and/or encodes has to implement.
sl@0: Based on parameters specified in Start, the device implementation will start decoding or encoding.
sl@0: The source and destination of the decoding/encoding operations should be set up before starting the task by sending
sl@0: THwDeviceInitParams to the Init() function.
sl@0: */
sl@0: class CMMFHwDevice  : public CBase
sl@0: 	{
sl@0: public:
sl@0: 	static CMMFHwDevice* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType);
sl@0: 	static CMMFHwDevice* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier);
sl@0: 	inline static CMMFHwDevice* NewL(TUid aUid);
sl@0: 	static CMMFHwDevice* NewL(TFileName aFileName);
sl@0: 
sl@0: 	/**
sl@0: 	Starts Encoding or Decoding task(s) based on the parameter specified.
sl@0: 
sl@0: 	@param  aFuncCmd
sl@0: 	        The device function specifying the requested service i.e. decode or encode.
sl@0: 	@param  aFlowCmd
sl@0: 	        The device flow directions for the requested service.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt Start(TDeviceFunc aFuncCmd, TDeviceFlow aFlowCmd) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Stops the current on-going task.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt Stop() = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Temporarily suspends the current task of decoding or encoding.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt Pause() = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Initializes the hardware device tasks.
sl@0: 
sl@0: 	@param  aDevInfo
sl@0: 	        The device initialization parameters.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt Init(THwDeviceInitParams& aDevInfo) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Retrieves a custom interface to the device.
sl@0: 
sl@0: 	@param  aInterfaceId
sl@0: 	        The interface UID, defined with the custom interface.
sl@0: 
sl@0: 	@return A pointer to the interface implementation, or NULL if the device does not
sl@0: 	        implement the interface requested. The return value must be cast to the
sl@0: 	        correct type by the user.
sl@0: 	*/
sl@0: 	virtual TAny* CustomInterface(TUid aInterfaceId) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Call this function to notify hardware device implementation that
sl@0: 	data is available in aFillBufferPtr for decoding.
sl@0: 
sl@0: 	@param  aFillBufferPtr
sl@0: 	        The data buffer filled by the observer.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt ThisHwBufferFilled(CMMFBuffer& aFillBufferPtr) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Call this function to notify hardware device implementation that
sl@0: 	data in aEmptyBufferPtr from encoding is processed.
sl@0: 
sl@0: 	@param  aEmptyBufferPtr
sl@0: 	        The data buffer processed by the observer.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt ThisHwBufferEmptied(CMMFBuffer& aEmptyBufferPtr) = 0;
sl@0: 
sl@0: 	/**
sl@0:     Used to configure the sample rate and stereo mode of a CMMFHwDevice plugin.
sl@0: 
sl@0: 	The configuration of HwDevices is device specific and is not used in any of the reference
sl@0: 	devices that return KErrNotSupported.
sl@0: 
sl@0: 	@param  aConfig
sl@0: 	        The device configuration.
sl@0: 	*/
sl@0: 	virtual TInt SetConfig(TTaskConfig& aConfig) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Call this function to stop and then delete a codec. This is used to allow resources to be freed 
sl@0: 	when using a DSP or similar hardware.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt StopAndDeleteCodec() = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Call this function to delete a codec. 
sl@0: 
sl@0: 	This is used to allow resources to be freed when using a DSP or similar hardware.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	virtual TInt DeleteCodec() = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Destructor.
sl@0: 
sl@0: 	The destructor is called by ECom framework allowing derived classes
sl@0: 	to clean up the implementation specific resources.
sl@0: 	*/
sl@0: 	inline virtual ~CMMFHwDevice();
sl@0: 
sl@0: private:
sl@0: 	static void SelectByPreference( RImplInfoPtrArray& aPlugInArray, const TDesC& aPreferredSupplier ) ;
sl@0: 
sl@0: protected:
sl@0: 	/**
sl@0: 	A pointer to the hardware device observer.
sl@0: 	*/
sl@0: 	MMMFHwDeviceObserver* iHwDeviceObserver;
sl@0: 
sl@0: //Attributes
sl@0: private:
sl@0: 	TUid iDtor_ID_Key;
sl@0: 	};
sl@0: 	
sl@0: #include <mmf/server/mmfhwdevice.inl>
sl@0: 
sl@0: #endif
sl@0: