1 // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // include\mmf\common\mmfcodec.h
23 #include <ecom/ecom.h>
24 #include <mmf/common/mmfutilities.h>
25 #include <mmf/plugin/mmfplugininterfaceuids.hrh>
28 * This UID is the INTERFACE_UID for CMMFCodec. It is used to search for codec plugins in plugin DLLs.
29 * All codec plugin DLLs must include interface_uid = KMmfUidPluginInterfaceCodec in their .rss files.
36 Indicates the result of processing data from the source buffer to a destination buffer
37 and provides functions to compare the result code.
39 class TCodecProcessResult
43 Flag to track the codec's processing status.
45 enum TCodecProcessResultStatus
48 The codec successfully has completed its processing.
50 A codec should return this code when it has fully processed the source buffer, and is finished
51 with the destination buffer. The codec should finish with the destination buffer when it has
52 been filled. The EProcessComplete return code indicates that the codec has finished
53 with the destination buffer. This informs the data path that the destination buffer may now be
54 passed onto the data sink. If the codec returns EProcessComplete this means that the codec is
55 expecting a new source buffer and a new destination buffer the next time it's ProcessL() method
60 Could not empty the source buffer because the destination buffer became full.
62 A codec should return this code when it has not been able to fully process the source buffer.
63 This would usually be the case if the codec has filled the destination buffer (or the remaining
64 space available in the destination buffer is insufficient to perform any further useful
65 processing) before the source buffer has been processed. The EProcessIncomplete return code
66 indicates that the codec has finished with the destination buffer. This informs the data path
67 that the destination buffer may now be passed onto the data sink. If the codec returns
68 EProcessIncomplete this means that the codec is expecting the same source buffer but a new
69 destination buffer the next time it's ProcessL() method is called.
74 Codec came across an end of data.
76 This can be returned if a codec is able to determine that there is no more source data. It is
77 not necessary for the codec to return this however as in most cases the codec will not be able
78 to determine when the end of data has been reached.
83 Could not fill the destination buffer because the source buffer has been emptied
85 A codec should return this code when is has fully processed the source buffer and there is still
86 sufficient space available in the destination buffer for the codec to continue using the same
87 destination buffer. The EDstNotFilled return code indicates that the codec has not finished with
88 the destination buffer. If the codec returns EDstNotFilled this means that the codec is
89 expecting a new source buffer but the same destination buffer the next time its ProcessL()
97 This is no longer required as if an error occurs in the codec's ProcessL()function, it should
98 leave. When used with a datapath, returning EProcessError has the same effect as leaving with
106 As 'EFrameIncomplete' but also requests a call to GetNewDataPosition.
108 EProcessIncompleteRepositionRequest,
113 As 'EFrameComplete' but also requests a call to GetNewDataPosition.
115 EProcessCompleteRepositionRequest
119 Overloaded operator to test equality.
122 The status to compare the result of the process function.
124 @return A boolean indicating if the two status codes are the same. ETrue if they are, EFalse
127 TBool operator==(const TCodecProcessResultStatus aStatus) const {return (iStatus == aStatus);}
130 Overloaded operator to test inequality.
133 The status to compare the result of the process function.
134 @return A boolean indicating if the two status codes are not the same. ETrue if they are not,
137 TBool operator!=(const TCodecProcessResultStatus aStatus) const {return (iStatus != aStatus);}
140 The codec's processing status.
142 @see enum TCodecProcessResultStatus
144 TCodecProcessResultStatus iStatus;
147 The number of source bytes processed.
149 The number of bytes of source data that have been processed.
151 A codec should set this, and iDstBytesAdded, to indicate the source bytes processed for a
152 particular call (i.e. not the total number of source bytes processed or destination bytes
153 added). The codec should also ensure that the length of the destination buffer matches the
154 length of the processed data in the destination buffer. Note that the codec should not
155 reallocate the maximum length of the destination buffer.
157 TUint iSrcBytesProcessed;
160 The number of bytes added to the destination buffer.
162 A codec should set this, and iSrcBytesProcessed, to indicate the source bytes processed for a
163 particular call (i.e. not the total number of source bytes processed or destination bytes
164 added). The codec should also ensure that the length of the destination buffer matches the
165 length of the processed data in the destination buffer. Note that the codec should not
166 reallocate the maximum length of the destination buffer.
168 TUint iDstBytesAdded;
174 TCodecProcessResult()
175 :iStatus(EProcessError), iSrcBytesProcessed(0), iDstBytesAdded(0) {};
178 This member is internal and not intended for use.
186 class TFourCC; //forward reference
187 class CMMFBuffer; //forward reference
193 ECom plugin class for a codec that processes source data in a certain fourCC coding type and
194 converts it to a destination buffer of another fourCC coding type.
195 The function is synchronous as it is expected that the codec will be operating in its own thread
196 of execution - usually via a CMMFDataPath or CMMFDataPathProxy
198 The codec can be instantiated in 3 different ways:
200 1. NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType).
202 This instantiate a codec that can convert the aSrcDatatype to a aDstDataType.
204 2. NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier).
206 This is similar to the above but is used where there may be multiple codecs that
207 perform the same conversion - the idea is that a 3rd party deveoper may develop there own
208 controller and codecs and can ensure the controller uses their codecs by setting the preferredSupplier
213 This is used to explicitly instantiated a codec where the uid is known. This might be used by
214 controlers that only support one codec type.
216 The processing of the data is handled by the codecs ProcessL() member.
217 The intention is that the source buffer for conversion is converted to the appropriate coding type
218 in the destination buffer. The buffers can be of any size. Since the buffers can be of any size there is no
219 guarantee that all the source buffer can be processed to fill the destination buffer or that the
220 all the source buffer may be processed before the destination is full. Therefore the
221 ProcessL needs to return a TCodecProcessResult returing the number of source bytes processed
222 and the number of destination bytes processed along with a process result code defined thus:
223 - EProcessComplete: the codec processed all the source data into the sink buffer
224 - EProcessIncomplete: the codec filled sink buffer before all the source buffer was processed
225 - EDstNotFilled: the codec processed the source buffer but the sink buffer was not filled
226 - EEndOfData: the codec detected the end data - all source data in processed but sink may not be full
227 - EProcessError: the codec process error condition
229 The ProcessL should start processing the source buffer from the iPosition data member of the source data
230 and start filling the destination buffer from its iPosition.
232 class CMMFCodec : public CBase
235 //The function which instantiates an object of this type
236 // using the TFourCC codes as the resolver parameters.
237 IMPORT_C static CMMFCodec* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType);
238 IMPORT_C static CMMFCodec* NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier);
239 IMPORT_C static CMMFCodec* NewL(TUid aUid);
241 static void SelectByPreference( RImplInfoPtrArray& aPlugInArray, const TDesC& aPreferredSupplier ) ;
243 inline virtual void ConfigureL(TUid aConfigType, const TDesC8& aConfigData);
248 Used to flush out status information when a reposition occurs. This is a virtual function that
249 is provided should the codec require resetting prior to use.
251 virtual void ResetL() {}
252 //Standardised destructor.
253 inline virtual ~CMMFCodec();
257 Processes the data in the specified source buffer and writes the processed data to the specified
260 This function is synchronous, when the function returns the data has been processed. The source
261 buffer is converted to the appropriate coding type in the destination buffer. The buffers can be
262 of any size, therefore there is no guarantee that all the source buffer can be processed to fill
263 the destination buffer or that all the source buffer may be processed before the destination is
264 full. This function therefore returns the number of source, and destination, bytes processed
265 along with a process result code indicating completion status.
267 The aSource and aSink buffers passed in are derived from CMMFBuffer. The buffer type (e.g. a
268 CMMFDataBuffer) passed in should be supported by the codec otherwise this function should leave
269 with KErrNotSupported. The position of the source buffer should be checked by calling the source
270 buffer's Position() member which indicates the current source read position in bytes. The codec
271 should start processing from the current source buffer read position. The position of the
272 destination buffer should be checked by calling the destination buffer's Position() method which
273 indicates the current destination write position in bytes. The codec should start writing to the
274 destination buffer at the current destination buffer write position.
276 This is a virtual function that each derived class must implement.
278 @see enum TCodecProcessResult
281 The source buffer containing data to encode or decode.
283 The destination buffer to hold the data after encoding or decoding.
285 @return The result of the processing.
287 virtual TCodecProcessResult ProcessL(const CMMFBuffer& aSource, CMMFBuffer& aDestination) = 0;
292 Gets a pointer to the extension specified by an identifier. The extension can be either an
293 interface or function. If the extension is not supported NULL value is given and returns
294 KErrExtensionNotSupported.
297 Extension identifier.
299 Pointer to get the extension.
300 @return If successful returns KErrNone otherwise KErrExtensionNotSupported.
302 TInt ExtensionInterface(TUint aExtensionId, TAny*& aExtPtr);
311 Destroys any variables then informs ECom that this specific instance of the interface has been
314 inline CMMFCodec::~CMMFCodec()
316 // Destroy any instance variables and then
317 // inform ecom that this specific
318 // instance of the interface has been destroyed.
319 REComSession::DestroyedImplementation(iDtor_ID_Key);
323 Sets codec configuration.
325 This is a virtual function which does not need to be implemented
326 by a codec, but may be if required. This function provides additional configuration
327 information for the codec. The configuration is passed in as a descriptor.
328 The default version leaves with KErrNotSupported.
331 The UID of the configuration data.
333 The configuration information.
335 inline void CMMFCodec::ConfigureL(TUid /*aConfigType*/, const TDesC8& /*aConfigData*/)
337 User::Leave(KErrNotSupported);