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