1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/mmlibs/mmfw/inc/mmf/server/MmfCodec.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,341 @@
1.4 +// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// include\mmf\common\mmfcodec.h
1.18 +//
1.19 +//
1.20 +
1.21 +#ifndef MMFCODEC_H
1.22 +#define MMFCODEC_H
1.23 +
1.24 +
1.25 +#include <e32base.h>
1.26 +#include <ecom/ecom.h>
1.27 +#include <mmf/common/mmfutilities.h>
1.28 +#include <mmf/plugin/mmfplugininterfaceuids.hrh>
1.29 +
1.30 +/*
1.31 + * This UID is the INTERFACE_UID for CMMFCodec. It is used to search for codec plugins in plugin DLLs.
1.32 + * All codec plugin DLLs must include interface_uid = KMmfUidPluginInterfaceCodec in their .rss files.
1.33 + */
1.34 +
1.35 +/**
1.36 +@publishedAll
1.37 +@released
1.38 +
1.39 +Indicates the result of processing data from the source buffer to a destination buffer
1.40 +and provides functions to compare the result code.
1.41 +*/
1.42 +class TCodecProcessResult
1.43 + {
1.44 +public:
1.45 + /**
1.46 + Flag to track the codec's processing status.
1.47 + */
1.48 + enum TCodecProcessResultStatus
1.49 + {
1.50 + /**
1.51 + The codec successfully has completed its processing.
1.52 +
1.53 + A codec should return this code when it has fully processed the source buffer, and is finished
1.54 + with the destination buffer. The codec should finish with the destination buffer when it has
1.55 + been filled. The EProcessComplete return code indicates that the codec has finished
1.56 + with the destination buffer. This informs the data path that the destination buffer may now be
1.57 + passed onto the data sink. If the codec returns EProcessComplete this means that the codec is
1.58 + expecting a new source buffer and a new destination buffer the next time it's ProcessL() method
1.59 + is called.
1.60 + */
1.61 + EProcessComplete,
1.62 + /**
1.63 + Could not empty the source buffer because the destination buffer became full.
1.64 +
1.65 + A codec should return this code when it has not been able to fully process the source buffer.
1.66 + This would usually be the case if the codec has filled the destination buffer (or the remaining
1.67 + space available in the destination buffer is insufficient to perform any further useful
1.68 + processing) before the source buffer has been processed. The EProcessIncomplete return code
1.69 + indicates that the codec has finished with the destination buffer. This informs the data path
1.70 + that the destination buffer may now be passed onto the data sink. If the codec returns
1.71 + EProcessIncomplete this means that the codec is expecting the same source buffer but a new
1.72 + destination buffer the next time it's ProcessL() method is called.
1.73 + */
1.74 + EProcessIncomplete,
1.75 +
1.76 + /**
1.77 + Codec came across an end of data.
1.78 +
1.79 + This can be returned if a codec is able to determine that there is no more source data. It is
1.80 + not necessary for the codec to return this however as in most cases the codec will not be able
1.81 + to determine when the end of data has been reached.
1.82 + */
1.83 + EEndOfData,
1.84 +
1.85 + /**
1.86 + Could not fill the destination buffer because the source buffer has been emptied
1.87 +
1.88 + A codec should return this code when is has fully processed the source buffer and there is still
1.89 + sufficient space available in the destination buffer for the codec to continue using the same
1.90 + destination buffer. The EDstNotFilled return code indicates that the codec has not finished with
1.91 + the destination buffer. If the codec returns EDstNotFilled this means that the codec is
1.92 + expecting a new source buffer but the same destination buffer the next time its ProcessL()
1.93 + method is called.
1.94 + */
1.95 + EDstNotFilled,
1.96 +
1.97 + /**
1.98 + An error occured.
1.99 +
1.100 + This is no longer required as if an error occurs in the codec's ProcessL()function, it should
1.101 + leave. When used with a datapath, returning EProcessError has the same effect as leaving with
1.102 + KErrCorrupt.
1.103 + */
1.104 + EProcessError,
1.105 +
1.106 + /**
1.107 + @deprecated
1.108 +
1.109 + As 'EFrameIncomplete' but also requests a call to GetNewDataPosition.
1.110 + */
1.111 + EProcessIncompleteRepositionRequest,
1.112 +
1.113 + /**
1.114 + @deprecated
1.115 +
1.116 + As 'EFrameComplete' but also requests a call to GetNewDataPosition.
1.117 + */
1.118 + EProcessCompleteRepositionRequest
1.119 + };
1.120 +
1.121 + /**
1.122 + Overloaded operator to test equality.
1.123 +
1.124 + @param aStatus
1.125 + The status to compare the result of the process function.
1.126 +
1.127 + @return A boolean indicating if the two status codes are the same. ETrue if they are, EFalse
1.128 + otherwise.
1.129 + */
1.130 + TBool operator==(const TCodecProcessResultStatus aStatus) const {return (iStatus == aStatus);}
1.131 +
1.132 + /**
1.133 + Overloaded operator to test inequality.
1.134 +
1.135 + @param aStatus
1.136 + The status to compare the result of the process function.
1.137 + @return A boolean indicating if the two status codes are not the same. ETrue if they are not,
1.138 + EFalse otherwise.
1.139 + */
1.140 + TBool operator!=(const TCodecProcessResultStatus aStatus) const {return (iStatus != aStatus);}
1.141 +
1.142 + /**
1.143 + The codec's processing status.
1.144 +
1.145 + @see enum TCodecProcessResultStatus
1.146 + */
1.147 + TCodecProcessResultStatus iStatus;
1.148 +
1.149 + /**
1.150 + The number of source bytes processed.
1.151 +
1.152 + The number of bytes of source data that have been processed.
1.153 +
1.154 + A codec should set this, and iDstBytesAdded, to indicate the source bytes processed for a
1.155 + particular call (i.e. not the total number of source bytes processed or destination bytes
1.156 + added). The codec should also ensure that the length of the destination buffer matches the
1.157 + length of the processed data in the destination buffer. Note that the codec should not
1.158 + reallocate the maximum length of the destination buffer.
1.159 + */
1.160 + TUint iSrcBytesProcessed;
1.161 +
1.162 + /**
1.163 + The number of bytes added to the destination buffer.
1.164 +
1.165 + A codec should set this, and iSrcBytesProcessed, to indicate the source bytes processed for a
1.166 + particular call (i.e. not the total number of source bytes processed or destination bytes
1.167 + added). The codec should also ensure that the length of the destination buffer matches the
1.168 + length of the processed data in the destination buffer. Note that the codec should not
1.169 + reallocate the maximum length of the destination buffer.
1.170 + */
1.171 + TUint iDstBytesAdded;
1.172 +public:
1.173 +
1.174 + /**
1.175 + Default constructor.
1.176 + */
1.177 + TCodecProcessResult()
1.178 + :iStatus(EProcessError), iSrcBytesProcessed(0), iDstBytesAdded(0) {};
1.179 +private:
1.180 + /**
1.181 + This member is internal and not intended for use.
1.182 + */
1.183 + TInt iReserved1;
1.184 + TInt iReserved2;
1.185 + TInt iReserved3;
1.186 + };
1.187 +
1.188 +
1.189 +class TFourCC; //forward reference
1.190 +class CMMFBuffer; //forward reference
1.191 +
1.192 +/**
1.193 +@publishedAll
1.194 +@released
1.195 +
1.196 +ECom plugin class for a codec that processes source data in a certain fourCC coding type and
1.197 +converts it to a destination buffer of another fourCC coding type.
1.198 +The function is synchronous as it is expected that the codec will be operating in its own thread
1.199 +of execution - usually via a CMMFDataPath or CMMFDataPathProxy
1.200 +
1.201 +The codec can be instantiated in 3 different ways:
1.202 +
1.203 +1. NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType).
1.204 +
1.205 +This instantiate a codec that can convert the aSrcDatatype to a aDstDataType.
1.206 +
1.207 +2. NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier).
1.208 +
1.209 +This is similar to the above but is used where there may be multiple codecs that
1.210 +perform the same conversion - the idea is that a 3rd party deveoper may develop there own
1.211 +controller and codecs and can ensure the controller uses their codecs by setting the preferredSupplier
1.212 +to themselves.
1.213 +
1.214 +3. NewL(TUid aUid).
1.215 +
1.216 +This is used to explicitly instantiated a codec where the uid is known. This might be used by
1.217 +controlers that only support one codec type.
1.218 +
1.219 +The processing of the data is handled by the codecs ProcessL() member.
1.220 +The intention is that the source buffer for conversion is converted to the appropriate coding type
1.221 +in the destination buffer. The buffers can be of any size. Since the buffers can be of any size there is no
1.222 +guarantee that all the source buffer can be processed to fill the destination buffer or that the
1.223 +all the source buffer may be processed before the destination is full. Therefore the
1.224 +ProcessL needs to return a TCodecProcessResult returing the number of source bytes processed
1.225 +and the number of destination bytes processed along with a process result code defined thus:
1.226 +- EProcessComplete: the codec processed all the source data into the sink buffer
1.227 +- EProcessIncomplete: the codec filled sink buffer before all the source buffer was processed
1.228 +- EDstNotFilled: the codec processed the source buffer but the sink buffer was not filled
1.229 +- EEndOfData: the codec detected the end data - all source data in processed but sink may not be full
1.230 +- EProcessError: the codec process error condition
1.231 +
1.232 +The ProcessL should start processing the source buffer from the iPosition data member of the source data
1.233 +and start filling the destination buffer from its iPosition.
1.234 +*/
1.235 +class CMMFCodec : public CBase
1.236 +{
1.237 +public:
1.238 + //The function which instantiates an object of this type
1.239 + // using the TFourCC codes as the resolver parameters.
1.240 + IMPORT_C static CMMFCodec* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType);
1.241 + IMPORT_C static CMMFCodec* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier);
1.242 + IMPORT_C static CMMFCodec* NewL(TUid aUid);
1.243 +
1.244 + static void SelectByPreference( RImplInfoPtrArray& aPlugInArray, const TDesC& aPreferredSupplier ) ;
1.245 +
1.246 + inline virtual void ConfigureL(TUid aConfigType, const TDesC8& aConfigData);
1.247 +
1.248 + /**
1.249 + Codec reset.
1.250 +
1.251 + Used to flush out status information when a reposition occurs. This is a virtual function that
1.252 + is provided should the codec require resetting prior to use.
1.253 + */
1.254 + virtual void ResetL() {}
1.255 + //Standardised destructor.
1.256 + inline virtual ~CMMFCodec();
1.257 +
1.258 +
1.259 + /**
1.260 + Processes the data in the specified source buffer and writes the processed data to the specified
1.261 + destination buffer.
1.262 +
1.263 + This function is synchronous, when the function returns the data has been processed. The source
1.264 + buffer is converted to the appropriate coding type in the destination buffer. The buffers can be
1.265 + of any size, therefore there is no guarantee that all the source buffer can be processed to fill
1.266 + the destination buffer or that all the source buffer may be processed before the destination is
1.267 + full. This function therefore returns the number of source, and destination, bytes processed
1.268 + along with a process result code indicating completion status.
1.269 +
1.270 + The aSource and aSink buffers passed in are derived from CMMFBuffer. The buffer type (e.g. a
1.271 + CMMFDataBuffer) passed in should be supported by the codec otherwise this function should leave
1.272 + with KErrNotSupported. The position of the source buffer should be checked by calling the source
1.273 + buffer's Position() member which indicates the current source read position in bytes. The codec
1.274 + should start processing from the current source buffer read position. The position of the
1.275 + destination buffer should be checked by calling the destination buffer's Position() method which
1.276 + indicates the current destination write position in bytes. The codec should start writing to the
1.277 + destination buffer at the current destination buffer write position.
1.278 +
1.279 + This is a virtual function that each derived class must implement.
1.280 +
1.281 + @see enum TCodecProcessResult
1.282 +
1.283 + @param aSource
1.284 + The source buffer containing data to encode or decode.
1.285 + @param aDestination
1.286 + The destination buffer to hold the data after encoding or decoding.
1.287 +
1.288 + @return The result of the processing.
1.289 + */
1.290 + virtual TCodecProcessResult ProcessL(const CMMFBuffer& aSource, CMMFBuffer& aDestination) = 0;
1.291 +
1.292 + /**
1.293 + @internalComponent
1.294 +
1.295 + Gets a pointer to the extension specified by an identifier. The extension can be either an
1.296 + interface or function. If the extension is not supported NULL value is given and returns
1.297 + KErrExtensionNotSupported.
1.298 +
1.299 + @param aExtensionId
1.300 + Extension identifier.
1.301 + @param aExtPtr
1.302 + Pointer to get the extension.
1.303 + @return If successful returns KErrNone otherwise KErrExtensionNotSupported.
1.304 + */
1.305 + TInt ExtensionInterface(TUint aExtensionId, TAny*& aExtPtr);
1.306 +
1.307 +private:
1.308 + TUid iDtor_ID_Key;
1.309 +};
1.310 +
1.311 +/**
1.312 +Destructor.
1.313 +
1.314 +Destroys any variables then informs ECom that this specific instance of the interface has been
1.315 +destroyed.
1.316 +*/
1.317 +inline CMMFCodec::~CMMFCodec()
1.318 + {
1.319 + // Destroy any instance variables and then
1.320 + // inform ecom that this specific
1.321 + // instance of the interface has been destroyed.
1.322 + REComSession::DestroyedImplementation(iDtor_ID_Key);
1.323 + }
1.324 +
1.325 +/**
1.326 +Sets codec configuration.
1.327 +
1.328 +This is a virtual function which does not need to be implemented
1.329 +by a codec, but may be if required. This function provides additional configuration
1.330 +information for the codec. The configuration is passed in as a descriptor.
1.331 +The default version leaves with KErrNotSupported.
1.332 +
1.333 +@param aConfigType
1.334 + The UID of the configuration data.
1.335 +@param aConfigData
1.336 + The configuration information.
1.337 +*/
1.338 +inline void CMMFCodec::ConfigureL(TUid /*aConfigType*/, const TDesC8& /*aConfigData*/)
1.339 +{
1.340 + User::Leave(KErrNotSupported);
1.341 +}
1.342 +
1.343 +#endif
1.344 +