1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/devsound/hwdevapi/inc/mmfhwdevice.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,394 @@
1.4 +/*
1.5 +* Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +#ifndef __MMF_HW_DEVICE_H__
1.24 +#define __MMF_HW_DEVICE_H__
1.25 +
1.26 +#include <e32base.h>
1.27 +#include <ecom/implementationinformation.h>
1.28 +#include <mmf/common/mmfutilities.h> //TFourCC
1.29 +#include <mmf/server/mmfhwdevicecmds.h>
1.30 +#include <mmf/server/taskconfig.h>
1.31 +
1.32 +/**
1.33 +@publishedPartner
1.34 +@released
1.35 +
1.36 +The connection type defines what the stream will connect to,
1.37 +either gpp, dsp node, or dsp device.
1.38 +*/
1.39 +typedef enum TConnectionType_tag
1.40 + {
1.41 + /** Gpp
1.42 + */
1.43 + EConnectionGpp,
1.44 + /** dsp node
1.45 + */
1.46 + EConnectionTask,
1.47 + /** dsp device
1.48 + */
1.49 + EConnectionDevice
1.50 + } TConnectionType ;
1.51 +
1.52 +/**
1.53 +@publishedPartner
1.54 +@released
1.55 +
1.56 +Connection Type
1.57 +*/
1.58 +typedef struct TStreamConnection_tag
1.59 + {
1.60 + /** connection id
1.61 + */
1.62 + TInt iId ;
1.63 + /** connection type
1.64 + */
1.65 + TConnectionType iType ;
1.66 + } TStreamConnection;
1.67 +
1.68 +const TUint KMaxDeviceNameLength = 128;
1.69 +
1.70 +enum TSamplingFreq { ESampFreq8k, ESampFreq11025k, ESampFreq16k, ESampFreq2205k, ESampFreq32k, ESampFreq441k, ESampFreq48k, ESampFreq12k, ESampFreq24k, ESampFreq64k};
1.71 +
1.72 +/**
1.73 +@publishedPartner
1.74 +@released
1.75 +
1.76 +Type class for stream connection parameters.
1.77 +This structure defines the connection parameters that are required to
1.78 +be filled in by the HwDevice observer. The connection type defines
1.79 +what the stream will connect to, either gpp, dsp node, or dsp device.
1.80 +*/
1.81 +class TConnection
1.82 + {
1.83 + public:
1.84 + /** Connection type.
1.85 + */
1.86 + TStreamConnection iConnection;
1.87 + /** Name of the device if needed.
1.88 + */
1.89 + TBuf8<KMaxDeviceNameLength> iDeviceName;
1.90 + };
1.91 +
1.92 +// Forward reference
1.93 +class MMMFHwDeviceObserver;
1.94 +
1.95 +/**
1.96 +@publishedPartner
1.97 +@released
1.98 +
1.99 +Type class for Hardware initialization parameters.
1.100 +The implementation specific initialization attributes are passed in this
1.101 +structure. Elements common to all HwDevices are defined here. These are
1.102 +the pointer to the observer and stream connection identification for the
1.103 +HwDevice.
1.104 +
1.105 +These stream connections are defined as follows:
1.106 +- SrcStream is the source data stream to the HwDevice for a decoder/player.
1.107 +- OutStream is the counterpart stream of data out of the HwDevice of
1.108 +processed source data.
1.109 +- InStream is the input stream of data to the HwDevice for an
1.110 +encoder/recorder.
1.111 +- DestStream is the destination data stream of
1.112 +this InStream after it has been processed.
1.113 +
1.114 +The last element is a pointer to a buffer of the rest of the initialization
1.115 +data for the HwDevice. This data will vary for different HwDevices.
1.116 +However, the first element is always the number of internal connections (TUint8)
1.117 +required by the HwDevice. Following this, is an element (TUint8) for each of
1.118 +the required connection ID's. The elements following this are only known by
1.119 +the HwDevice.
1.120 +*/
1.121 +class THwDeviceInitParams
1.122 + {
1.123 + public:
1.124 + THwDeviceInitParams() : iHwDeviceInitArgsPtr(0,0){};
1.125 + /** Pointer to an observer.
1.126 + */
1.127 + MMMFHwDeviceObserver* iHwDeviceObserver;
1.128 + /** Source stream attributes.
1.129 + */
1.130 + TConnection iSrcStream;
1.131 + /** Destination stream attributes.
1.132 + */
1.133 + TConnection iDestStream;
1.134 + /** Input stream attributes.
1.135 + */
1.136 + TConnection iInStream;
1.137 + /** Output stream attributes.
1.138 + */
1.139 + TConnection iOutStream;
1.140 + /** Pointer to a buffer.
1.141 + */
1.142 + TPtr8 iHwDeviceInitArgsPtr;
1.143 + };
1.144 +
1.145 +
1.146 +/**
1.147 +@publishedPartner
1.148 +@released
1.149 +
1.150 +The observer class interface for a hardware device listener class.
1.151 +
1.152 +MMMFHwDeviceObserver provides a generic interface which should be implemented
1.153 +by the classes that are interested in receiving events from the CMMFHwDevice
1.154 +implementation class.
1.155 +*/
1.156 +class MMMFHwDeviceObserver
1.157 + {
1.158 +public:
1.159 +
1.160 + /**
1.161 + Handles CMMFHwDevice object’s data request event.
1.162 +
1.163 + This function is called by the CMMFHwDevice implementation class when it
1.164 + needs data for decoding.
1.165 +
1.166 + @param aHwDataBuffer
1.167 + The buffer to fill the data.
1.168 +
1.169 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.170 + another of the system-wide error codes.
1.171 + */
1.172 + virtual TInt FillThisHwBuffer(CMMFBuffer& aHwDataBuffer) = 0;
1.173 +
1.174 + /**
1.175 + Handles CMMFHwDevice object’s data request event.
1.176 +
1.177 + This function is called by the CMMFHwDevice implementation class when it
1.178 + fills encoded data into a buffer.
1.179 +
1.180 + @param aHwDataBuffer
1.181 + The buffer with encoded data.
1.182 +
1.183 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.184 + another of the system-wide error codes.
1.185 + */
1.186 + virtual TInt EmptyThisHwBuffer(CMMFBuffer& aHwDataBuffer) = 0;
1.187 +
1.188 + /**
1.189 + Handles the CMMFHwDevice object’s message event.
1.190 +
1.191 + This function is called by the CMMFHwDevice implementation class when a
1.192 + message is generated and passed back to the observer.
1.193 +
1.194 + @param aMessageType
1.195 + The type of message. Defines the contents of aMsg.
1.196 + @param aMsg
1.197 + The message packed in a descriptor.
1.198 +
1.199 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.200 + another of the system-wide error codes.
1.201 + */
1.202 + virtual TInt MsgFromHwDevice(TUid aMessageType, const TDesC8& aMsg)=0;
1.203 +
1.204 + /**
1.205 + Called by a CMMFHwDevice derived class when it stops a decoding/encoding task.
1.206 + */
1.207 + virtual void Stopped() = 0;
1.208 +
1.209 + /**
1.210 + Called by a CMMFHwDevice derived class when it stops a decoding/encoding task.
1.211 + */
1.212 + virtual void Error(TInt aError=KErrNone) = 0;
1.213 + };
1.214 +
1.215 +/*
1.216 + *
1.217 + * KMmfUidPluginInterfaceHwDevice
1.218 + *
1.219 + * This UID is the INTERFACE_UID for CMMFHwDevice. It is used to search for hardware device plugins in plugin DLLs.
1.220 + * All hardware device plugin DLLs must include interface_uid = KMmfUidPluginInterfaceHwDevice in their .rss files.
1.221 + *
1.222 + */
1.223 +
1.224 +/**
1.225 +@publishedPartner
1.226 +@released
1.227 +
1.228 +ECom plugin class for a hardware device that decodes (plays) source data in a certain
1.229 +FourCC coding type to another FourCC coding type or encodes (records) data from a certain
1.230 +FourCC coding type to a another FourCC coding type.
1.231 +
1.232 +The hardware device can be instantiated in 3 different ways:
1.233 +
1.234 +1. NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType)
1.235 +
1.236 +This instantiate a hardware device that can encode or decode the aSrcDatatype to a aDstDataType.
1.237 +
1.238 +2. NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier)
1.239 +
1.240 +This is similar to the above but is used where there may be multiple hardware devices that
1.241 +perform the same conversion. Third party developers may use their own
1.242 +hardware device implementations and can ensure the controller uses their implementation by setting
1.243 +the preferred supplier to themselves.
1.244 +
1.245 +3. NewL(TUid aUid)
1.246 +
1.247 +This is used to explicitly instantiate a hardware device where the UID is known.
1.248 +
1.249 +4. NewL(TFileName aFileName)
1.250 +
1.251 +This is used to create an instance of a HwDevice implementation by loading the library
1.252 +
1.253 +CMMFHwDevice provides a generic interface that every Hardware Device that decodes and/or encodes has to implement.
1.254 +Based on parameters specified in Start, the device implementation will start decoding or encoding.
1.255 +The source and destination of the decoding/encoding operations should be set up before starting the task by sending
1.256 +THwDeviceInitParams to the Init() function.
1.257 +*/
1.258 +class CMMFHwDevice : public CBase
1.259 + {
1.260 +public:
1.261 + static CMMFHwDevice* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType);
1.262 + static CMMFHwDevice* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier);
1.263 + inline static CMMFHwDevice* NewL(TUid aUid);
1.264 + static CMMFHwDevice* NewL(TFileName aFileName);
1.265 +
1.266 + /**
1.267 + Starts Encoding or Decoding task(s) based on the parameter specified.
1.268 +
1.269 + @param aFuncCmd
1.270 + The device function specifying the requested service i.e. decode or encode.
1.271 + @param aFlowCmd
1.272 + The device flow directions for the requested service.
1.273 +
1.274 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.275 + another of the system-wide error codes.
1.276 + */
1.277 + virtual TInt Start(TDeviceFunc aFuncCmd, TDeviceFlow aFlowCmd) = 0;
1.278 +
1.279 + /**
1.280 + Stops the current on-going task.
1.281 +
1.282 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.283 + another of the system-wide error codes.
1.284 + */
1.285 + virtual TInt Stop() = 0;
1.286 +
1.287 + /**
1.288 + Temporarily suspends the current task of decoding or encoding.
1.289 +
1.290 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.291 + another of the system-wide error codes.
1.292 + */
1.293 + virtual TInt Pause() = 0;
1.294 +
1.295 + /**
1.296 + Initializes the hardware device tasks.
1.297 +
1.298 + @param aDevInfo
1.299 + The device initialization parameters.
1.300 +
1.301 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.302 + another of the system-wide error codes.
1.303 + */
1.304 + virtual TInt Init(THwDeviceInitParams& aDevInfo) = 0;
1.305 +
1.306 + /**
1.307 + Retrieves a custom interface to the device.
1.308 +
1.309 + @param aInterfaceId
1.310 + The interface UID, defined with the custom interface.
1.311 +
1.312 + @return A pointer to the interface implementation, or NULL if the device does not
1.313 + implement the interface requested. The return value must be cast to the
1.314 + correct type by the user.
1.315 + */
1.316 + virtual TAny* CustomInterface(TUid aInterfaceId) = 0;
1.317 +
1.318 + /**
1.319 + Call this function to notify hardware device implementation that
1.320 + data is available in aFillBufferPtr for decoding.
1.321 +
1.322 + @param aFillBufferPtr
1.323 + The data buffer filled by the observer.
1.324 +
1.325 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.326 + another of the system-wide error codes.
1.327 + */
1.328 + virtual TInt ThisHwBufferFilled(CMMFBuffer& aFillBufferPtr) = 0;
1.329 +
1.330 + /**
1.331 + Call this function to notify hardware device implementation that
1.332 + data in aEmptyBufferPtr from encoding is processed.
1.333 +
1.334 + @param aEmptyBufferPtr
1.335 + The data buffer processed by the observer.
1.336 +
1.337 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.338 + another of the system-wide error codes.
1.339 + */
1.340 + virtual TInt ThisHwBufferEmptied(CMMFBuffer& aEmptyBufferPtr) = 0;
1.341 +
1.342 + /**
1.343 + Used to configure the sample rate and stereo mode of a CMMFHwDevice plugin.
1.344 +
1.345 + The configuration of HwDevices is device specific and is not used in any of the reference
1.346 + devices that return KErrNotSupported.
1.347 +
1.348 + @param aConfig
1.349 + The device configuration.
1.350 + */
1.351 + virtual TInt SetConfig(TTaskConfig& aConfig) = 0;
1.352 +
1.353 + /**
1.354 + Call this function to stop and then delete a codec. This is used to allow resources to be freed
1.355 + when using a DSP or similar hardware.
1.356 +
1.357 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.358 + another of the system-wide error codes.
1.359 + */
1.360 + virtual TInt StopAndDeleteCodec() = 0;
1.361 +
1.362 + /**
1.363 + Call this function to delete a codec.
1.364 +
1.365 + This is used to allow resources to be freed when using a DSP or similar hardware.
1.366 +
1.367 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.368 + another of the system-wide error codes.
1.369 + */
1.370 + virtual TInt DeleteCodec() = 0;
1.371 +
1.372 + /**
1.373 + Destructor.
1.374 +
1.375 + The destructor is called by ECom framework allowing derived classes
1.376 + to clean up the implementation specific resources.
1.377 + */
1.378 + inline virtual ~CMMFHwDevice();
1.379 +
1.380 +private:
1.381 + static void SelectByPreference( RImplInfoPtrArray& aPlugInArray, const TDesC& aPreferredSupplier ) ;
1.382 +
1.383 +protected:
1.384 + /**
1.385 + A pointer to the hardware device observer.
1.386 + */
1.387 + MMMFHwDeviceObserver* iHwDeviceObserver;
1.388 +
1.389 +//Attributes
1.390 +private:
1.391 + TUid iDtor_ID_Key;
1.392 + };
1.393 +
1.394 +#include <mmf/server/mmfhwdevice.inl>
1.395 +
1.396 +#endif
1.397 +