test: epoc32/include/mmf/common/mmfcontroller.h@2fe1408b6811

     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    17 #ifndef __MMFCONTROLLER_H__

    18 #define __MMFCONTROLLER_H__

    20 #include <mmf/server/mmfdatasource.h>

    21 #include <mmf/server/mmfdatasink.h>

    22 #include <mmf/common/mmfcontrollerframework.h>

    23 #include <mmf/common/mmfcontrollerpluginresolver.h>

    24 #include <mmfplugininterfaceuids.hrh>

    26 #include <caf/caf.h>

    29 /**

    30 @publishedAll

    31 @released

    33 Error category denoting a general controller error.

    35 @see TMMFEvent

    36 @since 7.0s

    37 */

    38 const TUid KMMFErrorCategoryControllerGeneralError = {0x101F76D3};

    40 /**

    41 @publishedAll

    42 @released

    44 Error category denoting playback complete i.e. due to EOF or error condition

    46 @see TMMFEvent

    47 @since 7.0s

    48 */

    49 const TUid KMMFEventCategoryPlaybackComplete = {0x101f7ea0};

    51 /**

    52 @internalComponent

    53 */

    54 const TUid KUidInterfaceMMFDataSinkHolder = {0x101F76D4};

    55 /**

    56 @internalComponent

    57 */

    58 const TUid KUidInterfaceMMFDataSourceHolder = {0x101F76D5};

    59 /**

    60 @internalComponent

    61 */

    62 const TUid KUidMMFControllerExtendedDataHolder = {0x102834AC};

    64 /**

    65 @internalComponent

    67 Create a const TUid with the same values as the controller

    68 ECOM plugin interface UID

    69 */

    70 const TUid KUidInterfaceMMFController = {KMmfUidPluginInterfaceController};

    72 /**

    73 @internalComponent

    75 IPC messages for interface KUidInterfaceMMFController in the controller framework.

    76 */

    77 enum TMMFControllerMessages

    78 	{

    79 	EMMFControllerAddDataSource,

    80 	EMMFControllerAddDataSink,

    81 	EMMFControllerRemoveDataSource,

    82 	EMMFControllerRemoveDataSink,

    83 	EMMFControllerReset,

    84 	EMMFControllerPrime,

    85 	EMMFControllerPlay,

    86 	EMMFControllerPause,

    87 	EMMFControllerStop,

    88 	EMMFControllerGetPosition,

    89 	EMMFControllerSetPosition,

    90 	EMMFControllerGetDuration,

    91 	EMMFControllerGetNumberOfMetaDataEntries,

    92 	EMMFControllerGetSizeOfMetaDataEntry,//use internally

    93 	EMMFControllerGetMetaDataEntry,

    94 	EMMFControllerSetPrioritySettings,

    95 	EMMFControllerCancelAddDataSource,

    96 	EMMFControllerCancelAddDataSink,

    97 	EMMFControllerAddFileHandleDataSource,

    98 	EMMFControllerAddFileHandleDataSink,

    99 	EMMFControllerSourceSinkInitDataPreload,

   100 	EMMFControllerAddFileHandleDataSourceWithInitData,

   101 	EMMFControllerAddFileHandleDataSinkWithInitData

   102 	};

   106 /**

   107 @publishedAll

   108 @released

   110 Client representation of a controller plugin for the Multimedia Framework.

   112 This class allows a client to load a controller plugin into a new thread and access the

   113 functionality provided by that plugin.

   115 @since 7.0s

   116 */

   117 class RMMFController

   118 	{

   119 public:

   121 	IMPORT_C RMMFController();

   123 	IMPORT_C TInt Open(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings);

   125 	IMPORT_C TInt Open(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings);

   127 	IMPORT_C TInt Open(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap );

   129 	IMPORT_C TInt Open(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap );

   131 	IMPORT_C TInt OpenInSecureDRMProcess(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings);

   133 	IMPORT_C TInt OpenInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings);

   135 	IMPORT_C TInt OpenInSecureDRMProcess(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap );

   137 	IMPORT_C TInt OpenInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap );

   139 	IMPORT_C void Close();

   141 	IMPORT_C TInt SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings) const;

   143 	IMPORT_C TInt AddDataSource(TUid aSourceUid, const TDesC8& aSourceInitData);

   145 	IMPORT_C TInt AddDataSink(TUid aSinkUid, const TDesC8& aSinkInitData);

   147 	IMPORT_C TInt AddDataSource(TUid aSourceUid, const TDesC8& aSourceInitData, TMMFMessageDestination& aHandleInfo);

   149 	IMPORT_C TInt AddDataSink(TUid aSinkUid, const TDesC8& aSinkInitData, TMMFMessageDestination& aHandleInfo);

   151 	IMPORT_C void AddDataSource(const TMMFUidPckg& aSourceUid, const TDesC8& aSourceInitData, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);

   152 	IMPORT_C void AddFileHandleDataSource(const RFile& aFile, const TDesC8& aSourceInitData, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);

   153 	IMPORT_C void AddFileHandleDataSource(const RFile& aFile, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);

   155 	IMPORT_C void CancelAddDataSource();

   157 	IMPORT_C void AddDataSink(const TMMFUidPckg& aSinkUid, const TDesC8& aSinkInitData, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);

   158 	IMPORT_C void AddFileHandleDataSink(const RFile& aFile, const TDesC8& aSinkInitData, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);

   159 	IMPORT_C void AddFileHandleDataSink(const RFile& aFile, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);

   161 	IMPORT_C void CancelAddDataSink();

   163 	IMPORT_C TInt RemoveDataSource(const TMMFMessageDestination& aSourceHandleInfo);

   165 	IMPORT_C TInt RemoveDataSink(const TMMFMessageDestination& aSinkHandleInfo);

   167 	IMPORT_C TInt Reset();

   169 	IMPORT_C TInt Prime();

   171 	IMPORT_C TInt Play();

   173 	IMPORT_C TInt Pause();

   175 	IMPORT_C TInt Stop();

   177 	IMPORT_C TInt GetPosition(TTimeIntervalMicroSeconds& aPosition) const;

   179 	IMPORT_C TInt SetPosition(const TTimeIntervalMicroSeconds& aPosition) const;

   181 	IMPORT_C TInt GetDuration(TTimeIntervalMicroSeconds& aDuration) const;

   183 	IMPORT_C TInt GetNumberOfMetaDataEntries(TInt& aNumberOfEntries) const;

   185 	IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aIndex) const;

   187 	IMPORT_C TInt CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);

   189 	IMPORT_C TInt CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);

   191 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);

   193 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);

   195 	IMPORT_C void ReceiveEvents(TMMFEventPckg& aEventPckg, TRequestStatus& aStatus);

   197 	IMPORT_C TInt CancelReceiveEvents();

   199 	IMPORT_C TInt SetThreadPriority(const TThreadPriority& aPriority) const;

   201 private:

   202 	/**

   203 	The controller proxy.  Used to pass messages to the controller thread.

   204 	*/

   205 	RMMFControllerProxy iControllerProxy;

   207 	/**

   208 	Used to hold the destination information for messages for the standard controller plugin interface.

   209 	*/

   210 	TMMFMessageDestinationPckg iDestinationPckg;

   211 	};

   214 /**

   215 @publishedAll

   216 @released

   218 Defines an object to which a client may have a direct handle.

   220 This class provides a way of identifying objects within the controller framework, and a means

   221 of passing commands to those objects.

   223 @since  7.0s

   224 */

   225 class CMMFObject : public CBase

   226 	{

   227 friend class CMMFObjectContainer;//to set the handle

   228 public:

   229 	IMPORT_C ~CMMFObject();

   231 	IMPORT_C CMMFObject(TUid aInterfaceId);

   233 	IMPORT_C const TMMFMessageDestination& Handle();

   235 	IMPORT_C TBool operator==(const CMMFObject& aOther);

   237 	/**

   238 	Passes a message to the object to handle.

   240 	This is a pure virtual method to be implemented by concrete classes derived from this class.

   242 	The message passed in MUST be completed by the object; however, it can be copied to be

   243 	completed at a later time, should some other asynchronous action need to occur first.

   245 	@param  aMessage

   246 	        The message to be handled.  This MUST be completed by the object.

   248 	@since  7.0s

   249 	*/

   250 	virtual void HandleRequest(TMMFMessage& aMessage) = 0;

   251 private:

   252 	void SetHandle(const TMMFMessageDestination& aNewHandle);

   253 private:

   254 	TMMFMessageDestination iHandle;

   255 	};

   258 /**

   259 @publishedAll

   260 @released

   262 Container class to hold the CMMFObject-derived objects in the controller framework.

   264 @since 7.0s

   265 */

   266 class CMMFObjectContainer : public CBase

   267 	{

   268 public:

   270 	IMPORT_C CMMFObjectContainer();

   272 	IMPORT_C ~CMMFObjectContainer();

   274 	IMPORT_C TInt AddMMFObject(CMMFObject& aObject);

   276 	IMPORT_C void RemoveAndDestroyMMFObject(CMMFObject& aObject);

   278 	IMPORT_C TInt FindMMFObject(const TMMFMessageDestination& aObjectHandle, CMMFObject*& aObjectFound);

   280 	IMPORT_C void DeleteAllObjects();

   282 	const RPointerArray<CMMFObject>& MMFObjects();

   284 private:

   285 	/**

   286 	Internal method to find an object in the array.

   287 	*/

   288 	TInt FindMMFObject(const CMMFObject& aObject, TInt& aPositionInArray);

   290 	/**

   291 	Internal method used to generate the object handle for a newly added object.

   292 	*/

   293 	TInt GenerateObjectHandle();

   294 private:

   295 	/**

   296 	The array of objects.

   297 	*/

   298 	RPointerArray<CMMFObject> iObjects;

   300 	/**

   301 	The next available object handle.

   302 	*/

   303 	TInt iNextObjectHandle;

   304 	};

   307 /**

   308 @publishedAll

   309 @released

   311 CMMFObject-derived class to wrap a Data Source.

   313 Allows a handle to be attributed to a data source, so it can be removed from the controller and

   314 the client can send messages directly to it.

   316 @since 7.0s

   317 */

   318 class CMMFDataSourceHolder : public CMMFObject

   319 	{

   320 public:

   322 	IMPORT_C CMMFDataSourceHolder(MDataSource& aDataSource);

   324 	IMPORT_C ~CMMFDataSourceHolder();

   326 	IMPORT_C MDataSource& DataSource();

   328 	//from CMMFObject

   329 	IMPORT_C void HandleRequest(TMMFMessage& aMessage);

   330 private:

   331 	/**

   332 	Pointer to the data source owned by this object.

   333 	*/

   334 	MDataSource* iDataSource;

   335 	};

   337 /**

   338 @publishedAll

   339 @released

   341 CMMFObject-derived class to wrap a Data Sink.

   343 Allows a handle to be attributed to a data sink, so it can be removed from the controller and

   344 the client can send messages directly to it.

   346 @since 7.0s

   347 */

   348 class CMMFDataSinkHolder : public CMMFObject

   349 	{

   350 public:

   351 	IMPORT_C CMMFDataSinkHolder(MDataSink& aDataSink);

   353 	IMPORT_C ~CMMFDataSinkHolder();

   355 	IMPORT_C MDataSink& DataSink();

   357 	//from CMMFObject

   358 	IMPORT_C void HandleRequest(TMMFMessage& aMessage);

   360 private:

   361 	/**

   362 	Pointer to the data sink owned by this object.

   363 	*/

   364 	MDataSink* iDataSink;

   365 	};

   368 /**

   369 @publishedAll

   370 @released

   372 Base class for client-side custom command classes.

   374 In order facilitate the use of the more common custom commands, it is desirable to write

   375 a concrete API class for the client to use.  This API class can then be use to wrap all the code

   376 involved to formulate the custom command messages.

   378 @since 7.0s

   379 */

   380 class RMMFCustomCommandsBase

   381 	{

   382 public:

   384 	IMPORT_C RMMFCustomCommandsBase(RMMFController& aController, TUid aInterfaceId);

   385 protected:

   386 	/**

   387 	The controller.

   389 	Derived classes should use iController.CustomCommandSync() and

   390 	iController.CustomCommandAsync() to send the custom commands to the controller

   391 	plugin.

   392 	*/

   393 	RMMFController& iController;

   395 	/**

   396 	The destination package.

   398 	Derived classes must pass this into iController.CustomCommandSync() and

   399 	iController.CustomCommandAsync() as the destination argument.

   400 	*/

   401 	TMMFMessageDestinationPckg iDestinationPckg;

   402 	};

   404 /**

   405 @publishedAll

   406 @released

   408 Base class to define the interface of a custom command parser.

   410 In order to facilitate the support of common custom commands by controller plugins, a

   411 custom command parser object can be used.  A set of custom command parsers are created

   412 by the controller plugin (one for each interface supported), and added to the custom command

   413 parser manager in the controller framework.  The controller plugin must also derive from a set of

   414 concrete interfaces (provided in the form of mixin classes). Then, a custom command supported by

   415 one of the custom command parsers will appear to the controller as a concrete API call, rather than

   416 a call to its own custom command API.

   418 @since 7.0s

   419 */

   420 class CMMFCustomCommandParserBase : public CBase

   421 	{

   422 public:

   424 	/**

   425 	Pure virtual method to be implemented by derived classes.

   427 	Derived classes must implement the code to decode the message from the client.

   429 	@param  aMessage

   430 	        The message to be serviced. This message must be completed by the derived class.

   432 	@since 7.0s

   433 	*/

   434 	virtual void HandleRequest(TMMFMessage& aMessage) = 0;

   436 	/**

   437 	Returns the UID of the custom command interface provided by this parser.

   439 	@return The interface UID.

   441 	@since  7.0s

   442 	*/

   443 	IMPORT_C TUid InterfaceId();

   445 	/**

   446 	Destructor.

   448 	@since 7.0s

   449 	*/

   450 	IMPORT_C ~CMMFCustomCommandParserBase();

   451 protected:

   453 	/**

   454 	Constructor.

   456 	@param  aInterfaceId

   457 	        The uid of the custom command interface provided by this parser.

   458 	        This must be the same as the interface id of the corresponding client

   459 	        API class. See RMMFCustomCommandsBase.

   461 	@since  7.0s

   462 	*/

   463 	IMPORT_C CMMFCustomCommandParserBase(TUid aInterfaceId);

   465 private:

   467 	/**

   468 	The uid of the custom command interface provided by this parser.

   469 	*/

   470 	TUid iInterfaceId;

   471 	};

   473 /**

   474 @publishedPartner

   475 @released

   477 Class to manage custom command parsers.

   479 An object of this type is owned by the controller framework to contain all the custom command

   480 parsers for the controller plugin.

   482 @since 7.0s

   483 */

   484 class CMMFCustomCommandParserManager : public CBase

   485 	{

   486 public:

   487 	/**

   488 	Factory constructor.

   490 	@return A pointer to the newly created object.

   492 	@since 7.0s

   493 	*/

   494 	IMPORT_C static CMMFCustomCommandParserManager* NewL();

   496 	/**

   497 	Destructor.

   499 	Deletes all custom command parsers added to the manager.

   501 	@since 7.0s

   502 	*/

   503 	IMPORT_C ~CMMFCustomCommandParserManager();

   505 	/**

   506 	Attempts to find a custom command parser capable of handling the message.

   508 	@param  aMessage

   509             The message to be handled.

   511 	@return A boolean indicating in the message has been handled. ETrue if the message has been handled, EFalse

   512 	        if it has not.

   514 	@since 7.0s

   515 	*/

   516 	IMPORT_C TBool HandleRequest(TMMFMessage& aMessage);

   518 	/**

   519 	Adds a custom command parser to the manager.  The manager takes ownership of the parser.

   521 	Note:

   522 	This method will leave if it fails to add the parser. If it does leave, ownership

   523 	of the parser will remain with the caller.

   525 	@param  aParser

   526 	        A reference to the parser to be added to the manager.

   528 	@since 7.0s

   529 	*/

   530 	IMPORT_C void AddCustomCommandParserL(CMMFCustomCommandParserBase& aParser);

   531 private:

   532 	CMMFCustomCommandParserManager();

   533 private:

   534 	/**

   535 	The array of custom command parsers.

   536 	*/

   537 	RPointerArray<CMMFCustomCommandParserBase> iParsers;

   538 	};

   541 class CMMFControllerExtendedData;

   542 /**

   543 @publishedAll

   544 @released

   546 Base class for controller plugins.

   548 A controller plugin for the multimedia framework must derive from this class and implement

   549 all the pure virtual functions.

   551 Controller plugins control the flow of multimedia data from one or more sources to one or

   552 more sinks. For example, an audio controller plugin might take data from a file source and

   553 output it to a speaker sink, or take data from a microphone source and save it to a file

   554 sink. A controller plugin typically supports one or more multimedia formats, for example

   555 WAV or MPEG4.

   557 @since 7.0s

   558 */

   559 class CMMFController : public CBase

   560 	{

   561 public:

   563 	/**

   564 	Allocates and constructs a new controller plugin.

   566 	Uses ECOM to instantiate a new controller plugin. Can leave with any of the system-wide error codes.

   568 	@param  aControllerUid

   569 	        The unique ID of the controller to be instantiated from ECOM.

   570 	@param  aEventHandler

   571 	        A reference to an event handling object that can be used by the

   572 	        controller to send events back to the client.

   573 	@param 	aClientTid

   574 			The thread Id of the client thread

   576 	@return A pointer to the new controller plugin.

   578 	@since	7.0s

   579 	*/

   580 	static CMMFController* NewL(TUid aControllerUid, MAsyncEventHandler& aEventHandler, TThreadId aClientTid);

   582 	/**

   583 	Handles a message from the client.

   585 	Decodes the message and calls one of the private DoXxx methods to unpackaged the parameters.

   587 	@param  aMessage

   588 	        The message to be handled.

   590 	@since  7.0s

   591 	*/

   592 	IMPORT_C virtual void HandleRequestL(TMMFMessage& aMessage);

   594 	/**

   595 	Default destructor.

   596 	*/

   597 	IMPORT_C virtual ~CMMFController();

   598 protected:

   600 	/**

   601 	Constructor.

   602 	*/

   603 	CMMFController() {};

   605 	// virtual functions to be implemented by controller plugin

   607 	/**

   608 	Add a data source to the controller plugin.

   610 	NOTE: The data source is owned by the controller framework, NOT by the controller plugin.

   611 	Under no circumstances should the controller plugin delete the data source.

   613 	@param  aDataSource

   614 	        A reference to the data source to be added.  The controller plugin

   615 	        may call aDataSource.DataSourceType() to find out

   616 	        exactly what type of source it is.

   618 	@leave  KErrNotSupported

   619 	        If the controller plugin does not support the data source, it should leave with this.

   621 	@since  7.0s

   622 	*/

   623 	virtual void AddDataSourceL(MDataSource& aDataSource) = 0;

   625 	/**

   626 	Adds a data sink to the controller plugin.

   628 	NOTE: The data sink is owned by the controller framework, NOT by the controller plugin.

   629 	Under no circumstances should the controller plugin delete the data sink.

   631 	@param  aDataSink

   632 	        A reference to the data sink to be added.  The controller plugin

   633 	        may call aDatasink.DatasinkType() to find out

   634             exactly what type of sink it is.

   636 	@leave  KErrNotSupported

   637 	        If the controller plugin does not support the data sink, it should leave with this.

   639 	@since 7.0s

   640 	*/

   641 	virtual void AddDataSinkL(MDataSink& aDataSink) = 0;

   643 	/**

   644 	Removes a data source from the controller plugin.

   646 	Note:

   647 	The data source is owned by the controller framework, NOT by the controller plugin.

   648 	Under no circumstances should the controller plugin delete the data source.

   650 	@param  aDataSource

   651 	        A reference to the data source to be removed.

   653 	@leave  KErrNotSupported

   654 	        The controller plugin may leave during this method.  If the controller plugin does

   655 	        not support the removal of data sources, it should leave with

   656 	        KErrNotSupported. If the controller plugin leaves, the data source will

   657 	        not be destroyed by the controller framework.  If it does not leave, the data source

   658 	        will be destroyed.

   660 	@since 7.0s

   661 	*/

   662 	virtual void RemoveDataSourceL(MDataSource& aDataSource) = 0;

   664 	/**

   665 	Removes a data sink from the controller plugin.

   667 	Note:

   668 	The data sink is owned by the controller framework, NOT by the controller plugin.

   669 	Under no circumstances should the controller plugin delete the data sink.

   671 	@param  aDataSink

   672 	        A reference to the data sink to be removed.

   674 	@leave  KErrNotSupported

   675 	        The controller plugin may leave during this method.  If the controller plugin does

   676 	        not support the removal of data sinks, it should leave with

   677 	        KErrNotSupported. If the controller plugin leaves, the data sink will

   678 	        not be destroyed by the controller framework.  If it does not leave, the data sink

   679 	        will be destroyed.

   681 	@since  7.0s

   682 	*/

   683 	virtual void RemoveDataSinkL(MDataSink& aDataSink) = 0;

   685 	/**

   686 	Resets the controller plugin.

   688 	The controller should revert back to its newly constructed state. If the Reset is successful

   689 	(i.e. it doesn't leave), the controller framework will delete all objects added to the

   690 	MMFObjectManager including any sources and sinks.

   692 	@leave  KErrNotSupported

   693 	        If the controller plugin does not support being reset, it should leave with KErrNotSupported.

   695 	@since  7.0s

   696 	*/

   697 	virtual void ResetL() = 0;

   699 	/**

   700 	Primes the controller plugin.

   702 	The controller must prepare to start playing, by initialising its sources, sinks and buffers.

   703 	This moves the controller from the STOPPED to the PRIMED state.

   705 	@since  7.0s

   706 	*/

   707 	virtual void PrimeL() = 0;

   709 	/**

   710 	A partner to the PrimeL() method that is overridable to allow Asynchronous

   711 	completion in the controller whilst maintaining a Synchronous client API.

   713 	The default implementation of this is to call PrimeL() and complete the message with KErrNone.

   715 	@since  7.0s

   716 	*/

   717 	IMPORT_C virtual void PrimeL(TMMFMessage& aMessage);

   719 	/**

   720 	Commences playback.

   722 	The controller must now begin transferring data from its source(s) to its sink(s).

   723 	This moves the controller from the PRIMED to the PLAYING state.

   725 	Note:

   726 	This method must return once playing has commenced, and not wait until playing is complete.

   728 	@since  7.0s

   729 	*/

   730 	virtual void PlayL()= 0;

   732 	/**

   733 	A partner to the PlayL() method that is overridable to allow Asynchronous

   734 	completion in the controller whilst maintaining a Synchronous client API.

   736 	The default implementation of this is to call PlayL() and complete the message with KErrNone.

   738 	@since  7.0s

   739 	*/

   740 	IMPORT_C virtual void PlayL(TMMFMessage& aMessage);

   743 	/**

   744 	Pauses the controller plugin.

   746 	The controller must now cease transferring data from its source(s) to its sink(s).

   747 	This moves the controller from the PLAYING back to the PRIMED state.

   749 	A subsequent call to Play() will cause the controller plugin to resume playback

   750 	from the point it was paused (unless there has been a call to SetPosition() in

   751 	the meantime.

   753 	@since  7.0s

   754 	*/

   755 	virtual void PauseL()= 0;

   757 	/**

   758 	A partner to the PauseL() method that is overridable to allow Asynchronous

   759 	completion in the controller whilst maintaining a Synchronous client API.

   761 	The default implementation of this is to call PauseL() and complete the message with KErrNone.

   763 	@since  7.0s

   764 	*/

   765 	IMPORT_C virtual void PauseL(TMMFMessage& aMessage);

   767 	/**

   768 	Stops the controller plugin.

   770 	The controller must now undo anything that occurred during the call to Prime().

   771 	This moves the controller from the PRIMED back to the STOPPED state.

   773 	@since  7.0s

   774 	*/

   775 	virtual void StopL()= 0;

   777 	/**

   778 	A partner to the StopL() method that is overridable to allow Asynchronous

   779 	completion in the controller whilst maintaining a Synchronous client API.

   781 	The default implementation of this is to call StopL() and complete the message with KErrNone.

   783 	@since  7.0s

   784 	*/

   785 	IMPORT_C virtual void StopL(TMMFMessage& aMessage);

   787 	/**

   788 	Gets the current position.

   790 	The controller plugin should calculate the current position in microseconds.

   792 	@return The current position in microseconds.

   794 	@since  7.0s

   795 	*/

   796 	virtual TTimeIntervalMicroSeconds PositionL() const = 0;

   798 	/**

   799 	Sets the current position.

   801 	The controller plugin should reposition itself to the position provided.

   803 	@param  aPosition

   804 	        The desired position in microseconds.

   806 	@since  7.0s

   807 	*/

   808 	virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition) = 0;

   810 	/**

   811 	Gets the duration of the clip.

   813 	The controller plugin should calculate the clip duration in microseconds.

   815 	@return The clips duration in microseconds.

   817 	@since  7.0s

   818 	*/

   819 	virtual TTimeIntervalMicroSeconds DurationL() const = 0;

   821 	/**

   822 	Sets the priority settings.

   824 	The new priority settings must be applied to any resource being used by the controller

   825 	plugin that requires priority settings (for example the sound device).

   827 	@param  aPrioritySettings

   828 	        The new priority settings

   830 	@since  7.0s

   832 	@capability MultimediaDD

   833 	            A process requesting or using this method that has MultimediaDD capability will

   834 				always have precedence over a process that does not have MultimediaDD.

   835 	*/

   836 	virtual void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings) = 0;

   838 	/**

   839 	Handles a custom command.

   841 	Custom commands allow a controller plugin to define its own API.  If the controller framework

   842 	does not understand a message from the client, it is assumed this is a custom command for the

   843 	plugin and passed into this interface.

   845 	The more common custom commands can be handled by Custom Command Parsers on behalf of the

   846 	controller plugin.  This allows the controller plugin to implement a concrete interface

   847 	(defined by mixin classes) rather than having to decode the command itself.  For more

   848 	information, see CMMFCustomCommandParserBase.

   850 	The controller plugin must always complete the message passed into this method,

   851 	even if it does not support the interface required by the message.

   853 	@param  aMessage

   854 	        The message to be handled by the controller plugin.

   856     @see    CMMFCustomCommandParserBase.

   857 	@since 7.0s

   858 	*/

   859 	virtual void CustomCommand(TMMFMessage& aMessage)

   860 		{aMessage.Complete(KErrNotSupported);};//default implementation

   862 	/**

   863 	RetrieveS the number of meta data entries in the clip.

   865 	@param  aNumberOfEntries

   866 	        The controller plugin must set this to the number of meta data entries

   867 	        in the clip.

   869 	@since  7.0s

   870 	*/

   871 	virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries) = 0;

   873 	/**

   874 	Retrieves a meta data entry from the clip.

   876 	@param  aIndex

   877 	        The index of the meta data entry to retrieve.

   879 	@return A pointer to a newly created CMMFMetaDataEntry object containing the meta information.

   880 	        The controller framework will take ownership of the object when this method returns.

   882 	@since  7.0s

   883 	*/

   884 	virtual CMMFMetaDataEntry* GetMetaDataEntryL(TInt aIndex) = 0;

   886 	// Utility functions to be used by controller plugins

   888 	/**

   889 	Sends an event to the client.

   891 	The controller plugin can use this method to send an event to the client.

   893 	@param  aEvent

   894 	        The event to be sent to the client.

   895 	@return One of the system-wide error codes.

   897 	@since 7.0s

   898 	*/

   899 	IMPORT_C TInt DoSendEventToClient(const TMMFEvent& aEvent);

   901 	/**

   902 	Gets a reference to the multimedia framework object container.

   904 	The controller plugin may add CMMFObject-derived objects to the container to allow them

   905 	to receive messages directly from the client.

   907 	@return A reference to the MMFObjectContainer.

   909 	@since  7.0s

   910 	*/

   911 	IMPORT_C CMMFObjectContainer& MMFObjectContainerL();

   913 	/**

   914 	Adds a custom command parser to the controller framework.

   916 	If the controller framework receives a request it does not understand, it will

   917 	search through its list of custom command parsers before passing the request

   918 	on to the controller plugin as a custom command.

   920 	By using the custom command parsers, the controller plugin can implement a concrete

   921 	API rather than having to decode the common custom commands itself.

   923 	@param  aParser

   924 	        The parser to be added to the controller framework. The controller framework

   925 	        takes ownership of the parser if the call does not leave.

   927 	@since  7.0s

   928 	*/

   929 	IMPORT_C void AddCustomCommandParserL(CMMFCustomCommandParserBase& aParser);

   931 	/**

   932 	Retrieves the client thread Id of this controller.

   934 	@return Thread Id of the controller's client

   935 	*/

   936 	IMPORT_C TThreadId ClientThreadIdL();

   938 	/**

   939 	Check the Secure DRM Mode of current controller object

   941 	@return ETrue if the controller is running under Secure DRM mode; otherwise EFalse.

   942 	*/

   943 	IMPORT_C TBool IsSecureDrmModeL();

   945 private:

   946 	/**

   947 	This is internal and not intended for use.

   948 	*/

   949 	void ConstructL(MAsyncEventHandler& aEventHandler, TThreadId aClientTid);

   950 	// IPC decode functions

   951 	TBool DoAddDataSourceL(TMMFMessage& aMessage);

   952 	TBool DoAddDataSinkL(TMMFMessage& aMessage);

   953 	TBool DoAddFileHandleDataSourceL(TMMFMessage& aMessage);

   954 	TBool DoAddFileHandleDataSinkL(TMMFMessage& aMessage);

   955 	TBool DoRemoveDataSourceL(TMMFMessage& aMessage);

   956 	TBool DoRemoveDataSinkL(TMMFMessage& aMessage);

   957 	TBool DoResetL(TMMFMessage& aMessage);

   958 	TBool DoPrimeL(TMMFMessage& aMessage);

   959 	TBool DoPlayL(TMMFMessage& aMessage);

   960 	TBool DoPauseL(TMMFMessage& aMessage);

   961 	TBool DoStopL(TMMFMessage& aMessage);

   962 	TBool DoGetPositionL(TMMFMessage& aMessage);

   963 	TBool DoSetPositionL(TMMFMessage& aMessage);

   964 	TBool DoGetDurationL(TMMFMessage& aMessage);

   965 	TBool DoSetPrioritySettingsL(TMMFMessage& aMessage);

   966 	void DoCustomCommand(TMMFMessage& aMessage);

   967 	TBool DoGetNumberOfMetaDataEntriesL(TMMFMessage& aMessage);

   968 	TBool DoGetSizeOfMetaDataEntryL(TMMFMessage& aMessage);

   969 	TBool DoGetMetaDataEntryL(TMMFMessage& aMessage);

   970 	TBool DoPreloadSourceSinkInitDataL(TMMFMessage& aMessage);

   971 	TBool DoAddFileHandleDataSourceWithInitDataL(TMMFMessage& aMessage);

   972 	TBool DoAddFileHandleDataSinkWithInitDataL(TMMFMessage& aMessage);

   973 	void ReplaceFileHandleInInitDataL(RFile* aFile, TDes8& aInitData);

   974 	// Ownership of aSource is taken into this function

   975 	void AddMDataSourceAndRepondClientL(MDataSource* aSource, TMMFMessage& aMessage);

   976 	// Ownership of aSink is taken into this function

   977 	void AddMDataSinkAndRepondClientL(MDataSink* aSink, TMMFMessage& aMessage);

   978 	CMMFControllerExtendedData* GetExtendedDataL();

   979 	static CMMFControllerExtendedData* CreateExtendedDataL(TThreadId aClientTid);

   981 private:

   982 	/**

   983 	Buffer to assist copy of meta data over the thread boundary.

   984 	*/

   985 	CBufFlat* iMetaDataBuffer;

   987 	/**

   988 	Required by ECOM.

   989 	*/

   990 	TUid iDtor_ID_Key;

   992 	/**

   993 	The event handler for the controller plugin.

   994 	*/

   995 	MAsyncEventHandler* iAsyncEventHandler;

   997 	/**

   998 	The MMF object container.

   999 	*/

  1000 	CMMFObjectContainer* iMMFObjectContainer;

  1002 	/**

  1003 	The custom command parser manager.

  1004 	*/

  1005 	CMMFCustomCommandParserManager* iCustomCommandParserManager;

  1006 	};

  1010 /**

  1011 @publishedAll

  1012 @released

  1014 Mixin class that the user of the class CMMFControllerEventMonitor must derive from.

  1016 @since  7.0s

  1017 */

  1018 class MMMFControllerEventMonitorObserver

  1019 	{

  1020 public:

  1022 	/**

  1023 	Handles an event that has been generated.

  1025 	@param  aEvent

  1026 	        The event to be handled.

  1028 	@since  7.0s

  1029 	*/

  1030 	virtual void HandleEvent(const TMMFEvent& aEvent) = 0;

  1031 	};

  1033 /**

  1034 @publishedAll

  1035 @released

  1037 Active object utility class that can be used to monitor a controller plugin for events.

  1038 If an event occurs, the client will be notified via the MMMFControllerEventMonitorObserver interface.

  1040 @since 7.0s

  1041 */

  1042 class CMMFControllerEventMonitor : public CActive

  1043 	{

  1044 public:

  1046 	/**

  1047 	Constructs a controller event monitor object.

  1049 	@param  aObserver

  1050 	        A reference to the observer of the active object.  The observer will be

  1051 	        notified when an event occurs.

  1052 	@param  aMMFController

  1053 	        A reference to the client controller interface class.

  1055 	@return A pointer to the new event monitor.

  1057 	@since  7.0s

  1058 	*/

  1059 	IMPORT_C static CMMFControllerEventMonitor* NewL(MMMFControllerEventMonitorObserver& aObserver,

  1060 		RMMFController& aMMFController);

  1061 	/**

  1062 	Destructor.

  1063 	*/

  1064 	~CMMFControllerEventMonitor();

  1066 	/**

  1067 	Tells the controller event monitor to start listening for events.

  1069 	The controller plugin must have been opened before this method is called.

  1071 	@since  7.0s

  1072 	*/

  1073 	IMPORT_C void Start();

  1075 private:

  1076 	/**

  1077 	Calls HandleEvent on iObserver.

  1079 	This will not leave.

  1081 	@since  7.0s

  1082 	*/

  1083 	void RunL();

  1085 	/**

  1086 	Cancels the outstanding request on iMMFController.

  1088 	@since  7.0s

  1089 	*/

  1090 	void DoCancel();

  1092 	/**

  1093 	Constructs a controller event monitor object.

  1095 	@param  aObserver

  1096 	        A reference to the observer of the active object.  The observer will be

  1097 	        notified when an event occurs.

  1098 	@param  aMMFController

  1099 	        A reference to the client controller interface class.

  1101 	@since  7.0s

  1102 	*/

  1103 	CMMFControllerEventMonitor(MMMFControllerEventMonitorObserver& aObserver,

  1104 		RMMFController& aMMFController);

  1105 private:

  1106 	MMMFControllerEventMonitorObserver& iObserver;

  1107 	RMMFController& iMMFController;

  1108 	TMMFEventPckg iEventPckg;

  1109 	};

  1111 /**

  1112 Mixin class that the user of the class CMMFAddDataSourceSinkAsync must derive from.

  1113 @since 8.0

  1114 @publishedAll

  1115 @released

  1116 */

  1117 class MMMFAddDataSourceSinkAsyncObserver

  1118 	{

  1119 public:

  1120 /**

  1121 The request to add a data source or sink has completed.

  1122 @param	"aError"		"The error resulting from adding the source/sink."

  1123 @param  "aHandleInfo"	"This object identifies	the data source/sink inside the controller

  1124 						framework.  This allows the client to send custom commands directly to

  1125 						the data source/sink, and to also remove the data sink from the controller.

  1126 						Note that not all data sinks support custom commands, and not all

  1127 						controller plugins support the removal of a data sink."

  1128 */

  1129 	virtual void MadssaoAddDataSourceSinkAsyncComplete(TInt aError, const TMMFMessageDestination& aHandle) = 0;

  1130 	};

  1133 /**

  1134 Active object utility class that can be used to add a data source or data sink to a controller

  1135 plugin asynchronously.  Once the command has been completed, the caller will be notified via the

  1136 MMMFAddDataSourceSinkAsyncObserver interface.

  1137 @since 8.0

  1138 @publishedAll

  1139 @released

  1141 */

  1142 class CMMFAddDataSourceSinkAsync : public CActive

  1143 	{

  1144 public:

  1146 	IMPORT_C static CMMFAddDataSourceSinkAsync* NewL(MMMFAddDataSourceSinkAsyncObserver& aObs);

  1147     IMPORT_C void AddDataSource(RMMFController& aController, TUid aSourceUid, const TDesC8& aSourceInitData);

  1148 	IMPORT_C void AddFileHandleDataSource(RMMFController& aController, const RFile& aFile);

  1149 	IMPORT_C void AddFileHandleDataSource(RMMFController& aController, const RFile& aFile, const TDesC8& aSourceInitData);

  1150     IMPORT_C void AddDataSink(RMMFController& aController, TUid aSinkUid, const TDesC8& aSinkInitData);

  1151 	IMPORT_C void AddFileHandleDataSink(RMMFController& aController, const RFile& aFile);

  1152 	IMPORT_C void AddFileHandleDataSink(RMMFController& aController, const RFile& aFile, const TDesC8& aSinkInitData);

  1154 	~CMMFAddDataSourceSinkAsync();

  1156 private:

  1157 	void RunL();

  1158 	void DoCancel();

  1159 	CMMFAddDataSourceSinkAsync(MMMFAddDataSourceSinkAsyncObserver& aObserver);

  1160 private:

  1161 	enum TCurrentAction {EIdle, EAddingDataSource, EAddingDataSink};

  1162 private:

  1163 	MMMFAddDataSourceSinkAsyncObserver& iObserver;

  1164 	TMMFMessageDestinationPckg iHandleInfoPckg;

  1165 	TCurrentAction iCurrentAction;

  1166 	RMMFController* iMMFController;

  1167 	HBufC8* iSourceSinkInitData;

  1168 	TMMFUidPckg iSourceSinkUidPckg;

  1169 	};

  1171 /**

  1172 @internalComponent

  1174 The controller proxy session.

  1176 Only one session can be connected to a controller proxy server.

  1178 */

  1179 NONSHARABLE_CLASS(CMMFControllerExtendedData) : public CMMFObject

  1180 	{

  1181 public:

  1182 	CMMFControllerExtendedData();

  1184 	~CMMFControllerExtendedData();

  1186 	// Set/Get the source/sink initialization data used by CMMFController

  1187 	// Ownership of aSourceSinkInitData is transferred (NULL pointer is allow)

  1188 	// If source/sink initialization data is already set, previous one will be destroyed

  1189 	void SetSourceSinkInitData(HBufC8* aSourceSinkInitData);

  1190 	HBufC8* SourceSinkInitData() const;

  1191 	void ResetSourceSinkInitData();

  1193 	// Set/Get the client thread ID used by CMMFController

  1194 	void SetClientThreadId(TThreadId aClientThreadId);

  1195 	TThreadId ClientThreadId() const;

  1197 	// Set/Get the Secure DRM mode of CMMFController

  1198 	void SetSecureDrmMode(TBool aSecureDrmMode);

  1199 	TBool SecureDrmMode() const;

  1201 	//from CMMFObject

  1202 	void HandleRequest(TMMFMessage& aMessage);

  1203 private:

  1204 	/**

  1205 	Extended data uses by CMMFController: Source/Sink initialization data

  1206 	It serves as a temporary storage for Source/Sink initialization

  1207 	Client should request the server to use and cleanup this variable ASAP

  1208 	once it is being loaded

  1209 	*/

  1210 	HBufC8*	iSourceSinkInitData;

  1212 	/**

  1213 	Extended data uses by CMMFController: The client thread Id

  1214 	*/

  1215 	TThreadId iClientThreadId;

  1217 	/**

  1218 	Extended data uses by CMMFController: Controller Scecure DRM Mode

  1219 	*/

  1220 	TBool iSecureDrmMode;

  1221 	};

  1223 #endif

author	William Roberts <williamr@symbian.org>
	Tue, 16 Mar 2010 16:12:26 +0000
branch	Symbian2
changeset 2	2fe1408b6811
parent 0	061f57f2323e
child 4	837f303aceeb
permissions	-rw-r--r--