diff -r 000000000000 -r 40261b775718 mmlibs/mmfw/inc/mmf/server/MmfCodec.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmlibs/mmfw/inc/mmf/server/MmfCodec.h Tue Feb 02 01:56:55 2010 +0200 @@ -0,0 +1,341 @@ +// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// include\mmf\common\mmfcodec.h +// +// + +#ifndef MMFCODEC_H +#define MMFCODEC_H + + +#include +#include +#include +#include + +/* + * This UID is the INTERFACE_UID for CMMFCodec. It is used to search for codec plugins in plugin DLLs. + * All codec plugin DLLs must include interface_uid = KMmfUidPluginInterfaceCodec in their .rss files. + */ + +/** +@publishedAll +@released + +Indicates the result of processing data from the source buffer to a destination buffer +and provides functions to compare the result code. +*/ +class TCodecProcessResult + { +public: + /** + Flag to track the codec's processing status. + */ + enum TCodecProcessResultStatus + { + /** + The codec successfully has completed its processing. + + A codec should return this code when it has fully processed the source buffer, and is finished + with the destination buffer. The codec should finish with the destination buffer when it has + been filled. The EProcessComplete return code indicates that the codec has finished + with the destination buffer. This informs the data path that the destination buffer may now be + passed onto the data sink. If the codec returns EProcessComplete this means that the codec is + expecting a new source buffer and a new destination buffer the next time it's ProcessL() method + is called. + */ + EProcessComplete, + /** + Could not empty the source buffer because the destination buffer became full. + + A codec should return this code when it has not been able to fully process the source buffer. + This would usually be the case if the codec has filled the destination buffer (or the remaining + space available in the destination buffer is insufficient to perform any further useful + processing) before the source buffer has been processed. The EProcessIncomplete return code + indicates that the codec has finished with the destination buffer. This informs the data path + that the destination buffer may now be passed onto the data sink. If the codec returns + EProcessIncomplete this means that the codec is expecting the same source buffer but a new + destination buffer the next time it's ProcessL() method is called. + */ + EProcessIncomplete, + + /** + Codec came across an end of data. + + This can be returned if a codec is able to determine that there is no more source data. It is + not necessary for the codec to return this however as in most cases the codec will not be able + to determine when the end of data has been reached. + */ + EEndOfData, + + /** + Could not fill the destination buffer because the source buffer has been emptied + + A codec should return this code when is has fully processed the source buffer and there is still + sufficient space available in the destination buffer for the codec to continue using the same + destination buffer. The EDstNotFilled return code indicates that the codec has not finished with + the destination buffer. If the codec returns EDstNotFilled this means that the codec is + expecting a new source buffer but the same destination buffer the next time its ProcessL() + method is called. + */ + EDstNotFilled, + + /** + An error occured. + + This is no longer required as if an error occurs in the codec's ProcessL()function, it should + leave. When used with a datapath, returning EProcessError has the same effect as leaving with + KErrCorrupt. + */ + EProcessError, + + /** + @deprecated + + As 'EFrameIncomplete' but also requests a call to GetNewDataPosition. + */ + EProcessIncompleteRepositionRequest, + + /** + @deprecated + + As 'EFrameComplete' but also requests a call to GetNewDataPosition. + */ + EProcessCompleteRepositionRequest + }; + + /** + Overloaded operator to test equality. + + @param aStatus + The status to compare the result of the process function. + + @return A boolean indicating if the two status codes are the same. ETrue if they are, EFalse + otherwise. + */ + TBool operator==(const TCodecProcessResultStatus aStatus) const {return (iStatus == aStatus);} + + /** + Overloaded operator to test inequality. + + @param aStatus + The status to compare the result of the process function. + @return A boolean indicating if the two status codes are not the same. ETrue if they are not, + EFalse otherwise. + */ + TBool operator!=(const TCodecProcessResultStatus aStatus) const {return (iStatus != aStatus);} + + /** + The codec's processing status. + + @see enum TCodecProcessResultStatus + */ + TCodecProcessResultStatus iStatus; + + /** + The number of source bytes processed. + + The number of bytes of source data that have been processed. + + A codec should set this, and iDstBytesAdded, to indicate the source bytes processed for a + particular call (i.e. not the total number of source bytes processed or destination bytes + added). The codec should also ensure that the length of the destination buffer matches the + length of the processed data in the destination buffer. Note that the codec should not + reallocate the maximum length of the destination buffer. + */ + TUint iSrcBytesProcessed; + + /** + The number of bytes added to the destination buffer. + + A codec should set this, and iSrcBytesProcessed, to indicate the source bytes processed for a + particular call (i.e. not the total number of source bytes processed or destination bytes + added). The codec should also ensure that the length of the destination buffer matches the + length of the processed data in the destination buffer. Note that the codec should not + reallocate the maximum length of the destination buffer. + */ + TUint iDstBytesAdded; +public: + + /** + Default constructor. + */ + TCodecProcessResult() + :iStatus(EProcessError), iSrcBytesProcessed(0), iDstBytesAdded(0) {}; +private: + /** + This member is internal and not intended for use. + */ + TInt iReserved1; + TInt iReserved2; + TInt iReserved3; + }; + + +class TFourCC; //forward reference +class CMMFBuffer; //forward reference + +/** +@publishedAll +@released + +ECom plugin class for a codec that processes source data in a certain fourCC coding type and +converts it to a destination buffer of another fourCC coding type. +The function is synchronous as it is expected that the codec will be operating in its own thread +of execution - usually via a CMMFDataPath or CMMFDataPathProxy + +The codec can be instantiated in 3 different ways: + +1. NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType). + +This instantiate a codec that can convert the aSrcDatatype to a aDstDataType. + +2. NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier). + +This is similar to the above but is used where there may be multiple codecs that +perform the same conversion - the idea is that a 3rd party deveoper may develop there own +controller and codecs and can ensure the controller uses their codecs by setting the preferredSupplier +to themselves. + +3. NewL(TUid aUid). + +This is used to explicitly instantiated a codec where the uid is known. This might be used by +controlers that only support one codec type. + +The processing of the data is handled by the codecs ProcessL() member. +The intention is that the source buffer for conversion is converted to the appropriate coding type +in the destination buffer. The buffers can be of any size. Since the buffers can be of any size there is no +guarantee that all the source buffer can be processed to fill the destination buffer or that the +all the source buffer may be processed before the destination is full. Therefore the +ProcessL needs to return a TCodecProcessResult returing the number of source bytes processed +and the number of destination bytes processed along with a process result code defined thus: +- EProcessComplete: the codec processed all the source data into the sink buffer +- EProcessIncomplete: the codec filled sink buffer before all the source buffer was processed +- EDstNotFilled: the codec processed the source buffer but the sink buffer was not filled +- EEndOfData: the codec detected the end data - all source data in processed but sink may not be full +- EProcessError: the codec process error condition + +The ProcessL should start processing the source buffer from the iPosition data member of the source data +and start filling the destination buffer from its iPosition. +*/ +class CMMFCodec : public CBase +{ +public: + //The function which instantiates an object of this type + // using the TFourCC codes as the resolver parameters. + IMPORT_C static CMMFCodec* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType); + IMPORT_C static CMMFCodec* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier); + IMPORT_C static CMMFCodec* NewL(TUid aUid); + + static void SelectByPreference( RImplInfoPtrArray& aPlugInArray, const TDesC& aPreferredSupplier ) ; + + inline virtual void ConfigureL(TUid aConfigType, const TDesC8& aConfigData); + + /** + Codec reset. + + Used to flush out status information when a reposition occurs. This is a virtual function that + is provided should the codec require resetting prior to use. + */ + virtual void ResetL() {} + //Standardised destructor. + inline virtual ~CMMFCodec(); + + + /** + Processes the data in the specified source buffer and writes the processed data to the specified + destination buffer. + + This function is synchronous, when the function returns the data has been processed. The source + buffer is converted to the appropriate coding type in the destination buffer. The buffers can be + of any size, therefore there is no guarantee that all the source buffer can be processed to fill + the destination buffer or that all the source buffer may be processed before the destination is + full. This function therefore returns the number of source, and destination, bytes processed + along with a process result code indicating completion status. + + The aSource and aSink buffers passed in are derived from CMMFBuffer. The buffer type (e.g. a + CMMFDataBuffer) passed in should be supported by the codec otherwise this function should leave + with KErrNotSupported. The position of the source buffer should be checked by calling the source + buffer's Position() member which indicates the current source read position in bytes. The codec + should start processing from the current source buffer read position. The position of the + destination buffer should be checked by calling the destination buffer's Position() method which + indicates the current destination write position in bytes. The codec should start writing to the + destination buffer at the current destination buffer write position. + + This is a virtual function that each derived class must implement. + + @see enum TCodecProcessResult + + @param aSource + The source buffer containing data to encode or decode. + @param aDestination + The destination buffer to hold the data after encoding or decoding. + + @return The result of the processing. + */ + virtual TCodecProcessResult ProcessL(const CMMFBuffer& aSource, CMMFBuffer& aDestination) = 0; + + /** + @internalComponent + + Gets a pointer to the extension specified by an identifier. The extension can be either an + interface or function. If the extension is not supported NULL value is given and returns + KErrExtensionNotSupported. + + @param aExtensionId + Extension identifier. + @param aExtPtr + Pointer to get the extension. + @return If successful returns KErrNone otherwise KErrExtensionNotSupported. + */ + TInt ExtensionInterface(TUint aExtensionId, TAny*& aExtPtr); + +private: + TUid iDtor_ID_Key; +}; + +/** +Destructor. + +Destroys any variables then informs ECom that this specific instance of the interface has been +destroyed. +*/ +inline CMMFCodec::~CMMFCodec() + { + // Destroy any instance variables and then + // inform ecom that this specific + // instance of the interface has been destroyed. + REComSession::DestroyedImplementation(iDtor_ID_Key); + } + +/** +Sets codec configuration. + +This is a virtual function which does not need to be implemented +by a codec, but may be if required. This function provides additional configuration +information for the codec. The configuration is passed in as a descriptor. +The default version leaves with KErrNotSupported. + +@param aConfigType + The UID of the configuration data. +@param aConfigData + The configuration information. +*/ +inline void CMMFCodec::ConfigureL(TUid /*aConfigType*/, const TDesC8& /*aConfigData*/) +{ + User::Leave(KErrNotSupported); +} + +#endif +