epoc32/include/mmf/common/mmfcontroller.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100 (2010-03-31)
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
     2 // All rights reserved.
     3 // This component and the accompanying materials are made available
     4 // under the terms of "Eclipse Public License v1.0"
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 //
    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 <mmf/plugin/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 @publishedAll
    53 @released
    54 
    55 Client representation of a controller plugin for the Multimedia Framework.
    56 
    57 This class allows a client to load a controller plugin into a new thread and access the
    58 functionality provided by that plugin.
    59 
    60 @since 7.0s
    61 */
    62 class RMMFController
    63 	{
    64 public:
    65 
    66 	IMPORT_C RMMFController();
    67 
    68 	IMPORT_C TInt Open(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings);
    69 
    70 	IMPORT_C TInt Open(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings);
    71 
    72 	IMPORT_C TInt Open(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap );
    73 
    74 	IMPORT_C TInt Open(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap );
    75 	
    76 	IMPORT_C TInt OpenInSecureDRMProcess(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings);
    77 	
    78 	IMPORT_C TInt OpenInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings);
    79 
    80 	IMPORT_C TInt OpenInSecureDRMProcess(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap );
    81 
    82 	IMPORT_C TInt OpenInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap );
    83 	
    84 	IMPORT_C void Close();
    85 
    86 	IMPORT_C TInt SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings) const;
    87 
    88 	IMPORT_C TInt AddDataSource(TUid aSourceUid, const TDesC8& aSourceInitData);
    89 
    90 	IMPORT_C TInt AddDataSink(TUid aSinkUid, const TDesC8& aSinkInitData);
    91 
    92 	IMPORT_C TInt AddDataSource(TUid aSourceUid, const TDesC8& aSourceInitData, TMMFMessageDestination& aHandleInfo);
    93 	
    94 	IMPORT_C TInt AddDataSink(TUid aSinkUid, const TDesC8& aSinkInitData, TMMFMessageDestination& aHandleInfo);
    95 
    96 	IMPORT_C void AddDataSource(const TMMFUidPckg& aSourceUid, const TDesC8& aSourceInitData, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);
    97 	IMPORT_C void AddFileHandleDataSource(const RFile& aFile, const TDesC8& aSourceInitData, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);
    98 	IMPORT_C void AddFileHandleDataSource(const RFile& aFile, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);
    99 	
   100 	IMPORT_C void CancelAddDataSource();
   101 	
   102 	IMPORT_C void AddDataSink(const TMMFUidPckg& aSinkUid, const TDesC8& aSinkInitData, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);
   103 	IMPORT_C void AddFileHandleDataSink(const RFile& aFile, const TDesC8& aSinkInitData, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);
   104 	IMPORT_C void AddFileHandleDataSink(const RFile& aFile, TMMFMessageDestinationPckg& aHandleInfoPckg, TRequestStatus& aStatus);
   105 	
   106 	IMPORT_C void CancelAddDataSink();
   107 
   108 	IMPORT_C TInt RemoveDataSource(const TMMFMessageDestination& aSourceHandleInfo);
   109 
   110 	IMPORT_C TInt RemoveDataSink(const TMMFMessageDestination& aSinkHandleInfo);
   111 
   112 	IMPORT_C TInt Reset();
   113 
   114 	IMPORT_C TInt Prime();
   115 
   116 	IMPORT_C TInt Play();
   117 
   118 	IMPORT_C TInt Pause();
   119 
   120 	IMPORT_C TInt Stop();
   121 
   122 	IMPORT_C TInt GetPosition(TTimeIntervalMicroSeconds& aPosition) const;
   123 
   124 	IMPORT_C TInt SetPosition(const TTimeIntervalMicroSeconds& aPosition) const;
   125 
   126 	IMPORT_C TInt GetDuration(TTimeIntervalMicroSeconds& aDuration) const;
   127 
   128 	IMPORT_C TInt GetNumberOfMetaDataEntries(TInt& aNumberOfEntries) const;
   129 
   130 	IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aIndex) const;
   131 
   132 	IMPORT_C TInt CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);
   133 
   134 	IMPORT_C TInt CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);
   135 
   136 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);
   137 
   138 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);
   139 
   140 	IMPORT_C void ReceiveEvents(TMMFEventPckg& aEventPckg, TRequestStatus& aStatus);
   141 
   142 	IMPORT_C TInt CancelReceiveEvents();
   143 	
   144 	IMPORT_C TInt SetThreadPriority(const TThreadPriority& aPriority) const;
   145 	
   146 private:
   147 	/**
   148 	The controller proxy.  Used to pass messages to the controller thread.
   149 	*/
   150 	RMMFControllerProxy iControllerProxy;
   151 
   152 	/**
   153 	Used to hold the destination information for messages for the standard controller plugin interface.
   154 	*/
   155 	TMMFMessageDestinationPckg iDestinationPckg;
   156 	};
   157 
   158 
   159 /**
   160 @publishedAll
   161 @released
   162 
   163 Defines an object to which a client may have a direct handle.
   164 
   165 This class provides a way of identifying objects within the controller framework, and a means
   166 of passing commands to those objects.
   167 
   168 @since  7.0s
   169 */
   170 class CMMFObject : public CBase
   171 	{
   172 friend class CMMFObjectContainer;//to set the handle
   173 public:
   174 	IMPORT_C ~CMMFObject();
   175 
   176 	IMPORT_C CMMFObject(TUid aInterfaceId);
   177 
   178 	IMPORT_C const TMMFMessageDestination& Handle();
   179 
   180 	IMPORT_C TBool operator==(const CMMFObject& aOther);
   181 
   182 	/**
   183 	Passes a message to the object to handle.
   184 
   185 	This is a pure virtual method to be implemented by concrete classes derived from this class.
   186 
   187 	The message passed in MUST be completed by the object; however, it can be copied to be
   188 	completed at a later time, should some other asynchronous action need to occur first.
   189 
   190 	@param  aMessage
   191 	        The message to be handled.  This MUST be completed by the object.
   192 
   193 	@since  7.0s
   194 	*/
   195 	virtual void HandleRequest(TMMFMessage& aMessage) = 0;
   196 private:
   197 	void SetHandle(const TMMFMessageDestination& aNewHandle);
   198 private:
   199 	TMMFMessageDestination iHandle;
   200 	};
   201 
   202 /**
   203 @publishedAll
   204 @released
   205 
   206 Container class to hold the CMMFObject-derived objects in the controller framework.
   207 
   208 @since 7.0s
   209 */
   210 class CMMFObjectContainer : public CBase
   211 	{
   212 public:
   213 
   214 	IMPORT_C CMMFObjectContainer();
   215 
   216 	IMPORT_C ~CMMFObjectContainer();
   217 
   218 	IMPORT_C TInt AddMMFObject(CMMFObject& aObject);
   219 
   220 	IMPORT_C void RemoveAndDestroyMMFObject(CMMFObject& aObject);
   221 
   222 	IMPORT_C TInt FindMMFObject(const TMMFMessageDestination& aObjectHandle, CMMFObject*& aObjectFound);
   223 
   224 	IMPORT_C void DeleteAllObjects();
   225 	
   226 	const RPointerArray<CMMFObject>& MMFObjects();
   227 	
   228 private:
   229 	/**
   230 	Internal method to find an object in the array.
   231 	*/
   232 	TInt FindMMFObject(const CMMFObject& aObject, TInt& aPositionInArray);
   233 
   234 	/**
   235 	Internal method used to generate the object handle for a newly added object.
   236 	*/
   237 	TInt GenerateObjectHandle();
   238 private:
   239 	/**
   240 	The array of objects.
   241 	*/
   242 	RPointerArray<CMMFObject> iObjects;
   243 
   244 	/**
   245 	The next available object handle.
   246 	*/
   247 	TInt iNextObjectHandle;
   248 	};
   249 
   250 
   251 /**
   252 @publishedAll
   253 @released
   254 
   255 CMMFObject-derived class to wrap a Data Source.
   256 
   257 Allows a handle to be attributed to a data source, so it can be removed from the controller and
   258 the client can send messages directly to it.
   259 
   260 @since 7.0s
   261 */
   262 class CMMFDataSourceHolder : public CMMFObject
   263 	{
   264 public:
   265 
   266 	IMPORT_C CMMFDataSourceHolder(MDataSource& aDataSource);
   267 
   268 	IMPORT_C ~CMMFDataSourceHolder();
   269 
   270 	IMPORT_C MDataSource& DataSource();
   271 
   272 	//from CMMFObject
   273 	IMPORT_C void HandleRequest(TMMFMessage& aMessage);
   274 private:
   275 	/**
   276 	Pointer to the data source owned by this object.
   277 	*/
   278 	MDataSource* iDataSource;
   279 	};
   280 
   281 /**
   282 @publishedAll
   283 @released
   284 
   285 CMMFObject-derived class to wrap a Data Sink.
   286 
   287 Allows a handle to be attributed to a data sink, so it can be removed from the controller and
   288 the client can send messages directly to it.
   289 
   290 @since 7.0s
   291 */
   292 class CMMFDataSinkHolder : public CMMFObject
   293 	{
   294 public:
   295 	IMPORT_C CMMFDataSinkHolder(MDataSink& aDataSink);
   296 
   297 	IMPORT_C ~CMMFDataSinkHolder();
   298 
   299 	IMPORT_C MDataSink& DataSink();
   300 
   301 	//from CMMFObject
   302 	IMPORT_C void HandleRequest(TMMFMessage& aMessage);
   303 
   304 private:
   305 	/**
   306 	Pointer to the data sink owned by this object.
   307 	*/
   308 	MDataSink* iDataSink;
   309 	};
   310 
   311 
   312 /**
   313 @publishedAll
   314 @released
   315 
   316 Base class for client-side custom command classes.
   317 
   318 In order facilitate the use of the more common custom commands, it is desirable to write
   319 a concrete API class for the client to use.  This API class can then be use to wrap all the code
   320 involved to formulate the custom command messages.
   321 
   322 @since 7.0s
   323 */
   324 class RMMFCustomCommandsBase
   325 	{
   326 public:
   327 
   328 	IMPORT_C RMMFCustomCommandsBase(RMMFController& aController, TUid aInterfaceId);
   329 protected:
   330 	/**
   331 	The controller.
   332 
   333 	Derived classes should use iController.CustomCommandSync() and
   334 	iController.CustomCommandAsync() to send the custom commands to the controller
   335 	plugin.
   336 	*/
   337 	RMMFController& iController;
   338 
   339 	/**
   340 	The destination package.
   341 
   342 	Derived classes must pass this into iController.CustomCommandSync() and
   343 	iController.CustomCommandAsync() as the destination argument.
   344 	*/
   345 	TMMFMessageDestinationPckg iDestinationPckg;
   346 	};
   347 
   348 /**
   349 @publishedAll
   350 @released
   351 
   352 Base class to define the interface of a custom command parser.
   353 
   354 In order to facilitate the support of common custom commands by controller plugins, a
   355 custom command parser object can be used.  A set of custom command parsers are created
   356 by the controller plugin (one for each interface supported), and added to the custom command
   357 parser manager in the controller framework.  The controller plugin must also derive from a set of
   358 concrete interfaces (provided in the form of mixin classes). Then, a custom command supported by
   359 one of the custom command parsers will appear to the controller as a concrete API call, rather than
   360 a call to its own custom command API.
   361 
   362 @since 7.0s
   363 */
   364 class CMMFCustomCommandParserBase : public CBase
   365 	{
   366 public:
   367 
   368 	/**
   369 	Pure virtual method to be implemented by derived classes.
   370 
   371 	Derived classes must implement the code to decode the message from the client.
   372 
   373 	@param  aMessage
   374 	        The message to be serviced. This message must be completed by the derived class.
   375 
   376 	@since 7.0s
   377 	*/
   378 	virtual void HandleRequest(TMMFMessage& aMessage) = 0;
   379 
   380 	/**
   381 	Returns the UID of the custom command interface provided by this parser.
   382 
   383 	@return The interface UID.
   384 
   385 	@since  7.0s
   386 	*/
   387 	IMPORT_C TUid InterfaceId();
   388 
   389 	/**
   390 	Destructor.
   391 
   392 	@since 7.0s
   393 	*/
   394 	IMPORT_C ~CMMFCustomCommandParserBase();
   395 protected:
   396 
   397 	/**
   398 	Constructor.
   399 
   400 	@param  aInterfaceId
   401 	        The uid of the custom command interface provided by this parser.
   402 	        This must be the same as the interface id of the corresponding client
   403 	        API class. See RMMFCustomCommandsBase.
   404 
   405 	@since  7.0s
   406 	*/
   407 	IMPORT_C CMMFCustomCommandParserBase(TUid aInterfaceId);
   408 
   409 private:
   410 
   411 	/**
   412 	The uid of the custom command interface provided by this parser.
   413 	*/
   414 	TUid iInterfaceId;
   415 	};
   416 
   417 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
   418 #include <mmf/common/mmfcontrollerextendeddata.h>
   419 #include <mmf/common/mmfcustomcommandparsermanager.h>
   420 #endif
   421 
   422 
   423 class CMMFControllerExtendedData;
   424 class CMMFCustomCommandParserManager;
   425 /**
   426 @publishedAll
   427 @released
   428 
   429 Base class for controller plugins.
   430 
   431 A controller plugin for the multimedia framework must derive from this class and implement
   432 all the pure virtual functions.
   433 
   434 Controller plugins control the flow of multimedia data from one or more sources to one or
   435 more sinks. For example, an audio controller plugin might take data from a file source and
   436 output it to a speaker sink, or take data from a microphone source and save it to a file
   437 sink. A controller plugin typically supports one or more multimedia formats, for example
   438 WAV or MPEG4.
   439 
   440 @since 7.0s
   441 */
   442 class CMMFController : public CBase
   443 	{
   444 public:
   445 
   446 	/**
   447 	Allocates and constructs a new controller plugin.
   448 
   449 	Uses ECOM to instantiate a new controller plugin. Can leave with any of the system-wide error codes.
   450 
   451 	@param  aControllerUid
   452 	        The unique ID of the controller to be instantiated from ECOM.
   453 	@param  aEventHandler
   454 	        A reference to an event handling object that can be used by the
   455 	        controller to send events back to the client.
   456 	@param 	aClientTid
   457 			The thread Id of the client thread
   458 
   459 	@return A pointer to the new controller plugin.
   460 
   461 	@since	7.0s
   462 	*/
   463 	static CMMFController* NewL(TUid aControllerUid, MAsyncEventHandler& aEventHandler, TThreadId aClientTid);
   464 
   465 	/**
   466 	Handles a message from the client.
   467 
   468 	Decodes the message and calls one of the private DoXxx methods to unpackaged the parameters.
   469 
   470 	@param  aMessage
   471 	        The message to be handled.
   472 
   473 	@since  7.0s
   474 	*/
   475 	IMPORT_C virtual void HandleRequestL(TMMFMessage& aMessage);
   476 
   477 	/**
   478 	Default destructor.
   479 	*/
   480 	IMPORT_C virtual ~CMMFController();
   481 protected:
   482 
   483 	/**
   484 	Constructor.
   485 	*/
   486 	CMMFController() {};
   487 
   488 	// virtual functions to be implemented by controller plugin
   489 
   490 	/**
   491 	Add a data source to the controller plugin.
   492 
   493 	NOTE: The data source is owned by the controller framework, NOT by the controller plugin.
   494 	Under no circumstances should the controller plugin delete the data source.
   495 
   496 	@param  aDataSource
   497 	        A reference to the data source to be added.  The controller plugin
   498 	        may call aDataSource.DataSourceType() to find out
   499 	        exactly what type of source it is.
   500 
   501 	@leave  KErrNotSupported
   502 	        If the controller plugin does not support the data source, it should leave with this.
   503 
   504 	@since  7.0s
   505 	*/
   506 	virtual void AddDataSourceL(MDataSource& aDataSource) = 0;
   507 
   508 	/**
   509 	Adds a data sink to the controller plugin.
   510 
   511 	NOTE: The data sink is owned by the controller framework, NOT by the controller plugin.
   512 	Under no circumstances should the controller plugin delete the data sink.
   513 
   514 	@param  aDataSink
   515 	        A reference to the data sink to be added.  The controller plugin
   516 	        may call aDatasink.DatasinkType() to find out
   517             exactly what type of sink it is.
   518 
   519 	@leave  KErrNotSupported
   520 	        If the controller plugin does not support the data sink, it should leave with this.
   521 
   522 	@since 7.0s
   523 	*/
   524 	virtual void AddDataSinkL(MDataSink& aDataSink) = 0;
   525 
   526 	/**
   527 	Removes a data source from the controller plugin.
   528 
   529 	Note:
   530 	The data source is owned by the controller framework, NOT by the controller plugin.
   531 	Under no circumstances should the controller plugin delete the data source.
   532 
   533 	@param  aDataSource
   534 	        A reference to the data source to be removed.
   535 
   536 	@leave  KErrNotSupported
   537 	        The controller plugin may leave during this method.  If the controller plugin does
   538 	        not support the removal of data sources, it should leave with
   539 	        KErrNotSupported. If the controller plugin leaves, the data source will
   540 	        not be destroyed by the controller framework.  If it does not leave, the data source
   541 	        will be destroyed.
   542 
   543 	@since 7.0s
   544 	*/
   545 	virtual void RemoveDataSourceL(MDataSource& aDataSource) = 0;
   546 
   547 	/**
   548 	Removes a data sink from the controller plugin.
   549 
   550 	Note:
   551 	The data sink is owned by the controller framework, NOT by the controller plugin.
   552 	Under no circumstances should the controller plugin delete the data sink.
   553 
   554 	@param  aDataSink
   555 	        A reference to the data sink to be removed.
   556 
   557 	@leave  KErrNotSupported
   558 	        The controller plugin may leave during this method.  If the controller plugin does
   559 	        not support the removal of data sinks, it should leave with
   560 	        KErrNotSupported. If the controller plugin leaves, the data sink will
   561 	        not be destroyed by the controller framework.  If it does not leave, the data sink
   562 	        will be destroyed.
   563 
   564 	@since  7.0s
   565 	*/
   566 	virtual void RemoveDataSinkL(MDataSink& aDataSink) = 0;
   567 
   568 	/**
   569 	Resets the controller plugin.
   570 
   571 	The controller should revert back to its newly constructed state. If the Reset is successful
   572 	(i.e. it doesn't leave), the controller framework will delete all objects added to the
   573 	MMFObjectManager including any sources and sinks.
   574 
   575 	@leave  KErrNotSupported
   576 	        If the controller plugin does not support being reset, it should leave with KErrNotSupported.
   577 
   578 	@since  7.0s
   579 	*/
   580 	virtual void ResetL() = 0;
   581 
   582 	/**
   583 	Primes the controller plugin.
   584 
   585 	The controller must prepare to start playing, by initialising its sources, sinks and buffers.
   586 	This moves the controller from the STOPPED to the PRIMED state.
   587 
   588 	@since  7.0s
   589 	*/
   590 	virtual void PrimeL() = 0;
   591 
   592 	/**
   593 	A partner to the PrimeL() method that is overridable to allow Asynchronous
   594 	completion in the controller whilst maintaining a Synchronous client API.
   595 
   596 	The default implementation of this is to call PrimeL() and complete the message with KErrNone.
   597 
   598 	@since  7.0s
   599 	*/
   600 	IMPORT_C virtual void PrimeL(TMMFMessage& aMessage);
   601 
   602 	/**
   603 	Commences playback.
   604 
   605 	The controller must now begin transferring data from its source(s) to its sink(s).
   606 	This moves the controller from the PRIMED to the PLAYING state.
   607 
   608 	Note:
   609 	This method must return once playing has commenced, and not wait until playing is complete.
   610 
   611 	@since  7.0s
   612 	*/
   613 	virtual void PlayL()= 0;
   614 
   615 	/**
   616 	A partner to the PlayL() method that is overridable to allow Asynchronous
   617 	completion in the controller whilst maintaining a Synchronous client API.
   618 
   619 	The default implementation of this is to call PlayL() and complete the message with KErrNone.
   620 
   621 	@since  7.0s
   622 	*/
   623 	IMPORT_C virtual void PlayL(TMMFMessage& aMessage);
   624 
   625 
   626 	/**
   627 	Pauses the controller plugin.
   628 
   629 	The controller must now cease transferring data from its source(s) to its sink(s).
   630 	This moves the controller from the PLAYING back to the PRIMED state.
   631 
   632 	A subsequent call to Play() will cause the controller plugin to resume playback
   633 	from the point it was paused (unless there has been a call to SetPosition() in
   634 	the meantime.
   635 
   636 	@since  7.0s
   637 	*/
   638 	virtual void PauseL()= 0;
   639 
   640 	/**
   641 	A partner to the PauseL() method that is overridable to allow Asynchronous
   642 	completion in the controller whilst maintaining a Synchronous client API.
   643 
   644 	The default implementation of this is to call PauseL() and complete the message with KErrNone.
   645 
   646 	@since  7.0s
   647 	*/
   648 	IMPORT_C virtual void PauseL(TMMFMessage& aMessage);
   649 
   650 	/**
   651 	Stops the controller plugin.
   652 
   653 	The controller must now undo anything that occurred during the call to Prime().
   654 	This moves the controller from the PRIMED back to the STOPPED state.
   655 
   656 	@since  7.0s
   657 	*/
   658 	virtual void StopL()= 0;
   659 
   660 	/**
   661 	A partner to the StopL() method that is overridable to allow Asynchronous
   662 	completion in the controller whilst maintaining a Synchronous client API.
   663 
   664 	The default implementation of this is to call StopL() and complete the message with KErrNone.
   665 
   666 	@since  7.0s
   667 	*/
   668 	IMPORT_C virtual void StopL(TMMFMessage& aMessage);
   669 
   670 	/**
   671 	Gets the current position.
   672 
   673 	The controller plugin should calculate the current position in microseconds.
   674 
   675 	@return The current position in microseconds.
   676 
   677 	@since  7.0s
   678 	*/
   679 	virtual TTimeIntervalMicroSeconds PositionL() const = 0;
   680 
   681 	/**
   682 	Sets the current position.
   683 
   684 	The controller plugin should reposition itself to the position provided.
   685 
   686 	@param  aPosition
   687 	        The desired position in microseconds.
   688 
   689 	@since  7.0s
   690 	*/
   691 	virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition) = 0;
   692 
   693 	/**
   694 	Gets the duration of the clip.
   695 
   696 	The controller plugin should calculate the clip duration in microseconds.
   697 
   698 	@return The clips duration in microseconds.
   699 
   700 	@since  7.0s
   701 	*/
   702 	virtual TTimeIntervalMicroSeconds DurationL() const = 0;
   703 
   704 	/**
   705 	Sets the priority settings.
   706 
   707 	The new priority settings must be applied to any resource being used by the controller
   708 	plugin that requires priority settings (for example the sound device).
   709 
   710 	@param  aPrioritySettings
   711 	        The new priority settings
   712 
   713 	@since  7.0s
   714 
   715 	*/
   716 	virtual void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings) = 0;
   717 
   718 	/**
   719 	Handles a custom command.
   720 
   721 	Custom commands allow a controller plugin to define its own API.  If the controller framework
   722 	does not understand a message from the client, it is assumed this is a custom command for the
   723 	plugin and passed into this interface.
   724 
   725 	The more common custom commands can be handled by Custom Command Parsers on behalf of the
   726 	controller plugin.  This allows the controller plugin to implement a concrete interface
   727 	(defined by mixin classes) rather than having to decode the command itself.  For more
   728 	information, see CMMFCustomCommandParserBase.
   729 
   730 	The controller plugin must always complete the message passed into this method,
   731 	even if it does not support the interface required by the message.
   732 
   733 	@param  aMessage
   734 	        The message to be handled by the controller plugin.
   735 
   736     @see    CMMFCustomCommandParserBase.
   737 	@since 7.0s
   738 	*/
   739 	virtual void CustomCommand(TMMFMessage& aMessage)
   740 		{aMessage.Complete(KErrNotSupported);};//default implementation
   741 
   742 	/**
   743 	RetrieveS the number of meta data entries in the clip.
   744 
   745 	@param  aNumberOfEntries
   746 	        The controller plugin must set this to the number of meta data entries
   747 	        in the clip.
   748 
   749 	@since  7.0s
   750 	*/
   751 	virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries) = 0;
   752 
   753 	/**
   754 	Retrieves a meta data entry from the clip.
   755 
   756 	@param  aIndex
   757 	        The index of the meta data entry to retrieve.
   758 
   759 	@return A pointer to a newly created CMMFMetaDataEntry object containing the meta information.
   760 	        The controller framework will take ownership of the object when this method returns.
   761 
   762 	@since  7.0s
   763 	*/
   764 	virtual CMMFMetaDataEntry* GetMetaDataEntryL(TInt aIndex) = 0;
   765 
   766 	// Utility functions to be used by controller plugins
   767 
   768 	/**
   769 	Sends an event to the client.
   770 
   771 	The controller plugin can use this method to send an event to the client.
   772 
   773 	@param  aEvent
   774 	        The event to be sent to the client.
   775 	@return One of the system-wide error codes.
   776 
   777 	@since 7.0s
   778 	*/
   779 	IMPORT_C TInt DoSendEventToClient(const TMMFEvent& aEvent);
   780 
   781 	/**
   782 	Gets a reference to the multimedia framework object container.
   783 
   784 	The controller plugin may add CMMFObject-derived objects to the container to allow them
   785 	to receive messages directly from the client.
   786 
   787 	@return A reference to the MMFObjectContainer.
   788 
   789 	@since  7.0s
   790 	*/
   791 	IMPORT_C CMMFObjectContainer& MMFObjectContainerL();
   792 
   793 	/**
   794 	Adds a custom command parser to the controller framework.
   795 
   796 	If the controller framework receives a request it does not understand, it will
   797 	search through its list of custom command parsers before passing the request
   798 	on to the controller plugin as a custom command.
   799 
   800 	By using the custom command parsers, the controller plugin can implement a concrete
   801 	API rather than having to decode the common custom commands itself.
   802 
   803 	@param  aParser
   804 	        The parser to be added to the controller framework. The controller framework
   805 	        takes ownership of the parser if the call does not leave.
   806 
   807 	@since  7.0s
   808 	*/
   809 	IMPORT_C void AddCustomCommandParserL(CMMFCustomCommandParserBase& aParser);
   810 
   811 	/**
   812 	Retrieves the client thread Id of this controller.
   813 
   814 	@return Thread Id of the controller's client
   815 	*/
   816 	IMPORT_C TThreadId ClientThreadIdL();
   817 	
   818 	/**
   819 	Check the Secure DRM Mode of current controller object
   820 
   821 	@return ETrue if the controller is running under Secure DRM mode; otherwise EFalse.
   822 	*/
   823 	IMPORT_C TBool IsSecureDrmModeL();
   824 	
   825 private:
   826 	/**
   827 	This is internal and not intended for use.
   828 	*/
   829 	void ConstructL(MAsyncEventHandler& aEventHandler, TThreadId aClientTid);
   830 	// IPC decode functions
   831 	TBool DoAddDataSourceL(TMMFMessage& aMessage);
   832 	TBool DoAddDataSinkL(TMMFMessage& aMessage);
   833 	TBool DoAddFileHandleDataSourceL(TMMFMessage& aMessage);
   834 	TBool DoAddFileHandleDataSinkL(TMMFMessage& aMessage);
   835 	TBool DoRemoveDataSourceL(TMMFMessage& aMessage);
   836 	TBool DoRemoveDataSinkL(TMMFMessage& aMessage);
   837 	TBool DoResetL(TMMFMessage& aMessage);
   838 	TBool DoPrimeL(TMMFMessage& aMessage);
   839 	TBool DoPlayL(TMMFMessage& aMessage);
   840 	TBool DoPauseL(TMMFMessage& aMessage);
   841 	TBool DoStopL(TMMFMessage& aMessage);
   842 	TBool DoGetPositionL(TMMFMessage& aMessage);
   843 	TBool DoSetPositionL(TMMFMessage& aMessage);
   844 	TBool DoGetDurationL(TMMFMessage& aMessage);
   845 	TBool DoSetPrioritySettingsL(TMMFMessage& aMessage);
   846 	void DoCustomCommand(TMMFMessage& aMessage);
   847 	TBool DoGetNumberOfMetaDataEntriesL(TMMFMessage& aMessage);
   848 	TBool DoGetSizeOfMetaDataEntryL(TMMFMessage& aMessage);
   849 	TBool DoGetMetaDataEntryL(TMMFMessage& aMessage);
   850 	TBool DoPreloadSourceSinkInitDataL(TMMFMessage& aMessage);
   851 	TBool DoAddFileHandleDataSourceWithInitDataL(TMMFMessage& aMessage);
   852 	TBool DoAddFileHandleDataSinkWithInitDataL(TMMFMessage& aMessage);
   853 	void ReplaceFileHandleInInitDataL(RFile* aFile, TDes8& aInitData);
   854 	// Ownership of aSource is taken into this function
   855 	void AddMDataSourceAndRepondClientL(MDataSource* aSource, TMMFMessage& aMessage);
   856 	// Ownership of aSink is taken into this function
   857 	void AddMDataSinkAndRepondClientL(MDataSink* aSink, TMMFMessage& aMessage);
   858 	CMMFControllerExtendedData* GetExtendedDataL();
   859 	static CMMFControllerExtendedData* CreateExtendedDataL(TThreadId aClientTid);
   860 	
   861 private:
   862 	/**
   863 	Buffer to assist copy of meta data over the thread boundary.
   864 	*/
   865 	CBufFlat* iMetaDataBuffer;
   866 	
   867 	/**
   868 	Required by ECOM.
   869 	*/
   870 	TUid iDtor_ID_Key;
   871 
   872 	/**
   873 	The event handler for the controller plugin.
   874 	*/
   875 	MAsyncEventHandler* iAsyncEventHandler;
   876 
   877 	/**
   878 	The MMF object container.
   879 	*/
   880 	CMMFObjectContainer* iMMFObjectContainer;
   881 
   882 	/**
   883 	The custom command parser manager.
   884 	*/
   885 	CMMFCustomCommandParserManager* iCustomCommandParserManager;
   886 	};
   887 
   888 
   889 
   890 /**
   891 @publishedAll
   892 @released
   893 
   894 Mixin class that the user of the class CMMFControllerEventMonitor must derive from.
   895 
   896 @since  7.0s
   897 */
   898 class MMMFControllerEventMonitorObserver
   899 	{
   900 public:
   901 
   902 	/**
   903 	Handles an event that has been generated.
   904 
   905 	@param  aEvent
   906 	        The event to be handled.
   907 
   908 	@since  7.0s
   909 	*/
   910 	virtual void HandleEvent(const TMMFEvent& aEvent) = 0;
   911 	};
   912 
   913 /**
   914 @publishedAll
   915 @released
   916 
   917 Active object utility class that can be used to monitor a controller plugin for events.
   918 If an event occurs, the client will be notified via the MMMFControllerEventMonitorObserver interface.
   919 
   920 @since 7.0s
   921 */
   922 class CMMFControllerEventMonitor : public CActive
   923 	{
   924 public:
   925 
   926 	/**
   927 	Constructs a controller event monitor object.
   928 
   929 	@param  aObserver
   930 	        A reference to the observer of the active object.  The observer will be
   931 	        notified when an event occurs.
   932 	@param  aMMFController
   933 	        A reference to the client controller interface class.
   934 
   935 	@return A pointer to the new event monitor.
   936 
   937 	@since  7.0s
   938 	*/
   939 	IMPORT_C static CMMFControllerEventMonitor* NewL(MMMFControllerEventMonitorObserver& aObserver,
   940 		RMMFController& aMMFController);
   941 	/**
   942 	Destructor.
   943 	*/
   944 	~CMMFControllerEventMonitor();
   945 
   946 	/**
   947 	Tells the controller event monitor to start listening for events.
   948 
   949 	The controller plugin must have been opened before this method is called.
   950 
   951 	@since  7.0s
   952 	*/
   953 	IMPORT_C void Start();
   954 
   955 private:
   956 	/**
   957 	Calls HandleEvent on iObserver.
   958 
   959 	This will not leave.
   960 
   961 	@since  7.0s
   962 	*/
   963 	void RunL();
   964 
   965 	/**
   966 	Cancels the outstanding request on iMMFController.
   967 
   968 	@since  7.0s
   969 	*/
   970 	void DoCancel();
   971 
   972 	/**
   973 	Constructs a controller event monitor object.
   974 	
   975 	@param  aObserver
   976 	        A reference to the observer of the active object.  The observer will be
   977 	        notified when an event occurs.
   978 	@param  aMMFController
   979 	        A reference to the client controller interface class.
   980 
   981 	@since  7.0s
   982 	*/
   983 	CMMFControllerEventMonitor(MMMFControllerEventMonitorObserver& aObserver,
   984 		RMMFController& aMMFController);
   985 private:
   986 	MMMFControllerEventMonitorObserver& iObserver;
   987 	RMMFController& iMMFController;
   988 	TMMFEventPckg iEventPckg;
   989 	};
   990 
   991 /**
   992 Mixin class that the user of the class CMMFAddDataSourceSinkAsync must derive from.
   993 @since 8.0
   994 @publishedAll
   995 @released
   996 */
   997 class MMMFAddDataSourceSinkAsyncObserver
   998 	{
   999 public:
  1000 /**
  1001 The request to add a data source or sink has completed.
  1002 @param	"aError"		"The error resulting from adding the source/sink."
  1003 @param  "aHandleInfo"	"This object identifies	the data source/sink inside the controller 
  1004 						framework.  This allows the client to send custom commands directly to 
  1005 						the data source/sink, and to also remove the data sink from the controller.
  1006 						Note that not all data sinks support custom commands, and not all
  1007 						controller plugins support the removal of a data sink."
  1008 */
  1009 	virtual void MadssaoAddDataSourceSinkAsyncComplete(TInt aError, const TMMFMessageDestination& aHandle) = 0;
  1010 	};
  1011 
  1012 
  1013 /**
  1014 Active object utility class that can be used to add a data source or data sink to a controller
  1015 plugin asynchronously.  Once the command has been completed, the caller will be notified via the
  1016 MMMFAddDataSourceSinkAsyncObserver interface.
  1017 @since 8.0
  1018 @publishedAll
  1019 @released
  1020 
  1021 */
  1022 class CMMFAddDataSourceSinkAsync : public CActive
  1023 	{
  1024 public:
  1025 
  1026 	IMPORT_C static CMMFAddDataSourceSinkAsync* NewL(MMMFAddDataSourceSinkAsyncObserver& aObs);
  1027     IMPORT_C void AddDataSource(RMMFController& aController, TUid aSourceUid, const TDesC8& aSourceInitData);
  1028 	IMPORT_C void AddFileHandleDataSource(RMMFController& aController, const RFile& aFile);
  1029 	IMPORT_C void AddFileHandleDataSource(RMMFController& aController, const RFile& aFile, const TDesC8& aSourceInitData);
  1030     IMPORT_C void AddDataSink(RMMFController& aController, TUid aSinkUid, const TDesC8& aSinkInitData);
  1031 	IMPORT_C void AddFileHandleDataSink(RMMFController& aController, const RFile& aFile);
  1032 	IMPORT_C void AddFileHandleDataSink(RMMFController& aController, const RFile& aFile, const TDesC8& aSinkInitData);
  1033 
  1034 	~CMMFAddDataSourceSinkAsync();
  1035 
  1036 private:
  1037 	void RunL();
  1038 	void DoCancel();
  1039 	CMMFAddDataSourceSinkAsync(MMMFAddDataSourceSinkAsyncObserver& aObserver);
  1040 private:
  1041 	enum TCurrentAction {EIdle, EAddingDataSource, EAddingDataSink};
  1042 private:
  1043 	MMMFAddDataSourceSinkAsyncObserver& iObserver;
  1044 	TMMFMessageDestinationPckg iHandleInfoPckg;
  1045 	TCurrentAction iCurrentAction;
  1046 	RMMFController* iMMFController;
  1047 	HBufC8* iSourceSinkInitData;
  1048 	TMMFUidPckg iSourceSinkUidPckg;
  1049 	};
  1050 
  1051 #endif