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