1 mmfcontroller.h

     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 //

    15 

    16 

    17 #ifndef __MMFCONTROLLER_H__

    18 #define __MMFCONTROLLER_H__

    19 

    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>

    25 

    26 #include <caf/caf.h>

    27 

    28 

    29 /**

    30 @publishedAll

    31 @released

    32 

    33 Error category denoting a general controller error.

    34 

    35 @see TMMFEvent

    36 @since 7.0s

    37 */

    38 const TUid KMMFErrorCategoryControllerGeneralError = {0x101F76D3};

    39 

    40 /**

    41 @publishedAll

    42 @released

    43 

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

    45 

    46 @see TMMFEvent

    47 @since 7.0s

    48 */

    49 const TUid KMMFEventCategoryPlaybackComplete = {0x101f7ea0};

    50 

    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};

    63 

    64 /**

    65 @internalComponent

    66 

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

    68 ECOM plugin interface UID

    69 */

    70 const TUid KUidInterfaceMMFController = {KMmfUidPluginInterfaceController};

    71 

    72 /**

    73 @internalComponent

    74 

    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 	};

   103 

   104 

   105 

   106 /**

   107 @publishedAll

   108 @released

   109 

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

   111 

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

   113 functionality provided by that plugin.

   114 

   115 @since 7.0s

   116 */

   117 class RMMFController

   118 	{

   119 public:

   120 

   121 	IMPORT_C RMMFController();

   122 

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

   124 

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

   126 

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

   128 

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

   130 	

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

   132 	

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

   134 

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

   136 

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

   138 	

   139 	IMPORT_C void Close();

   140 

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

   142 

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

   144 

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

   146 

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

   148 	

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

   150 

   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);

   154 	

   155 	IMPORT_C void CancelAddDataSource();

   156 	

   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);

   160 	

   161 	IMPORT_C void CancelAddDataSink();

   162 

   163 	IMPORT_C TInt RemoveDataSource(const TMMFMessageDestination& aSourceHandleInfo);

   164 

   165 	IMPORT_C TInt RemoveDataSink(const TMMFMessageDestination& aSinkHandleInfo);

   166 

   167 	IMPORT_C TInt Reset();

   168 

   169 	IMPORT_C TInt Prime();

   170 

   171 	IMPORT_C TInt Play();

   172 

   173 	IMPORT_C TInt Pause();

   174 

   175 	IMPORT_C TInt Stop();

   176 

   177 	IMPORT_C TInt GetPosition(TTimeIntervalMicroSeconds& aPosition) const;

   178 

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

   180 

   181 	IMPORT_C TInt GetDuration(TTimeIntervalMicroSeconds& aDuration) const;

   182 

   183 	IMPORT_C TInt GetNumberOfMetaDataEntries(TInt& aNumberOfEntries) const;

   184 

   185 	IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aIndex) const;

   186 

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

   188 

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

   190 

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

   192 

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

   194 

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

   196 

   197 	IMPORT_C TInt CancelReceiveEvents();

   198 	

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

   200 	

   201 private:

   202 	/**

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

   204 	*/

   205 	RMMFControllerProxy iControllerProxy;

   206 

   207 	/**

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

   209 	*/

   210 	TMMFMessageDestinationPckg iDestinationPckg;

   211 	};

   212 

   213 

   214 /**

   215 @publishedAll

   216 @released

   217 

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

   219 

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

   221 of passing commands to those objects.

   222 

   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();

   230 

   231 	IMPORT_C CMMFObject(TUid aInterfaceId);

   232 

   233 	IMPORT_C const TMMFMessageDestination& Handle();

   234 

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

   236 

   237 	/**

   238 	Passes a message to the object to handle.

   239 

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

   241 

   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.

   244 

   245 	@param  aMessage

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

   247 

   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 	};

   256 

   257 

   258 /**

   259 @publishedAll

   260 @released

   261 

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

   263 

   264 @since 7.0s

   265 */

   266 class CMMFObjectContainer : public CBase

   267 	{

   268 public:

   269 

   270 	IMPORT_C CMMFObjectContainer();

   271 

   272 	IMPORT_C ~CMMFObjectContainer();

   273 

   274 	IMPORT_C TInt AddMMFObject(CMMFObject& aObject);

   275 

   276 	IMPORT_C void RemoveAndDestroyMMFObject(CMMFObject& aObject);

   277 

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

   279 

   280 	IMPORT_C void DeleteAllObjects();

   281 	

   282 	const RPointerArray<CMMFObject>& MMFObjects();

   283 	

   284 private:

   285 	/**

   286 	Internal method to find an object in the array.

   287 	*/

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

   289 

   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;

   299 

   300 	/**

   301 	The next available object handle.

   302 	*/

   303 	TInt iNextObjectHandle;

   304 	};

   305 

   306 

   307 /**

   308 @publishedAll

   309 @released

   310 

   311 CMMFObject-derived class to wrap a Data Source.

   312 

   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.

   315 

   316 @since 7.0s

   317 */

   318 class CMMFDataSourceHolder : public CMMFObject

   319 	{

   320 public:

   321 

   322 	IMPORT_C CMMFDataSourceHolder(MDataSource& aDataSource);

   323 

   324 	IMPORT_C ~CMMFDataSourceHolder();

   325 

   326 	IMPORT_C MDataSource& DataSource();

   327 

   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 	};

   336 

   337 /**

   338 @publishedAll

   339 @released

   340 

   341 CMMFObject-derived class to wrap a Data Sink.

   342 

   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.

   345 

   346 @since 7.0s

   347 */

   348 class CMMFDataSinkHolder : public CMMFObject

   349 	{

   350 public:

   351 	IMPORT_C CMMFDataSinkHolder(MDataSink& aDataSink);

   352 

   353 	IMPORT_C ~CMMFDataSinkHolder();

   354 

   355 	IMPORT_C MDataSink& DataSink();

   356 

   357 	//from CMMFObject

   358 	IMPORT_C void HandleRequest(TMMFMessage& aMessage);

   359 

   360 private:

   361 	/**

   362 	Pointer to the data sink owned by this object.

   363 	*/

   364 	MDataSink* iDataSink;

   365 	};

   366 

   367 

   368 /**

   369 @publishedAll

   370 @released

   371 

   372 Base class for client-side custom command classes.

   373 

   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.

   377 

   378 @since 7.0s

   379 */

   380 class RMMFCustomCommandsBase

   381 	{

   382 public:

   383 

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

   385 protected:

   386 	/**

   387 	The controller.

   388 

   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;

   394 

   395 	/**

   396 	The destination package.

   397 

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

   399 	iController.CustomCommandAsync() as the destination argument.

   400 	*/

   401 	TMMFMessageDestinationPckg iDestinationPckg;

   402 	};

   403 

   404 /**

   405 @publishedAll

   406 @released

   407 

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

   409 

   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.

   417 

   418 @since 7.0s

   419 */

   420 class CMMFCustomCommandParserBase : public CBase

   421 	{

   422 public:

   423 

   424 	/**

   425 	Pure virtual method to be implemented by derived classes.

   426 

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

   428 

   429 	@param  aMessage

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

   431 

   432 	@since 7.0s

   433 	*/

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

   435 

   436 	/**

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

   438 

   439 	@return The interface UID.

   440 

   441 	@since  7.0s

   442 	*/

   443 	IMPORT_C TUid InterfaceId();

   444 

   445 	/**

   446 	Destructor.

   447 

   448 	@since 7.0s

   449 	*/

   450 	IMPORT_C ~CMMFCustomCommandParserBase();

   451 protected:

   452 

   453 	/**

   454 	Constructor.

   455 

   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.

   460 

   461 	@since  7.0s

   462 	*/

   463 	IMPORT_C CMMFCustomCommandParserBase(TUid aInterfaceId);

   464 

   465 private:

   466 

   467 	/**

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

   469 	*/

   470 	TUid iInterfaceId;

   471 	};

   472 

   473 /**

   474 @publishedPartner

   475 @released

   476 

   477 Class to manage custom command parsers.

   478 

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

   480 parsers for the controller plugin.

   481 

   482 @since 7.0s

   483 */

   484 class CMMFCustomCommandParserManager : public CBase

   485 	{

   486 public:

   487 	/**

   488 	Factory constructor.

   489 

   490 	@return A pointer to the newly created object.

   491 

   492 	@since 7.0s

   493 	*/

   494 	IMPORT_C static CMMFCustomCommandParserManager* NewL();

   495 

   496 	/**

   497 	Destructor.

   498 

   499 	Deletes all custom command parsers added to the manager.

   500 

   501 	@since 7.0s

   502 	*/

   503 	IMPORT_C ~CMMFCustomCommandParserManager();

   504 

   505 	/**

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

   507 

   508 	@param  aMessage

   509             The message to be handled.

   510 

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

   512 	        if it has not.

   513 

   514 	@since 7.0s

   515 	*/

   516 	IMPORT_C TBool HandleRequest(TMMFMessage& aMessage);

   517 

   518 	/**

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

   520 

   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.

   524 

   525 	@param  aParser

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

   527 

   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 	};

   539 

   540 

   541 class CMMFControllerExtendedData;

   542 /**

   543 @publishedAll

   544 @released

   545 

   546 Base class for controller plugins.

   547 

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

   549 all the pure virtual functions.

   550 

   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.

   556 

   557 @since 7.0s

   558 */

   559 class CMMFController : public CBase

   560 	{

   561 public:

   562 

   563 	/**

   564 	Allocates and constructs a new controller plugin.

   565 

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

   567 

   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

   575 

   576 	@return A pointer to the new controller plugin.

   577 

   578 	@since	7.0s

   579 	*/

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

   581 

   582 	/**

   583 	Handles a message from the client.

   584 

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

   586 

   587 	@param  aMessage

   588 	        The message to be handled.

   589 

   590 	@since  7.0s

   591 	*/

   592 	IMPORT_C virtual void HandleRequestL(TMMFMessage& aMessage);

   593 

   594 	/**

   595 	Default destructor.

   596 	*/

   597 	IMPORT_C virtual ~CMMFController();

   598 protected:

   599 

   600 	/**

   601 	Constructor.

   602 	*/

   603 	CMMFController() {};

   604 

   605 	// virtual functions to be implemented by controller plugin

   606 

   607 	/**

   608 	Add a data source to the controller plugin.

   609 

   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.

   612 

   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.

   617 

   618 	@leave  KErrNotSupported

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

   620 

   621 	@since  7.0s

   622 	*/

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

   624 

   625 	/**

   626 	Adds a data sink to the controller plugin.

   627 

   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.

   630 

   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.

   635 

   636 	@leave  KErrNotSupported

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

   638 

   639 	@since 7.0s

   640 	*/

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

   642 

   643 	/**

   644 	Removes a data source from the controller plugin.

   645 

   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.

   649 

   650 	@param  aDataSource

   651 	        A reference to the data source to be removed.

   652 

   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.

   659 

   660 	@since 7.0s

   661 	*/

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

   663 

   664 	/**

   665 	Removes a data sink from the controller plugin.

   666 

   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.

   670 

   671 	@param  aDataSink

   672 	        A reference to the data sink to be removed.

   673 

   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.

   680 

   681 	@since  7.0s

   682 	*/

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

   684 

   685 	/**

   686 	Resets the controller plugin.

   687 

   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.

   691 

   692 	@leave  KErrNotSupported

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

   694 

   695 	@since  7.0s

   696 	*/

   697 	virtual void ResetL() = 0;

   698 

   699 	/**

   700 	Primes the controller plugin.

   701 

   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.

   704 

   705 	@since  7.0s

   706 	*/

   707 	virtual void PrimeL() = 0;

   708 

   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.

   712 

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

   714 

   715 	@since  7.0s

   716 	*/

   717 	IMPORT_C virtual void PrimeL(TMMFMessage& aMessage);

   718 

   719 	/**

   720 	Commences playback.

   721 

   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.

   724 

   725 	Note:

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

   727 

   728 	@since  7.0s

   729 	*/

   730 	virtual void PlayL()= 0;

   731 

   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.

   735 

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

   737 

   738 	@since  7.0s

   739 	*/

   740 	IMPORT_C virtual void PlayL(TMMFMessage& aMessage);

   741 

   742 

   743 	/**

   744 	Pauses the controller plugin.

   745 

   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.

   748 

   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.

   752 

   753 	@since  7.0s

   754 	*/

   755 	virtual void PauseL()= 0;

   756 

   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.

   760 

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

   762 

   763 	@since  7.0s

   764 	*/

   765 	IMPORT_C virtual void PauseL(TMMFMessage& aMessage);

   766 

   767 	/**

   768 	Stops the controller plugin.

   769 

   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.

   772 

   773 	@since  7.0s

   774 	*/

   775 	virtual void StopL()= 0;

   776 

   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.

   780 

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

   782 

   783 	@since  7.0s

   784 	*/

   785 	IMPORT_C virtual void StopL(TMMFMessage& aMessage);

   786 

   787 	/**

   788 	Gets the current position.

   789 

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

   791 

   792 	@return The current position in microseconds.

   793 

   794 	@since  7.0s

   795 	*/

   796 	virtual TTimeIntervalMicroSeconds PositionL() const = 0;

   797 

   798 	/**

   799 	Sets the current position.

   800 

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

   802 

   803 	@param  aPosition

   804 	        The desired position in microseconds.

   805 

   806 	@since  7.0s

   807 	*/

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

   809 

   810 	/**

   811 	Gets the duration of the clip.

   812 

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

   814 

   815 	@return The clips duration in microseconds.

   816 

   817 	@since  7.0s

   818 	*/

   819 	virtual TTimeIntervalMicroSeconds DurationL() const = 0;

   820 

   821 	/**

   822 	Sets the priority settings.

   823 

   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).

   826 

   827 	@param  aPrioritySettings

   828 	        The new priority settings

   829 

   830 	@since  7.0s

   831 

   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;

   837 

   838 	/**

   839 	Handles a custom command.

   840 

   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.

   844 

   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.

   849 

   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.

   852 

   853 	@param  aMessage

   854 	        The message to be handled by the controller plugin.

   855 

   856     @see    CMMFCustomCommandParserBase.

   857 	@since 7.0s

   858 	*/

   859 	virtual void CustomCommand(TMMFMessage& aMessage)

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

   861 

   862 	/**

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

   864 

   865 	@param  aNumberOfEntries

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

   867 	        in the clip.

   868 

   869 	@since  7.0s

   870 	*/

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

   872 

   873 	/**

   874 	Retrieves a meta data entry from the clip.

   875 

   876 	@param  aIndex

   877 	        The index of the meta data entry to retrieve.

   878 

   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.

   881 

   882 	@since  7.0s

   883 	*/

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

   885 

   886 	// Utility functions to be used by controller plugins

   887 

   888 	/**

   889 	Sends an event to the client.

   890 

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

   892 

   893 	@param  aEvent

   894 	        The event to be sent to the client.

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

   896 

   897 	@since 7.0s

   898 	*/

   899 	IMPORT_C TInt DoSendEventToClient(const TMMFEvent& aEvent);

   900 

   901 	/**

   902 	Gets a reference to the multimedia framework object container.

   903 

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

   905 	to receive messages directly from the client.

   906 

   907 	@return A reference to the MMFObjectContainer.

   908 

   909 	@since  7.0s

   910 	*/

   911 	IMPORT_C CMMFObjectContainer& MMFObjectContainerL();

   912 

   913 	/**

   914 	Adds a custom command parser to the controller framework.

   915 

   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.

   919 

   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.

   922 

   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.

   926 

   927 	@since  7.0s

   928 	*/

   929 	IMPORT_C void AddCustomCommandParserL(CMMFCustomCommandParserBase& aParser);

   930 

   931 	/**

   932 	Retrieves the client thread Id of this controller.

   933 

   934 	@return Thread Id of the controller's client

   935 	*/

   936 	IMPORT_C TThreadId ClientThreadIdL();

   937 	

   938 	/**

   939 	Check the Secure DRM Mode of current controller object

   940 

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

   942 	*/

   943 	IMPORT_C TBool IsSecureDrmModeL();

   944 	

   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);

   980 	

   981 private:

   982 	/**

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

   984 	*/

   985 	CBufFlat* iMetaDataBuffer;

   986 	

   987 	/**

   988 	Required by ECOM.

   989 	*/

   990 	TUid iDtor_ID_Key;

   991 

   992 	/**

   993 	The event handler for the controller plugin.

   994 	*/

   995 	MAsyncEventHandler* iAsyncEventHandler;

   996 

   997 	/**

   998 	The MMF object container.

   999 	*/

  1000 	CMMFObjectContainer* iMMFObjectContainer;

  1001 

  1002 	/**

  1003 	The custom command parser manager.

  1004 	*/

  1005 	CMMFCustomCommandParserManager* iCustomCommandParserManager;

  1006 	};

  1007 

  1008 

  1009 

  1010 /**

  1011 @publishedAll

  1012 @released

  1013 

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

  1015 

  1016 @since  7.0s

  1017 */

  1018 class MMMFControllerEventMonitorObserver

  1019 	{

  1020 public:

  1021 

  1022 	/**

  1023 	Handles an event that has been generated.

  1024 

  1025 	@param  aEvent

  1026 	        The event to be handled.

  1027 

  1028 	@since  7.0s

  1029 	*/

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

  1031 	};

  1032 

  1033 /**

  1034 @publishedAll

  1035 @released

  1036 

  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.

  1039 

  1040 @since 7.0s

  1041 */

  1042 class CMMFControllerEventMonitor : public CActive

  1043 	{

  1044 public:

  1045 

  1046 	/**

  1047 	Constructs a controller event monitor object.

  1048 

  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.

  1054 

  1055 	@return A pointer to the new event monitor.

  1056 

  1057 	@since  7.0s

  1058 	*/

  1059 	IMPORT_C static CMMFControllerEventMonitor* NewL(MMMFControllerEventMonitorObserver& aObserver,

  1060 		RMMFController& aMMFController);

  1061 	/**

  1062 	Destructor.

  1063 	*/

  1064 	~CMMFControllerEventMonitor();

  1065 

  1066 	/**

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

  1068 

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

  1070 

  1071 	@since  7.0s

  1072 	*/

  1073 	IMPORT_C void Start();

  1074 

  1075 private:

  1076 	/**

  1077 	Calls HandleEvent on iObserver.

  1078 

  1079 	This will not leave.

  1080 

  1081 	@since  7.0s

  1082 	*/

  1083 	void RunL();

  1084 

  1085 	/**

  1086 	Cancels the outstanding request on iMMFController.

  1087 

  1088 	@since  7.0s

  1089 	*/

  1090 	void DoCancel();

  1091 

  1092 	/**

  1093 	Constructs a controller event monitor object.

  1094 	

  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.

  1100 

  1101 	@since  7.0s

  1102 	*/

  1103 	CMMFControllerEventMonitor(MMMFControllerEventMonitorObserver& aObserver,

  1104 		RMMFController& aMMFController);

  1105 private:

  1106 	MMMFControllerEventMonitorObserver& iObserver;

  1107 	RMMFController& iMMFController;

  1108 	TMMFEventPckg iEventPckg;

  1109 	};

  1110 

  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 	};

  1131 

  1132 

  1133 /**

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