epoc32/include/mmf/common/mmfcontroller.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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
  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
  1140 
  1141 */
  1142 class CMMFAddDataSourceSinkAsync : public CActive
  1143 	{
  1144 public:
  1145 
  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);
  1153 
  1154 	~CMMFAddDataSourceSinkAsync();
  1155 
  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 	};
  1170 
  1171 /**
  1172 @internalComponent
  1173 
  1174 The controller proxy session.
  1175 
  1176 Only one session can be connected to a controller proxy server.
  1177 
  1178 */
  1179 NONSHARABLE_CLASS(CMMFControllerExtendedData) : public CMMFObject
  1180 	{
  1181 public:
  1182 	CMMFControllerExtendedData();
  1183 	
  1184 	~CMMFControllerExtendedData();
  1185 	
  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();
  1192 
  1193 	// Set/Get the client thread ID used by CMMFController
  1194 	void SetClientThreadId(TThreadId aClientThreadId);
  1195 	TThreadId ClientThreadId() const;
  1196 	
  1197 	// Set/Get the Secure DRM mode of CMMFController
  1198 	void SetSecureDrmMode(TBool aSecureDrmMode);
  1199 	TBool SecureDrmMode() const;
  1200 		
  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;
  1211 	
  1212 	/**
  1213 	Extended data uses by CMMFController: The client thread Id
  1214 	*/
  1215 	TThreadId iClientThreadId;
  1216 	
  1217 	/**
  1218 	Extended data uses by CMMFController: Controller Scecure DRM Mode
  1219 	*/
  1220 	TBool iSecureDrmMode;
  1221 	};
  1222 
  1223 #endif