epoc32/include/mmf/server/mmfcodec.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 // include\mmf\common\mmfcodec.h
    15 // 
    16 //
    17 
    18 #ifndef MMFCODEC_H
    19 #define MMFCODEC_H
    20 
    21 
    22 #include <e32base.h>
    23 #include <ecom/ecom.h>
    24 #include <mmf/common/mmfutilities.h>
    25 #include <mmf/plugin/mmfplugininterfaceuids.hrh>
    26 
    27 /*
    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.
    30  */
    31 
    32 /**
    33 @publishedAll
    34 @released
    35 
    36 Indicates the result of processing data from the source buffer to a destination buffer
    37 and provides functions to compare the result code.
    38 */
    39 class TCodecProcessResult
    40 	{
    41 public:
    42 	/**
    43 	Flag to track the codec's processing status.
    44 	*/
    45 	enum TCodecProcessResultStatus
    46 	{
    47 	/** 
    48 	The codec successfully has completed its processing.
    49 
    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
    56 	is called.
    57 	*/
    58 	EProcessComplete,
    59 	/** 
    60 	Could not empty the source buffer because the destination buffer became full.
    61 
    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.
    70 	*/
    71 	EProcessIncomplete,
    72 
    73 	/**
    74 	Codec came across an end of data.
    75 
    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.
    79 	*/
    80 	EEndOfData,
    81 
    82 	/** 
    83 	Could not fill the destination buffer because the source buffer has been emptied 
    84 
    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()
    90 	method is called.
    91 	*/
    92 	EDstNotFilled,
    93 
    94 	/** 
    95 	An error occured.
    96 	
    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 
    99 	KErrCorrupt.
   100 	*/
   101 	EProcessError,
   102 
   103 	/**
   104 	@deprecated
   105 
   106 	As 'EFrameIncomplete' but also requests a call to GetNewDataPosition.
   107 	*/
   108 	EProcessIncompleteRepositionRequest,
   109 
   110 	/**
   111 	@deprecated
   112 
   113 	As 'EFrameComplete' but also requests a call to GetNewDataPosition.
   114 	*/
   115 	EProcessCompleteRepositionRequest
   116 	};
   117 
   118 	/** 
   119 	Overloaded operator to test equality.
   120 	
   121 	@param  aStatus
   122 	        The status to compare the result of the process function.
   123 
   124 	@return A boolean indicating if the two status codes are the same. ETrue if they are, EFalse
   125 	        otherwise.
   126 	*/
   127 	TBool operator==(const TCodecProcessResultStatus aStatus) const {return (iStatus == aStatus);}
   128 
   129 	/** 
   130 	Overloaded operator to test inequality.
   131 
   132 	@param  aStatus
   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, 
   135 	        EFalse otherwise.
   136 	*/
   137 	TBool operator!=(const TCodecProcessResultStatus aStatus) const {return (iStatus != aStatus);}
   138 
   139 	/**
   140 	The codec's processing status.
   141 
   142 	@see enum TCodecProcessResultStatus
   143 	*/
   144 	TCodecProcessResultStatus iStatus;
   145 
   146 	/** 
   147 	The number of source bytes processed.
   148 
   149 	The number of bytes of source data that have been processed.
   150 
   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.
   156 	*/
   157 	TUint iSrcBytesProcessed;
   158 
   159 	/** 
   160 	The number of bytes added to the destination buffer.
   161 
   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.
   167 	*/
   168 	TUint iDstBytesAdded;
   169 public:
   170 
   171 	/**
   172 	Default constructor.
   173 	*/
   174 	TCodecProcessResult()
   175 		:iStatus(EProcessError), iSrcBytesProcessed(0), iDstBytesAdded(0) {};
   176 private:
   177 	/**
   178 	This member is internal and not intended for use.
   179 	*/
   180 	TInt iReserved1;
   181 	TInt iReserved2;
   182 	TInt iReserved3;
   183 	};
   184 
   185 
   186 class TFourCC; //forward reference
   187 class CMMFBuffer; //forward reference
   188 
   189 /**
   190 @publishedAll
   191 @released
   192 
   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
   197 
   198 The codec can be instantiated in 3 different ways:
   199 
   200 1.	NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType).
   201 
   202 This instantiate a codec that can convert the aSrcDatatype to a aDstDataType.
   203 
   204 2.	NewL(const TFourCC& aSrcDatatype, const TFourCC& aDstDataType, const TDesC& aPreferredSupplier).
   205 
   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
   209 to themselves.
   210 
   211 3.	NewL(TUid aUid).
   212 
   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.
   215 
   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
   228 
   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.
   231 */
   232 class CMMFCodec  : public CBase
   233 {
   234 public:
   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);
   240 
   241 	static void SelectByPreference( RImplInfoPtrArray& aPlugInArray, const TDesC& aPreferredSupplier ) ;
   242 
   243 	inline virtual void ConfigureL(TUid aConfigType, const TDesC8& aConfigData);
   244 
   245 	/**
   246 	Codec reset.
   247 
   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.
   250 	*/
   251 	virtual void ResetL() {}
   252 	//Standardised destructor.
   253 	inline virtual ~CMMFCodec();
   254 
   255 
   256 	/**
   257 	Processes the data in the specified source buffer and writes the processed data to the specified 
   258 	destination buffer.
   259 
   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.
   266 
   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.
   275 
   276 	This is a virtual function that each derived class must implement.
   277 
   278 	@see enum TCodecProcessResult
   279 
   280 	@param  aSource
   281 	        The source buffer containing data to encode or decode.
   282 	@param  aDestination
   283 	        The destination buffer to hold the data after encoding or decoding.
   284 
   285 	@return The result of the processing.
   286 	*/
   287 	virtual TCodecProcessResult ProcessL(const CMMFBuffer& aSource, CMMFBuffer& aDestination) = 0;
   288 
   289 	/**
   290 	@internalComponent
   291 
   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.
   295 
   296 	@param	aExtensionId
   297 		Extension identifier.
   298 	@param	aExtPtr
   299 		Pointer to get the extension.
   300 	@return	If successful returns KErrNone otherwise KErrExtensionNotSupported.		
   301 	*/
   302 	TInt ExtensionInterface(TUint aExtensionId, TAny*& aExtPtr);
   303 
   304 private:
   305 	TUid iDtor_ID_Key;
   306 };
   307 
   308 /**
   309 Destructor.
   310 
   311 Destroys any variables then informs ECom that this specific instance of the interface has been
   312 destroyed.
   313 */
   314 inline CMMFCodec::~CMMFCodec()
   315 	{
   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);
   320 	}
   321 
   322 /**
   323 Sets codec configuration.
   324 
   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.
   329 
   330 @param  aConfigType
   331         The UID of the configuration data.
   332 @param  aConfigData
   333         The configuration information.
   334 */
   335 inline void CMMFCodec::ConfigureL(TUid /*aConfigType*/, const TDesC8& /*aConfigData*/)
   336 {
   337 	User::Leave(KErrNotSupported);
   338 }
   339 
   340 #endif
   341