1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mmf/server/mmfformat.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,1042 @@
1.4 +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __MMF_SERVER_FORMAT_H__
1.20 +#define __MMF_SERVER_FORMAT_H__
1.21 +
1.22 +#include <mmf/server/mmfdatasink.h>
1.23 +#include <mmf/server/mmfdatasource.h>
1.24 +#include <ecom/ecom.h>
1.25 +#include <mmfplugininterfaceuids.hrh>
1.26 +
1.27 +const TUint KMMFFormatDefaultFrameSize = 0x1000; //4K
1.28 +
1.29 +/**
1.30 +@publishedAll
1.31 +@released
1.32 +
1.33 +Base class from which source formats can be derived from. The intended usage is for controllers that can support more
1.34 +than one type of format. The class is an MDataSource as far as the data path is concerned but is an MDataSink to the clip
1.35 +that is the source of the actual data.
1.36 +
1.37 +All CMMFFormatDecode plugin DLLs must include interface_uid = KMmfUidPluginInterfaceFormatDecode in their .rss files.
1.38 +*/
1.39 +class CMMFFormatDecode : public CBase, public MDataSource, public MDataSink
1.40 + {
1.41 +public:
1.42 + // ECOM creation.
1.43 + IMPORT_C static CMMFFormatDecode* NewL( TUid aUid, MDataSource* aSource );
1.44 +
1.45 + IMPORT_C static CMMFFormatDecode* NewL( const TDesC& aFileName, MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
1.46 + IMPORT_C static CMMFFormatDecode* NewL( const TDesC8& aSourceHeader, MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
1.47 + IMPORT_C static CMMFFormatDecode* NewL( MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
1.48 +
1.49 + IMPORT_C static CMMFFormatDecode* NewL( const TDesC& aFileName, MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
1.50 + IMPORT_C static CMMFFormatDecode* NewL( const TDesC8& aSourceHeader, MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
1.51 + IMPORT_C static CMMFFormatDecode* NewL( MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
1.52 +
1.53 + /**
1.54 + Destructor.
1.55 + */
1.56 + virtual ~CMMFFormatDecode() {REComSession::DestroyedImplementation(iDtor_ID_Key);};
1.57 +
1.58 + /**
1.59 + Returns the ECom plugin UID of this format.
1.60 +
1.61 + @return The plugin UID.
1.62 + */
1.63 + TUid ImplementationUid() const {return iImplementationUid;}
1.64 +
1.65 + /**
1.66 + Gets the number of streams of the specified media type.
1.67 +
1.68 + This is a virtual function that each derived class must implement.
1.69 +
1.70 + @param aMediaType
1.71 + The UID of the media type, for example KUidMediaTypeAudio or KUidMediaTypeVideo.
1.72 +
1.73 + @return The number of streams of multimedia data in the format for the specified media type.
1.74 + For example, for a WAV or mp3 audio file this procedure would return 1 for a media
1.75 + type of audio and 0 for a media type of video. More complex multimedia formats (for
1.76 + example AVI and mp4) can support multiple streams of both video and audio.
1.77 + */
1.78 + virtual TUint Streams(TUid aMediaType) const = 0;
1.79 +
1.80 + /**
1.81 + Returns the time interval for one frame for the specified media type.
1.82 +
1.83 + This is a virtual function that each derived class must implement.
1.84 +
1.85 + In the case of video, a frame would usually be one frame of video. In the case of
1.86 + audio, a frame may correspond to a frame of audio, if the particular audio data type
1.87 + is framed eg mp3. There are two definitions of a frame. A format frame, which may
1.88 + consist of several frames of a particular framed audio data type. This may be the case,
1.89 + for example for GSM610 (a low quality audio data type used in telephony) where a frame
1.90 + is only 65 bytes large. In this case a format frame consists of several GSM610 data type
1.91 + frames as passing the data out 65 bytes at a time would be inefficient. In the case of
1.92 + non-framed data such as pcm, a frame can be an arbitrary size determined by the format plugin.
1.93 +
1.94 + @param aMediaType
1.95 + The media type id.
1.96 +
1.97 + @return The frame time interval
1.98 + */
1.99 + virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const = 0;
1.100 +
1.101 +
1.102 + /**
1.103 + Returns the duration of the clip for the specified media type.
1.104 +
1.105 + This is a virtual function that each derived class must implement.
1.106 +
1.107 + @param aMediaType
1.108 + The media type ID.
1.109 +
1.110 + @return The duration of the clip.
1.111 + */
1.112 + virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const = 0;
1.113 +
1.114 + /**
1.115 + Request from CMMFDataPath to fill the specified buffer.
1.116 + The CMMFFormat needs to break this down into one or more reads from the clip
1.117 + (from MDataSource - CMMFFormatDecode is a MDataSource to a CMMFDataPath consumer).
1.118 +
1.119 + This is a virtual function that each derived class must implement.
1.120 +
1.121 + This method is the means by which data is obtained from the data source. aBuffer is
1.122 + the buffer that needs filling from the source data stream as identified by aMediaId. The
1.123 + format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber()
1.124 + method. From this the format should be able to determine the actual position of the data on
1.125 + the data source. The technique here depends on the nature of the format. For a linear audio
1.126 + format, the position can be obtained by a simple calculation of the frame size, the header size
1.127 + and where appropriate the datatype.
1.128 +
1.129 + For non-linear formats either an index table of frame number and location will need to be
1.130 + created in the NewL() or some form of approximating algorithm will be required. Some formats have
1.131 + an index table as part of the format e.g. AVI. If no random access is required then no index table
1.132 + is required, the format can keep track of the current read position and increment it on each access,
1.133 + and reset it if the frame number is reset to 0 or 1. Given that for non-linear i.e. variable bit rate
1.134 + formats, the size of the data read may vary from frame to frame, then the format should either set
1.135 + the request size of the buffer for the required frame or call the source's ReadBufferL() (either
1.136 + CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or CMMFFile::ReadBufferL()) function that
1.137 + takes the aLength parameter.
1.138 +
1.139 + It is the responsibility of the format decode to determine the size and position of the source data
1.140 + for each frame. For linear audio formats, the format decode should fill the buffer up to its maximum
1.141 + length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively acting as a demultiplexor,
1.142 + and must obtain the appropriate data from the source depending on the aMediaId.
1.143 +
1.144 + @param aBuffer
1.145 + The buffer to fill.
1.146 + @param aConsumer
1.147 + The consumer.
1.148 + @param aMediaId
1.149 + The media type ID.
1.150 + */
1.151 + virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer, TMediaId aMediaId)=0;
1.152 +
1.153 + /**
1.154 + @internalAll
1.155 +
1.156 + Indicates data has been added to the file.
1.157 +
1.158 + @param aBuffer
1.159 + The emptied buffer.
1.160 + */
1.161 + inline virtual void BufferEmptiedL(CMMFBuffer* aBuffer);
1.162 +
1.163 + /**
1.164 + Tests whether a source buffer can be created.
1.165 +
1.166 + The format knows what type of source buffer it requires so default returns ETrue.
1.167 + It doesn't usually need to set the size of this buffer.
1.168 +
1.169 + @return A boolean indicating whether a buffer can be created. ETrue if the buffer can be created,
1.170 + EFalse otherwise.
1.171 + */
1.172 + virtual TBool CanCreateSourceBuffer() {return ETrue;}
1.173 +
1.174 + /**
1.175 + Creates a source buffer.
1.176 +
1.177 + This is a virtual function that each derived class must implement.
1.178 +
1.179 + This function should create a buffer of length 0, the maximum length should be equal to the maximum
1.180 + possible frame size. In the case of non framed data it should be set to an arbitrary size, which is
1.181 + effectively a trade off between being too small which will affect performance as more source reads
1.182 + are required, and being too large which will give very coarse positioning granularity. For pcm data,
1.183 + a buffer size of 4K is a good compromise. The same compromise also applies when deciding to put multiple
1.184 + audio frames into one format frame. The sink buffer size may also effect the format buffer size and
1.185 + the controller may use this to suggest a buffer size to the format by calling the format's SuggestSourceBufferSize()
1.186 + method. Alternatively the MDataSource::CreateSourceBufferL() function that takes the additional aSinkBuffer
1.187 + parameter may also be used when deciding the source buffer maximum size of the created source buffer.
1.188 +
1.189 + @param aMediaId
1.190 + The media type ID.
1.191 + @param aReference
1.192 + If ETrue the MDataSource owns the buffer. If EFalse, then the caller owns the buffer. This
1.193 + should normally be set to EFalse as format plugins do not create the reference buffer.
1.194 +
1.195 + @return The created source buffer.
1.196 + */
1.197 + virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference)=0;
1.198 +
1.199 + /**
1.200 + Returns the source data type code for the specified media type ID.
1.201 +
1.202 + Used by the CMMFDataPath for codec matching.
1.203 +
1.204 + This is a virtual function that each derived class must implement.
1.205 +
1.206 + @param aMediaId
1.207 + The media type ID.
1.208 +
1.209 + @return The source data type code.
1.210 + */
1.211 + virtual TFourCC SourceDataTypeCode(TMediaId aMediaId)=0;
1.212 +
1.213 + /**
1.214 + @internalAll
1.215 +
1.216 + Adds a buffer to a clip.
1.217 +
1.218 + @param aBuffer
1.219 + The buffer to which the clip is added.
1.220 + @param aSupplier
1.221 + The data source.
1.222 + @param aMediaId
1.223 + The Media ID.
1.224 + */
1.225 + inline virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId);
1.226 +
1.227 + /**
1.228 + Indicates the data source has filled the buffer.
1.229 +
1.230 + Called by the CMMFFormat's MDataSource when it has filled the buffer.
1.231 + The default implementation below would need overriding in cases where multiple
1.232 + clip reads were required to fill the buffer from the data path.
1.233 +
1.234 + @param aBuffer
1.235 + The buffer to which the clip is added.
1.236 + */
1.237 + virtual void BufferFilledL(CMMFBuffer* aBuffer) {iDataPath->BufferFilledL(aBuffer);}
1.238 +
1.239 + /**
1.240 + Tests whether a sink buffer can be created.
1.241 +
1.242 + Format would normally pass its own buffer onto the CMMFClip, so
1.243 + this may not be required. The default returns EFalse.
1.244 +
1.245 + @return A boolean indicating if the sink buffer can be created. ETrue if buffer can be created, EFalse otherwise.
1.246 + */
1.247 + virtual TBool CanCreateSinkBuffer() {return EFalse;}
1.248 +
1.249 + /**
1.250 + Creates a sink buffer for the specified media ID. The default version returns NULL.
1.251 +
1.252 + @param aMediaId
1.253 + The media type ID.
1.254 + @param aReference
1.255 + If ETrue the MDataSink owns the buffer.
1.256 + If EFalse, then the caller owns the buffer.
1.257 + @return The CMMFBuffer sink buffer.
1.258 + */
1.259 + inline virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference);
1.260 +
1.261 + /**
1.262 + Returns the sink data type code for the specified media type ID.
1.263 + This would be the same as the source data type four CC although
1.264 + the clip is not going to need this info.
1.265 +
1.266 + @param aMediaId
1.267 + The media type id.
1.268 +
1.269 + @return The sink data type code.
1.270 + */
1.271 + inline virtual TFourCC SinkDataTypeCode(TMediaId aMediaId);
1.272 +
1.273 + /**
1.274 + Gets the number of meta data entries.
1.275 +
1.276 + Meta Data support. The decode format is only capable of reading meta data entries from the clip.
1.277 +
1.278 + This is an optional method, used to return the number of meta data entries present in the format.
1.279 + A meta data entry is a format-specific field such as authorship, copyright, security details etc.
1.280 + The function is optional as many formats do not provide support for such additional meta data fields.
1.281 +
1.282 + The default leaves with KErrNotSupported.
1.283 +
1.284 + @param aNumberOfEntries
1.285 + A reference to the number of meta data entries supported by the format. On return, contains
1.286 + the number of meta data entries.
1.287 + */
1.288 + inline virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries);
1.289 +
1.290 + /**
1.291 + Returns the specified meta data entry.
1.292 +
1.293 + This method is optional as many formats do not provide support for such additional meta data fields.
1.294 +
1.295 + The default leaves with KErrNotSupported.
1.296 +
1.297 + @param aIndex
1.298 + The zero based meta data entry index to retrieve.
1.299 +
1.300 + @return The meta data entry.
1.301 + */
1.302 + inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);
1.303 +
1.304 + //audio format methods
1.305 +
1.306 + /**
1.307 + Sets the number of channels.
1.308 +
1.309 + The default returns KErrNotSupported.
1.310 +
1.311 + There would normally be no need to override this function as the format decode plugin can normally
1.312 + determine for itself the number of channels. It is only necessary to override this in cases where the
1.313 + format decode plugin cannot determine for itself the number of channels. This function should not be
1.314 + used if the audio clip already exists; that is, in the "Open and Append" scenario, when the function's
1.315 + behaviour is undefined.
1.316 +
1.317 + @param aChannels
1.318 + The number of channels.
1.319 +
1.320 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.321 + another of the system-wide error codes.
1.322 + */
1.323 + inline virtual TInt SetNumChannels(TUint aChannels);
1.324 +
1.325 + /**
1.326 + Sets the sample rate.
1.327 +
1.328 + The default implementation returns KErrNotSupported.
1.329 +
1.330 + There would normally be no need to override this function as the format decode can normally determine
1.331 + the sample rate for itself. It is only necessary to override this in cases where the format decode plugin
1.332 + cannot determine for itself the sample rate.
1.333 +
1.334 + @param aSampleRate
1.335 + The sample rate.
1.336 +
1.337 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.338 + another of the system-wide error codes.
1.339 + */
1.340 + inline virtual TInt SetSampleRate(TUint aSampleRate);
1.341 +
1.342 + /**
1.343 + Sets the bit rate.
1.344 +
1.345 + The default implementation returns KErrNotSupported.
1.346 +
1.347 + This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate can
1.348 + not be directly calculated from the sample rate. There would normally be no need to override this
1.349 + function as the format decode can normally determine the sample rate for itself. It is only necessary
1.350 + to override this in cases where the format decode plugin cannot determine for itself the sample rate.
1.351 +
1.352 + @param aBitRate
1.353 + The bit rate in bits per second.
1.354 +
1.355 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.356 + another of the system-wide error codes.
1.357 + */
1.358 + inline virtual TInt SetBitRate(TUint aBitRate);
1.359 +
1.360 + /**
1.361 + Returns the number of channels.
1.362 +
1.363 + The default implementation returns 0.
1.364 +
1.365 + @return The number of channels.
1.366 + */
1.367 + virtual TUint NumChannels() {return 0;}
1.368 +
1.369 + /**
1.370 + Gets the sample rate.
1.371 +
1.372 + The default implementation returns 0.
1.373 +
1.374 + @return The sample rate.
1.375 + */
1.376 + virtual TUint SampleRate() {return 0;}
1.377 +
1.378 + /**
1.379 + Gets the bit rate.
1.380 +
1.381 + The default implementation returns 0.
1.382 +
1.383 + This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate
1.384 + can not be directly calculated from the sample rate. This function needs overriding for any format
1.385 + decode that supports audio.
1.386 +
1.387 + @return The bit rate.
1.388 + */
1.389 + virtual TUint BitRate() {return 0;}
1.390 +
1.391 + /**
1.392 + Gets the supported sample rates.
1.393 +
1.394 + The default implementation leaves with KErrNotSupported.
1.395 +
1.396 + This should return an array of sample rates supported by the format where applicable. Note
1.397 + that this refers to the possible sample rates supported by the format, not the actual sample rate,
1.398 + which will be one of the supported sample rates. The implementation of this function is optional.
1.399 +
1.400 + @param aSampleRates
1.401 + Reference to an array of supported sample rates.
1.402 + */
1.403 + inline virtual void GetSupportedSampleRatesL(RArray<TUint>& aSampleRates);
1.404 +
1.405 + /**
1.406 + Gets the supported bit rates.
1.407 +
1.408 + The default leaves with KErrNotSupported.
1.409 +
1.410 + This should return an array of bit rates supported by the format where applicable. Note that this
1.411 + refers to the possible bit rates supported by the format, not the actual bit rate, which will be
1.412 + one of the supported bit rates. The implementation of this function is optional.
1.413 +
1.414 + @param aBitRates
1.415 + Reference to an array of supported bit rates.
1.416 + */
1.417 + inline virtual void GetSupportedBitRatesL(RArray<TUint>& aBitRates);
1.418 +
1.419 + /**
1.420 + Gets the supported number of channels.
1.421 +
1.422 + The default leaves with KErrNotSupported.
1.423 +
1.424 + The implementation of this procedure should return an array of channels supported by the format
1.425 + where applicable. Note that this refers to the possible number of channels supported by the format,
1.426 + not the actual number of channels, which will be one of the supported channels. For example, for a
1.427 + format decode plugin capable of supporting mono and stereo the procedure would return an array of
1.428 + length two the first array member containing the value 1 and the second containing the value 2. The
1.429 + implementation of this function is optional.
1.430 +
1.431 + @param aNumChannels
1.432 + A reference to an array of supported number of channels.
1.433 + */
1.434 + inline virtual void GetSupportedNumChannelsL(RArray<TUint>& aNumChannels);
1.435 +
1.436 + /**
1.437 + Gets the supported data types for the given media type id.
1.438 +
1.439 + The default leaves with KErrNotSupported.
1.440 +
1.441 + The implementation of this procedure should return an array of data types supported by the format where
1.442 + applicable. Note that this refers to the possible data types that may be supported by the format, not the
1.443 + actual data type of the format, which will be one of the supported data types. For example, for a format
1.444 + decode plugin capable of supporting pcm16 and GSM610 the procedure would return an array of length two the
1.445 + first array member containing the fourCC code ' P16' and the second containing the value GSM6. The
1.446 + implementation of this function is optional.
1.447 +
1.448 + @param aMediaId
1.449 + The media type id.
1.450 + @param aDataTypes
1.451 + A reference to an array of supported data types.
1.452 + */
1.453 + inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray<TFourCC>& aDataTypes);
1.454 +
1.455 + /**
1.456 + Used by the sink to suggest a source buffer size.
1.457 +
1.458 + This is an optional function provided so that a controller can suggest a buffer
1.459 + size for the format. The controller should not assume that the format will accept
1.460 + the suggested buffer size and there is no obligation on behalf of the format to
1.461 + use the suggested buffer size.
1.462 +
1.463 + @param aSuggestedBufferSize
1.464 + A recommended buffer size that the format should create.
1.465 + */
1.466 + inline virtual void SuggestSourceBufferSize(TUint aSuggestedBufferSize);
1.467 +
1.468 + /**
1.469 + Used to set the format's position.
1.470 +
1.471 + Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this
1.472 + setting to determine what data to provide.
1.473 +
1.474 + The actual position the format sets itself may vary from this setting to ensure
1.475 + that it is aligned to the sample boundaries ensuring consistent data output.
1.476 +
1.477 + If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer
1.478 +
1.479 + @param aPosition
1.480 + The position the format should use.
1.481 + */
1.482 + inline virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition);
1.483 +
1.484 +
1.485 + /**
1.486 + Supplies the current position.
1.487 +
1.488 + Subsequent data reads will commence from this position.
1.489 +
1.490 + @return The current position in microseconds.
1.491 + */
1.492 + virtual TTimeIntervalMicroSeconds PositionL() {User::Leave(KErrNotSupported);return TTimeIntervalMicroSeconds(0);}
1.493 +
1.494 +protected:
1.495 + //ConstructSourceL should never be called. The CMMFFormatDecode NewL functions should
1.496 + //always be used to instantiate a CMMFFormatDecode object (not MDataSource::NewL)
1.497 + /**
1.498 + @internalAll
1.499 + */
1.500 + virtual void ConstructSourceL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
1.501 +
1.502 + //ConstructSinkL should never be called. The CMMFFormatDecode NewL functions should
1.503 + //always be used to instantiate a CMMFFormatDecode object (not MDataSink::NewL)
1.504 + /**
1.505 + @internalAll
1.506 + */
1.507 + virtual void ConstructSinkL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
1.508 +
1.509 + /**
1.510 + Default constructor
1.511 + */
1.512 + CMMFFormatDecode() : MDataSource(KUidMmfFormatDecode), MDataSink(KUidMmfFormatDecode) {};
1.513 +
1.514 + // Creates and initialises format plugin.
1.515 + static CMMFFormatDecode* CreateFormatL(TUid aImplementationUid, MDataSource* aSource);
1.516 +protected:
1.517 +
1.518 + /**
1.519 + The clip is the source for the decode format.
1.520 + */
1.521 + MDataSource* iClip;
1.522 +
1.523 + /**
1.524 + The data path is the sink for the decode format.
1.525 + */
1.526 + MDataSink* iDataPath;
1.527 +private:
1.528 + TUid iDtor_ID_Key; // do not move - referenced inline in ~CMMFFormatDecode()
1.529 + TUid iImplementationUid; // do not move - referenced inline in ImplementationUid()
1.530 + };
1.531 +
1.532 +
1.533 +/**
1.534 +Extension class to allow derived classes to support custom interfaces
1.535 +
1.536 +@publishedPartner
1.537 +@prototype
1.538 +*/
1.539 +
1.540 +class CMMFFormatDecode2 : public CMMFFormatDecode
1.541 + {
1.542 +public:
1.543 + /**
1.544 + Gets a custom interface.
1.545 +
1.546 + @param aInterfaceId
1.547 + The Uid of the particular interface required.
1.548 +
1.549 + @return Custom interface pointer. NULL if the requested interface is not supported.
1.550 + */
1.551 + virtual TAny* CustomInterface(TUid aInterfaceId)=0;
1.552 + };
1.553 +
1.554 +
1.555 +/**
1.556 +@publishedAll
1.557 +@released
1.558 +
1.559 +Base class from which sink formats can be derived from.
1.560 +
1.561 +The intended usage is for controllers that can support more than one type of format.
1.562 +The class is an MDataSink as far as the data path is concerned but is an MDataSource to the clip
1.563 +that is the sink of the actual data. All CMMFFormatEncode plugin DLLs must include
1.564 +interface_uid = KMmfUidPluginInterfaceFormatEncode in their .rss files.
1.565 +*/
1.566 +class CMMFFormatEncode : public CBase, public MDataSource, public MDataSink
1.567 + {
1.568 +public:
1.569 + // ECOM creation.
1.570 + IMPORT_C static CMMFFormatEncode* NewL( TUid aUid, MDataSink* aSink );
1.571 + IMPORT_C static CMMFFormatEncode* NewL( const TDesC& aFileName, MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
1.572 + IMPORT_C static CMMFFormatEncode* NewL( const TDesC8& aSourceHeader, MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
1.573 + IMPORT_C static CMMFFormatEncode* NewL( MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
1.574 +
1.575 + /**
1.576 + Destructor.
1.577 + */
1.578 + virtual ~CMMFFormatEncode() {REComSession::DestroyedImplementation(iDtor_ID_Key);}
1.579 +
1.580 + // returns ECOM plugin uid of this format
1.581 + /**
1.582 + Gets the ECom plugin UID of this format.
1.583 +
1.584 + @return The plugin UID.
1.585 + */
1.586 + TUid ImplementationUid() const {return iImplementationUid;}
1.587 +
1.588 + /**
1.589 + Returns the time interval for one frame for the specified media type.
1.590 +
1.591 + This is a virtual function that each derived class must implement.
1.592 +
1.593 + @param aMediaType
1.594 + The media type ID.
1.595 + @return The frame time interval in microseconds.
1.596 + */
1.597 + virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const = 0;
1.598 +
1.599 + /**
1.600 + Returns the duration of the sink clip for the specified media type.
1.601 +
1.602 + This is a virtual function that each derived class must implement.
1.603 +
1.604 + @param aMediaType
1.605 + The media type ID.
1.606 +
1.607 + @return The duration of the sink clip.
1.608 + */
1.609 + virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const = 0;
1.610 +
1.611 + /**
1.612 + @internalAll
1.613 +
1.614 + Request from CMMFDataPath to fill the specified buffer.
1.615 +
1.616 + @param aBuffer
1.617 + The buffer to fill.
1.618 + @param aConsumer
1.619 + The consumer.
1.620 + @param aMediaId
1.621 + The media ID.
1.622 + */
1.623 + inline virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer, TMediaId aMediaId);
1.624 +
1.625 + /**
1.626 + Called by the clip when it has added the data to the file.
1.627 +
1.628 + @param aBuffer
1.629 + The emptied buffer.
1.630 + */
1.631 + virtual void BufferEmptiedL(CMMFBuffer* aBuffer) {iDataPath->BufferEmptiedL(aBuffer);}
1.632 +
1.633 + /**
1.634 + Tests whether a source buffer can be created.
1.635 +
1.636 + The default implementation returns EFalse.
1.637 +
1.638 + @return A boolean indicating if the buffer can be created. ETrue if buffer can be created, EFalse otherwise.
1.639 + */
1.640 + virtual TBool CanCreateSourceBuffer() {return EFalse;}
1.641 +
1.642 + /**
1.643 + Creates a source buffer. The default returns NULL.
1.644 +
1.645 + @param aMediaId
1.646 + The media type id.
1.647 + @param aReference
1.648 + If ETrue the MDataSource owns the buffer.
1.649 + If EFalse, then the caller owns the buffer.
1.650 +
1.651 + @return Source buffer.
1.652 + */
1.653 + inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference);
1.654 +
1.655 + /**
1.656 + Returns the source data type code for the specified media type ID.
1.657 +
1.658 + This is a virtual function that each derived class must implement.
1.659 +
1.660 + @param aMediaId
1.661 + The media type id.
1.662 +
1.663 + @return The source data type code.
1.664 + */
1.665 + inline virtual TFourCC SourceDataTypeCode(TMediaId aMediaId);
1.666 +
1.667 + /**
1.668 + Adds a buffer to a clip.
1.669 +
1.670 + Called by CMMFDataPath.
1.671 + (from MDataSink - CMMFFormatEncode is a MDataSink to a CMMFDataPath)
1.672 +
1.673 + This is a virtual function that each derived class must implement.
1.674 +
1.675 + @param aBuffer
1.676 + The buffer to which the clip is added.
1.677 + @param aSupplier
1.678 + The data source.
1.679 + @param aMediaId
1.680 + The media type ID.
1.681 + */
1.682 + virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0;
1.683 +
1.684 + /**
1.685 + @internalAll
1.686 +
1.687 + Called by the CMMFDataPath's MDataSource when it has filled the buffer.
1.688 +
1.689 + @param aBuffer
1.690 + The buffer that has been filled.
1.691 + */
1.692 + inline virtual void BufferFilledL(CMMFBuffer* aBuffer);
1.693 +
1.694 + /**
1.695 + Tests whether a sink buffer can be created.
1.696 +
1.697 + Format would normally pass its own buffer onto the CMMFClip, so
1.698 + this may not be required. The default returns ETrue.
1.699 +
1.700 + @return A boolean indicating if the buffer can be created. ETrue if buffer can be created, EFalse otherwise.
1.701 + */
1.702 + virtual TBool CanCreateSinkBuffer() {return ETrue;}
1.703 +
1.704 + /**
1.705 + Creates a sink buffer for the specified media ID.
1.706 +
1.707 + This is a virtual function that each derived class must implement.
1.708 +
1.709 + @param aMediaId
1.710 + The media type ID.
1.711 + @param aReference
1.712 + If ETrue then MDataSink owns the buffer.
1.713 + If EFalse, then the caller owns the buffer.
1.714 +
1.715 + @return A pointer to the CMMFBuffer sink buffer.
1.716 + */
1.717 + virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0;
1.718 +
1.719 + /**
1.720 + Returns the sink data type code for the specified media type ID.
1.721 +
1.722 + This would be the same as the source data type four CC although the clip
1.723 + is not going to need this info.
1.724 +
1.725 + This is a virtual function that each derived class must implement.
1.726 +
1.727 + @param aMediaId
1.728 + The media type ID.
1.729 +
1.730 + @return The sink data type code.
1.731 + */
1.732 + virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0;
1.733 +
1.734 + /**
1.735 + This function is used to truncate the sink ie. a CMMFClip,
1.736 +
1.737 + If aToEnd = ETrue the sink is cropped from the aPosition to the end of the clip.
1.738 + If aToEnd = EFalse then the sink is cropped from the start of the clip to aPosition.
1.739 +
1.740 + This function would be called by the CMMFController. The default implementation leaves
1.741 + with KErrNotSupported.
1.742 +
1.743 + @param aPosition
1.744 + The position within the clip.
1.745 + @param aToEnd
1.746 + Flag to determine which part of the clip to delete.
1.747 + */
1.748 + inline virtual void CropL(TTimeIntervalMicroSeconds aPosition, TBool aToEnd = ETrue);
1.749 +
1.750 +
1.751 + /**
1.752 + Gets the number of meta data entries.
1.753 +
1.754 + The encode format is capable of reading and writing meta data to the clip.
1.755 +
1.756 + The default implementation leaves with KErrNotSupported.
1.757 +
1.758 + @param aNumberOfEntries
1.759 + On return, contains the number of meta data entries.
1.760 + */
1.761 + inline virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries);
1.762 +
1.763 + /**
1.764 + Returns the specified meta data entry.
1.765 +
1.766 + The default implementation leaves with KErrNotSupported.
1.767 +
1.768 + @param aIndex
1.769 + The zero based meta data entry index to retrieve.
1.770 +
1.771 + @return The meta data entry.
1.772 + */
1.773 + inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);
1.774 +
1.775 + /**
1.776 + Adds the specified meta data entry to the clip.
1.777 +
1.778 + The default implementation leaves with KErrNotSupported.
1.779 +
1.780 + @param aNewEntry
1.781 + The meta data entry to add.
1.782 + */
1.783 + inline virtual void AddMetaDataEntryL(const CMMFMetaDataEntry& aNewEntry);
1.784 +
1.785 + /**
1.786 + Removes the specified meta data entry.
1.787 +
1.788 + The default implementation returns KErrNotSupported.
1.789 +
1.790 + @param aIndex
1.791 + The zero based meta data entry index to remove.
1.792 +
1.793 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.794 + another of the system-wide error codes.
1.795 + */
1.796 + inline virtual TInt RemoveMetaDataEntry(TInt aIndex);
1.797 +
1.798 + /**
1.799 + Replaces the specified meta data entry with the entry supplied in aNewEntry.
1.800 +
1.801 + The default implementation leaves with KErrNotSupported.
1.802 +
1.803 + @param aIndex
1.804 + The zero based meta data entry index to replace.
1.805 + @param aNewEntry
1.806 + The meta data entry to replace.
1.807 + */
1.808 + inline virtual void ReplaceMetaDataEntryL(TInt aIndex, const CMMFMetaDataEntry& aNewEntry);
1.809 +
1.810 + //audio format methods
1.811 +
1.812 + /**
1.813 + Sets the number of channels.
1.814 +
1.815 + The default implementation returns KErrNotSupported.
1.816 +
1.817 + @param aChannels
1.818 + The number of channels.
1.819 +
1.820 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.821 + another of the system-wide error codes.
1.822 + */
1.823 + inline virtual TInt SetNumChannels(TUint aChannels);
1.824 +
1.825 + /**
1.826 + Sets the sample rate.
1.827 +
1.828 + The default implementation returns KErrNotSupported.
1.829 +
1.830 + @param aSampleRate
1.831 + The sample rate.
1.832 +
1.833 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.834 + another of the system-wide error codes.
1.835 + */
1.836 + inline virtual TInt SetSampleRate(TUint aSampleRate);
1.837 +
1.838 + /**
1.839 + Sets the bit rate.
1.840 +
1.841 + The default implementation returns KErrNotSupported.
1.842 +
1.843 + @param aBitRate
1.844 + The bit rate.
1.845 +
1.846 + @return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.847 + another of the system-wide error codes.
1.848 + */
1.849 + inline virtual TInt SetBitRate(TUint aBitRate);
1.850 +
1.851 + /**
1.852 + Returns the number of channels.
1.853 +
1.854 + The default implementation returns 0.
1.855 +
1.856 + @return The number of channels.
1.857 + */
1.858 + virtual TUint NumChannels() {return 0;}
1.859 +
1.860 + /**
1.861 + Returns the sample rate.
1.862 +
1.863 + The default implementation returns 0.
1.864 +
1.865 + @return The sample rate.
1.866 + */
1.867 + virtual TUint SampleRate() {return 0;}
1.868 +
1.869 + /**
1.870 + Returns the default sample rate.
1.871 +
1.872 + The default returns 0.
1.873 +
1.874 + @return The default sample rate.
1.875 + */
1.876 + virtual TUint GetDefaultSampleRate() {return 0;}
1.877 +
1.878 + /**
1.879 + Returns the bit rate.
1.880 +
1.881 + The default returns 0.
1.882 +
1.883 + @return The bit rate.
1.884 + */
1.885 + virtual TUint BitRate() {return 0;}
1.886 +
1.887 + /**
1.888 + Returns the bytes per second.
1.889 +
1.890 + The default returns 0.
1.891 +
1.892 + @return The bytes per second.
1.893 + */
1.894 + virtual TInt64 BytesPerSecond() {return 0;}
1.895 +
1.896 + /**
1.897 + Gets the supported sample rates.
1.898 +
1.899 + The default implementation leaves with KErrNotSupported.
1.900 +
1.901 + @param aSampleRates
1.902 + A reference to an array of supported sample rates.
1.903 + */
1.904 + inline virtual void GetSupportedSampleRatesL(RArray<TUint>& aSampleRates);
1.905 +
1.906 + /**
1.907 + Gets the supported bit rates.
1.908 +
1.909 + The default implementation leaves with KErrNotSupported.
1.910 +
1.911 + @param aBitRates
1.912 + A reference to an array of supported bit rates.
1.913 + */
1.914 + inline virtual void GetSupportedBitRatesL(RArray<TUint>& aBitRates);
1.915 +
1.916 + /**
1.917 + Gets the supported number of channels.
1.918 +
1.919 + The default implementation leaves with KErrNotSupported.
1.920 +
1.921 + @param aNumChannels
1.922 + A reference to an array of supported number of channels.
1.923 + */
1.924 + inline virtual void GetSupportedNumChannelsL(RArray<TUint>& aNumChannels);
1.925 +
1.926 + /**
1.927 + Gets the supported data types for the given media type ID.
1.928 +
1.929 + The default implementation leaves with KErrNotSupported.
1.930 +
1.931 + @param aMediaId
1.932 + The media type id.
1.933 + @param aDataTypes
1.934 + A reference to an array of supported data types.
1.935 + */
1.936 + inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray<TFourCC>& aDataTypes);
1.937 +
1.938 + /**
1.939 + Sets the maximum clip size.
1.940 +
1.941 + The default implementation leaves with KErrNotSupported.
1.942 +
1.943 + @param aBytes
1.944 + The maximum clip size.
1.945 + */
1.946 + inline virtual void SetMaximumClipSizeL(TInt aBytes);
1.947 +
1.948 + /**
1.949 + Returns the maximum clip size.
1.950 +
1.951 + The default returns 0.
1.952 +
1.953 + @return The maximum clip size.
1.954 + */
1.955 + virtual TInt MaximumClipSize() { return 0;}
1.956 +
1.957 + /**
1.958 + Used to set the format's position.
1.959 +
1.960 + Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this
1.961 + setting to determine what data to provide.
1.962 +
1.963 + The actual position the format sets itself may vary to this setting to ensure
1.964 + that it is aligned to the sample boundaries ensuring consistent data output.
1.965 +
1.966 + If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer
1.967 +
1.968 + @param aPosition
1.969 + The position the format should use.
1.970 + */
1.971 + inline virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition);
1.972 +
1.973 +
1.974 + /**
1.975 + Supplies the current position.
1.976 +
1.977 + Subsequent data reads will commence from this position.
1.978 +
1.979 + @return The current position in microseconds.
1.980 + */
1.981 + virtual TTimeIntervalMicroSeconds PositionL() {User::Leave(KErrNotSupported);return TTimeIntervalMicroSeconds(0);}
1.982 +
1.983 +
1.984 +protected:
1.985 + //ConstructSourceL should never be called. The CMMFFormatEncode NewL functions should
1.986 + //always be used to instantiate a CMMFFormatEncode object (not MDataSource::NewL)
1.987 + /**
1.988 + @internalAll
1.989 + */
1.990 + virtual void ConstructSourceL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
1.991 + //ConstructSinkL should never be called. The CMMFFormatEncode NewL functions should
1.992 + //always be used to instantiate a CMMFFormatEncode object (not MDataSink::NewL)
1.993 + /**
1.994 + @internalAll
1.995 + */
1.996 + virtual void ConstructSinkL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
1.997 +
1.998 + /**
1.999 + Default constructor
1.1000 + */
1.1001 + CMMFFormatEncode() : MDataSource(KUidMmfFormatEncode), MDataSink(KUidMmfFormatEncode) {};
1.1002 +
1.1003 + // Creates and initialises format plugin.
1.1004 + static CMMFFormatEncode* CreateFormatL(TUid aImplementationUid, MDataSink* aSink);
1.1005 +protected:
1.1006 +
1.1007 + /**
1.1008 + The Data path is the source for the encode format.
1.1009 + */
1.1010 + MDataSource* iDataPath;
1.1011 +
1.1012 + /**
1.1013 + The clip is the sink for the encode format.
1.1014 + */
1.1015 + MDataSink* iClip;
1.1016 +private:
1.1017 + TUid iDtor_ID_Key; // do not move - referenced inline in ~CMMFFormatDecode()
1.1018 + TUid iImplementationUid; // do not move - referenced inline in ImplementationUid()
1.1019 + };
1.1020 +
1.1021 +
1.1022 +class CMMFFormatPluginSelectionParameters;
1.1023 +
1.1024 +/**
1.1025 +@publishedAll
1.1026 +@released
1.1027 +
1.1028 +Provides an internal utility function to choose a format plugin from ECom.
1.1029 +*/
1.1030 +class MMFFormatEcomUtilities
1.1031 + {
1.1032 +public:
1.1033 + //Internal utility function to choose a format plugin from ECOM
1.1034 + static TUid SelectFormatPluginL(const CMMFFormatPluginSelectionParameters& aSelectParams);
1.1035 +
1.1036 + // Internal utility function to instantiate each format decode plugin in turn
1.1037 + // until we find one that works
1.1038 + static CMMFFormatDecode* SelectFormatDecodePluginL(const CMMFFormatPluginSelectionParameters& aSelectParams, MDataSource* aSource);
1.1039 +
1.1040 + static CMMFFormatDecode* SelectFormatDecodePluginL(const CMMFFormatPluginSelectionParameters& aSelectParams, MDataSource* aSource, TBool& aSupportsCustomInterfaces);
1.1041 + };
1.1042 +
1.1043 +#include "mmfformat.inl"
1.1044 +
1.1045 +#endif