epoc32/include/mmf/server/mmfhwdevice.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 /*
     2 * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of "Eclipse Public License v1.0"
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description:
    15 *
    16 */
    17 
    18 
    19 
    20 #ifndef __MMF_HW_DEVICE_H__
    21 #define __MMF_HW_DEVICE_H__
    22 
    23 #include <e32base.h>
    24 #include <ecom/implementationinformation.h>
    25 #include <mmf/common/mmfutilities.h> //TFourCC
    26 #include <mmf/server/mmfhwdevicecmds.h>
    27 #include <mmf/server/taskconfig.h>
    28 
    29 /**
    30 @publishedPartner
    31 @released
    32 
    33 The connection type defines what the stream will connect to,
    34 either gpp, dsp node, or dsp device.
    35 */
    36 typedef enum TConnectionType_tag
    37 	{
    38 	/** Gpp
    39 	*/
    40     EConnectionGpp,
    41     /** dsp node
    42 	*/
    43     EConnectionTask,
    44     /** dsp device
    45 	*/
    46     EConnectionDevice
    47 	} TConnectionType ;
    48 
    49 /**
    50 @publishedPartner
    51 @released
    52 
    53 Connection Type
    54 */
    55 typedef struct TStreamConnection_tag
    56 	{
    57 	/** connection id
    58 	*/
    59     TInt               iId ;
    60     /** connection type
    61     */
    62     TConnectionType    iType ;
    63 	} TStreamConnection;
    64 
    65 const TUint KMaxDeviceNameLength = 128;
    66 
    67 enum TSamplingFreq { ESampFreq8k, ESampFreq11025k, ESampFreq16k, ESampFreq2205k, ESampFreq32k, ESampFreq441k, ESampFreq48k, ESampFreq12k, ESampFreq24k, ESampFreq64k};
    68 
    69 /**
    70 @publishedPartner
    71 @released
    72 
    73 Type class for stream connection parameters.
    74 This structure defines the connection parameters that are required to
    75 be filled in by the HwDevice observer.  The connection type defines
    76 what the stream will connect to, either gpp, dsp node, or dsp device.
    77 */
    78 class TConnection
    79 	{
    80 	public:
    81 	/** Connection type.
    82 	*/
    83     TStreamConnection           iConnection;
    84 	/** Name of the device if needed.
    85 	*/
    86     TBuf8<KMaxDeviceNameLength> iDeviceName;
    87 	};
    88 
    89 // Forward reference
    90 class MMMFHwDeviceObserver;
    91 
    92 /**
    93 @publishedPartner
    94 @released
    95 
    96 Type class for Hardware initialization parameters.
    97 The implementation specific initialization attributes are passed in this
    98 structure. Elements common to all HwDevices are defined here. These are
    99 the pointer to the observer and stream connection identification for the
   100 HwDevice.
   101 
   102 These stream connections are defined as follows:
   103 - SrcStream is the source data stream to the HwDevice for a decoder/player.
   104 - OutStream is the counterpart stream of data out of the HwDevice of
   105 processed source data.
   106 - InStream is the input stream of data to the HwDevice for an
   107 encoder/recorder. 
   108 - DestStream is the destination data stream of
   109 this InStream after it has been processed.
   110 
   111 The last element is a pointer to a buffer of the rest of the initialization
   112 data for the HwDevice. This data will vary for different HwDevices.
   113 However, the first element is always the number of internal connections (TUint8)
   114 required by the HwDevice. Following this, is an element (TUint8) for each of
   115 the required connection ID's. The elements following this are only known by
   116 the HwDevice.
   117 */
   118 class THwDeviceInitParams
   119 	{
   120 	public:
   121 		THwDeviceInitParams() : iHwDeviceInitArgsPtr(0,0){};
   122 		/** Pointer to an observer.
   123 		*/
   124 		MMMFHwDeviceObserver* iHwDeviceObserver;
   125 		/** Source stream attributes.
   126 		*/
   127 		TConnection           iSrcStream;
   128 		/** Destination stream attributes.
   129 		*/
   130 		TConnection           iDestStream;
   131 		/** Input stream attributes.
   132 		*/
   133 		TConnection           iInStream;
   134 		/** Output stream attributes.
   135 		*/
   136 		TConnection           iOutStream;
   137 		/** Pointer to a buffer.
   138 		*/
   139 		TPtr8                 iHwDeviceInitArgsPtr;
   140 	};
   141 
   142 
   143 /**
   144 @publishedPartner
   145 @released
   146 
   147 The observer class interface for a hardware device listener class.
   148 
   149 MMMFHwDeviceObserver provides a generic interface which should be implemented
   150 by the classes that are interested in receiving events from the CMMFHwDevice
   151 implementation class.
   152 */
   153 class MMMFHwDeviceObserver
   154 	{
   155 public:
   156 
   157 	/**
   158 	Handles CMMFHwDevice object’s data request event.
   159 
   160 	This function is called by the CMMFHwDevice implementation class when it
   161 	needs data for decoding.
   162 
   163 	@param  aHwDataBuffer
   164 	        The buffer to fill the data.
   165 
   166 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   167 	        another of the system-wide error codes.
   168 	*/
   169 	virtual TInt FillThisHwBuffer(CMMFBuffer& aHwDataBuffer) = 0;
   170 
   171 	/**
   172 	Handles CMMFHwDevice object’s data request event.
   173 	
   174 	This function is called by the CMMFHwDevice implementation class when it
   175 	fills encoded data into a buffer.
   176 
   177 	@param  aHwDataBuffer
   178 	        The buffer with encoded data.
   179 
   180 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   181 	        another of the system-wide error codes.
   182 	*/
   183 	virtual TInt EmptyThisHwBuffer(CMMFBuffer& aHwDataBuffer) = 0;
   184 
   185 	/**
   186 	Handles the CMMFHwDevice object’s message event.
   187 
   188 	This function is called by the CMMFHwDevice implementation class when a
   189 	message is generated and passed back to the observer.
   190 
   191 	@param  aMessageType
   192 	        The type of message. Defines the contents of aMsg.
   193 	@param  aMsg
   194 	        The message packed in a descriptor.
   195 
   196 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   197 	        another of the system-wide error codes.
   198 	*/
   199 	virtual TInt MsgFromHwDevice(TUid aMessageType, const TDesC8& aMsg)=0;
   200 
   201 	/**
   202 	Called by a CMMFHwDevice derived class when it stops a decoding/encoding task.
   203 	*/
   204 	virtual void Stopped() = 0;
   205 
   206 	/**
   207 	Called by a CMMFHwDevice derived class when it stops a decoding/encoding task.
   208 	*/
   209 	virtual void Error(TInt aError=KErrNone) = 0;
   210 	};
   211 
   212 /*
   213  *
   214  *	KMmfUidPluginInterfaceHwDevice
   215  *
   216  *	This UID is the INTERFACE_UID for CMMFHwDevice.  It is used to search for hardware device plugins in plugin DLLs.
   217  *	All hardware device plugin DLLs must include interface_uid = KMmfUidPluginInterfaceHwDevice in their .rss files.
   218  *
   219  */
   220 
   221 /**
   222 @publishedPartner
   223 @released
   224 
   225 ECom plugin class for a hardware device that decodes (plays) source data in a certain
   226 FourCC coding type to another FourCC coding type or encodes (records) data from a certain
   227 FourCC coding type to a another FourCC coding type.
   228 
   229 The hardware device can be instantiated in 3 different ways:
   230 
   231 1.	NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType)
   232 
   233 This instantiate a hardware device that can encode or decode the aSrcDatatype to a aDstDataType.
   234 
   235 2.	NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier)
   236 
   237 This is similar to the above but is used where there may be multiple hardware devices that
   238 perform the same conversion. Third party developers may use their own
   239 hardware device implementations and can ensure the controller uses their implementation by setting
   240 the preferred supplier to themselves.
   241 
   242 3.	NewL(TUid aUid)
   243 
   244 This is used to explicitly instantiate a hardware device where the UID is known.
   245 
   246 4.	NewL(TFileName aFileName)
   247 
   248 This is used to create an instance of a HwDevice implementation by loading the library
   249 
   250 CMMFHwDevice provides a generic interface that every Hardware Device that decodes and/or encodes has to implement.
   251 Based on parameters specified in Start, the device implementation will start decoding or encoding.
   252 The source and destination of the decoding/encoding operations should be set up before starting the task by sending
   253 THwDeviceInitParams to the Init() function.
   254 */
   255 class CMMFHwDevice  : public CBase
   256 	{
   257 public:
   258 	static CMMFHwDevice* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType);
   259 	static CMMFHwDevice* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier);
   260 	inline static CMMFHwDevice* NewL(TUid aUid);
   261 	static CMMFHwDevice* NewL(TFileName aFileName);
   262 
   263 	/**
   264 	Starts Encoding or Decoding task(s) based on the parameter specified.
   265 
   266 	@param  aFuncCmd
   267 	        The device function specifying the requested service i.e. decode or encode.
   268 	@param  aFlowCmd
   269 	        The device flow directions for the requested service.
   270 
   271 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   272 	        another of the system-wide error codes.
   273 	*/
   274 	virtual TInt Start(TDeviceFunc aFuncCmd, TDeviceFlow aFlowCmd) = 0;
   275 
   276 	/**
   277 	Stops the current on-going task.
   278 
   279 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   280 	        another of the system-wide error codes.
   281 	*/
   282 	virtual TInt Stop() = 0;
   283 
   284 	/**
   285 	Temporarily suspends the current task of decoding or encoding.
   286 
   287 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   288 	        another of the system-wide error codes.
   289 	*/
   290 	virtual TInt Pause() = 0;
   291 
   292 	/**
   293 	Initializes the hardware device tasks.
   294 
   295 	@param  aDevInfo
   296 	        The device initialization parameters.
   297 
   298 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   299 	        another of the system-wide error codes.
   300 	*/
   301 	virtual TInt Init(THwDeviceInitParams& aDevInfo) = 0;
   302 
   303 	/**
   304 	Retrieves a custom interface to the device.
   305 
   306 	@param  aInterfaceId
   307 	        The interface UID, defined with the custom interface.
   308 
   309 	@return A pointer to the interface implementation, or NULL if the device does not
   310 	        implement the interface requested. The return value must be cast to the
   311 	        correct type by the user.
   312 	*/
   313 	virtual TAny* CustomInterface(TUid aInterfaceId) = 0;
   314 
   315 	/**
   316 	Call this function to notify hardware device implementation that
   317 	data is available in aFillBufferPtr for decoding.
   318 
   319 	@param  aFillBufferPtr
   320 	        The data buffer filled by the observer.
   321 
   322 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   323 	        another of the system-wide error codes.
   324 	*/
   325 	virtual TInt ThisHwBufferFilled(CMMFBuffer& aFillBufferPtr) = 0;
   326 
   327 	/**
   328 	Call this function to notify hardware device implementation that
   329 	data in aEmptyBufferPtr from encoding is processed.
   330 
   331 	@param  aEmptyBufferPtr
   332 	        The data buffer processed by the observer.
   333 
   334 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   335 	        another of the system-wide error codes.
   336 	*/
   337 	virtual TInt ThisHwBufferEmptied(CMMFBuffer& aEmptyBufferPtr) = 0;
   338 
   339 	/**
   340     Used to configure the sample rate and stereo mode of a CMMFHwDevice plugin.
   341 
   342 	The configuration of HwDevices is device specific and is not used in any of the reference
   343 	devices that return KErrNotSupported.
   344 
   345 	@param  aConfig
   346 	        The device configuration.
   347 	*/
   348 	virtual TInt SetConfig(TTaskConfig& aConfig) = 0;
   349 
   350 	/**
   351 	Call this function to stop and then delete a codec. This is used to allow resources to be freed 
   352 	when using a DSP or similar hardware.
   353 
   354 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   355 	        another of the system-wide error codes.
   356 	*/
   357 	virtual TInt StopAndDeleteCodec() = 0;
   358 
   359 	/**
   360 	Call this function to delete a codec. 
   361 
   362 	This is used to allow resources to be freed when using a DSP or similar hardware.
   363 
   364 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   365 	        another of the system-wide error codes.
   366 	*/
   367 	virtual TInt DeleteCodec() = 0;
   368 
   369 	/**
   370 	Destructor.
   371 
   372 	The destructor is called by ECom framework allowing derived classes
   373 	to clean up the implementation specific resources.
   374 	*/
   375 	inline virtual ~CMMFHwDevice();
   376 
   377 private:
   378 	static void SelectByPreference( RImplInfoPtrArray& aPlugInArray, const TDesC& aPreferredSupplier ) ;
   379 
   380 protected:
   381 	/**
   382 	A pointer to the hardware device observer.
   383 	*/
   384 	MMMFHwDeviceObserver* iHwDeviceObserver;
   385 
   386 //Attributes
   387 private:
   388 	TUid iDtor_ID_Key;
   389 	};
   390 	
   391 #include <mmf/server/mmfhwdevice.inl>
   392 
   393 #endif
   394