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