1 mmfcontrollerframework.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 __MMFCONTROLLERFRAMEWORK_H__

    18 #define __MMFCONTROLLERFRAMEWORK_H__

    19 

    20 #include <e32base.h>

    21 #include <e32std.h>

    22 #include <f32file.h>

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

    24 #include <mmf/common/mmfcontrollerframeworkbase.h>

    25 #include <mmf/common/mmfipc.h>

    26 

    27 // fwd ref

    28 class CMMFControllerImplementationInformation;

    29 class CLogonMonitor;

    30 

    31 _LIT(KMMFControllerProxyServerName, "MMFControllerProxyServer-");

    32 

    33 /**

    34 @internalComponent

    35 */

    36 #define KMMFControllerProxyVersion TVersion(7,1,1)

    37 

    38 /**

    39 @internalComponent

    40 */

    41 const TInt KMMFControllerProxyMaxHeapSize = 0x1000000;//16MB

    42 

    43 /**

    44 @internalComponent

    45 */

    46 const TInt KMMFControllerProxyMaxCachedMessages = 10;

    47 

    48 /**

    49 @internalComponent

    50 

    51 Signals that the message is destined for the controller proxy

    52 */

    53 const TInt KMMFObjectHandleControllerProxy = -1;

    54 

    55 /**

    56 @publishedAll

    57 @released

    58 

    59 Signals that the message is destined for the controller

    60 */

    61 const TInt KMMFObjectHandleController = -2;

    62 

    63 /**

    64 @publishedAll

    65 @released

    66 

    67 Null, or invalid, object handle

    68 */

    69 const TInt KMMFObjectHandleNull = 0;

    70 /**

    71 @internalComponent

    72 

    73 The first valid object handle.  The MMF Object container will

    74 begin iterating from here when generating object handles.

    75 */

    76 const TInt KMMFObjectHandleFirstValid = 1;

    77 

    78 /**

    79 @internalComponent

    80 */

    81 const TInt KMmfControllerThreadShutdownTimeout = 20000000;	// 20 seconds

    82 

    83 /**

    84 @internalComponent

    85 

    86 The UID and messages associated with the controller proxy interface.

    87 */

    88 const TUid KUidInterfaceMMFControllerProxy = {0x101F77E7};

    89 

    90 /**

    91 @internalComponent

    92 

    93 Struct to allow RMMFController to pass several parameters to new CControllerProxyServer threads.

    94 */

    95 struct TControllerProxyServerParams 

    96 	{

    97 	RServer2*	iServer;

    98 	TBool		iUsingSharedHeap;

    99 	};

   100 	

   101 

   102 /**

   103 @internalComponent

   104 */

   105 enum TMMFControllerProxyMessages

   106 	{

   107 	EMMFControllerProxyLoadControllerPluginByUid,

   108 	EMMFControllerProxyReceiveEvents,

   109 	EMMFControllerProxyCancelReceiveEvents

   110 	};

   111 

   112 

   113 /**

   114 @publishedAll

   115 @released

   116 

   117 Describes the destination of a message in the controller framework.

   118 

   119 The destination is defined by a UID describing the interface and an integer object handle.

   120 The controller framework uses this information when it receives a message to decide where

   121 to send the message.

   122 

   123 The controller plugin and controller proxy use the special constant handles

   124 KMMFObjectHandleControllerProxy and KMMFObjectHandleController for

   125 efficiency.

   126 

   127 @since 7.0s

   128 */

   129 class TMMFMessageDestination

   130 	{

   131 public:

   132 

   133 	/**

   134 	Default constructor.

   135 	

   136 	Assigns a null UID to the interface, and a null handle to the handle.

   137 

   138 	@since 7.0s

   139 	*/

   140 	IMPORT_C TMMFMessageDestination();

   141 

   142 	/**

   143 	Constructor for sending messages to the controller plugin.

   144 

   145 	Assigns KMMFObjectHandleController to the destination handle.

   146 

   147 	@param  aInterfaceId

   148 	        The UID of the interface of this message destination.

   149 

   150 	@since  7.0s

   151 	*/

   152 	IMPORT_C TMMFMessageDestination(TUid aInterfaceId);

   153 

   154 	/**

   155 	Full constructor.

   156 	

   157 	@param  aInterfaceId

   158 	        The UID of the interface of this message destination.

   159 	@param  aDestinationHandle

   160 	        The handle of the destination object in the controller framework.

   161 

   162 	@since  7.0s

   163 	*/

   164 	IMPORT_C TMMFMessageDestination(TUid aInterfaceId, TInt aDestinationHandle);

   165 

   166 	/**

   167 	Copy constructor.

   168 

   169 	@param  aOther

   170 	        The TMMFMessageDestination object to be copied.

   171 

   172 	@since  7.0s

   173 	*/

   174 	IMPORT_C TMMFMessageDestination(const TMMFMessageDestination& aOther);

   175 

   176 	/**

   177 	Returns the UID of the interface of the message destination.

   178 

   179 	@return	The interface UID.

   180 

   181 	@since 7.0s

   182 	*/

   183 	IMPORT_C TUid InterfaceId() const;

   184 

   185 	/**

   186 	Returns the handle of the destination object in the controller framework.

   187 

   188 	@return	The destination handle.

   189 

   190 	@since 7.0s

   191 	*/

   192 	IMPORT_C TInt DestinationHandle() const;

   193 

   194 	/**

   195 	Compares two destinations.

   196 

   197 	@param  aOther

   198 	        The object to be compared with this object.

   199 

   200 	@return A boolean indicating if the objects are the same. ETrue if the objects are the same, 

   201 	        EFalse if the objects are different.

   202 

   203 	@since 7.0s

   204 	*/

   205 	IMPORT_C TBool operator==(const TMMFMessageDestination& aOther) const;

   206 

   207 private:

   208 	TUid iInterfaceId;

   209 	TInt iDestinationHandle;

   210 	/**

   211 	This member is internal and not intended for use.

   212 	*/

   213 	TInt iReserved1;

   214 	TInt iReserved2;

   215 	TInt iReserved3;

   216 	};

   217 

   218 /**

   219 @publishedAll

   220 @released

   221 

   222 Package buffer for TMMFMessageDestination

   223 */

   224 typedef TPckgBuf<TMMFMessageDestination> TMMFMessageDestinationPckg;

   225 

   226 

   227 /**

   228 @publishedAll

   229 @released

   230 

   231 Encapsulation of an RMessage or an RMessage2 to provide protection to controller plugins

   232 from the changes occurring with secure APIs.

   233 

   234 Adds required destination information to the message so the controller framework

   235 can determine which object the message is for.

   236 

   237 Adds capability to check whether the message has been completed.

   238 

   239 Allows two descriptors to be read from the client, and one descriptor to be copied to the client.

   240 

   241 @see RMMFControllerProxy::SendSync

   242 @see RMMFControllerProxy::SendAsync

   243 

   244 @since 7.0s

   245 */

   246 class TMMFMessage

   247 	{

   248 friend class CMMFControllerProxySession;

   249 friend class CMMFDevSoundSession;

   250 public:

   251 

   252 	/**

   253 	Copy constructor.

   254 	

   255 	A controller plugin should use this to take a copy of the message when it must wait for some

   256 	other event before completing it.

   257 

   258 	@param  aMessage

   259 	        The message object to copy.

   260 

   261 	@since 7.0s

   262 	*/

   263 	IMPORT_C TMMFMessage(const TMMFMessage& aMessage);

   264 

   265 	/**

   266 	Returns the destination of the message.

   267 

   268 	@return	The destination of the message, consisting of a UID defining the interface and the

   269 			handle of the destination object.

   270 

   271 	@since	7.0s

   272 	*/

   273 	IMPORT_C const TMMFMessageDestination& Destination();

   274 

   275 	/**

   276 	Returns an integer describing the function being called. Equivalent to 

   277 	RMessage::Function().

   278 

   279 	@return The function being called over IPC.

   280 

   281 	@see    RMessage::Function()

   282 

   283 	@since  7.0s

   284 	*/

   285 	IMPORT_C TInt Function();

   286 

   287 	/**

   288 	Returns the size of the first descriptor that can be copied over from the client.

   289 	

   290 	Use this to create a descriptor of appropriate size before reading the data from the client.

   291 

   292 	@return	The size of data 1.

   293 	@since	7.0s

   294 	*/

   295 	IMPORT_C TInt SizeOfData1FromClient();

   296 

   297 	/**

   298 	Copy the first descriptor from the client.

   299 	

   300 	@param  aDes

   301 	        A descriptor defining the area of memory into which the data from the client

   302 	        will be copied. Note, the descriptor must be of sufficient size.

   303 

   304 	@return	One of the system-wide error codes. In particular, KErrBadDescriptor will be returned

   305 	        if the client did not provide a valid descriptor.

   306 

   307 	@since  7.0s

   308 	*/

   309 	IMPORT_C TInt ReadData1FromClient(TDes8& aDes);

   310 

   311 	/**

   312 	Copy the first descriptor from the client.

   313 

   314 	This functino can leave with one of the system-wide error codes. In particular, the leave code 

   315 	KErrBadDescriptor will be used if the client did not provide a valid descriptor.

   316 

   317 	@param  aDes

   318 	        A descriptor defining the area of memory into which the data from the client

   319 	        will be copied. Note, the descriptor must be of sufficient size.

   320 

   321 	@since 7.0s

   322 	*/

   323 	IMPORT_C void ReadData1FromClientL(TDes8& aDes);

   324 

   325 

   326 	/**

   327 	Returns the size of the second descriptor that can be copied over from the client.

   328 	

   329 	Use this to create a descriptor of appropriate size before reading the data from the client.

   330 

   331 	@return The size of data 2.

   332 

   333 	@since  7.0s

   334 	*/

   335 	IMPORT_C TInt SizeOfData2FromClient();

   336 

   337 	/**

   338 	Copies the second descriptor from the client.

   339 

   340 	@param  aDes

   341 	        A descriptor defining the area of memory into which the data from the client

   342 	        will be copied. Note, the descriptor must be of sufficient size.

   343 

   344 	@return One of the system-wide error codes. In particular, KErrBadDescriptor will be returned

   345 	        if the client did not provide a valid descriptor.

   346 

   347 	@since  7.0s

   348 	*/

   349 	IMPORT_C TInt ReadData2FromClient(TDes8& aDes);

   350 

   351 	/**

   352 	Copies the second descriptor from the client.

   353 

   354 	This function can leave with one of the system-wide error codes. In particular, the leave code

   355 	KErrBadDescriptor will be used if the client did not provide a valid descriptor.

   356 

   357 	@param  aDes

   358 	        A descriptor defining the area of memory into which the data from the client

   359 	        will be copied. Note, the descriptor must be of sufficient size.

   360 

   361 	@since  7.0s

   362 	*/

   363 	IMPORT_C void ReadData2FromClientL(TDes8& aDes);

   364 

   365 	/**

   366 	Copies data back to the client.

   367 

   368 	@param  aDes

   369 	        The data to be copied back to the client.  Note that the client must

   370 	        have already created a descriptor of sufficient size for the data to be

   371 	        copied into.

   372 

   373 	@return One of the system-wide error codes. In particular, the error code KErrBadDescriptor will 

   374 	        be returned if the client did not provide a valid descriptor.

   375 

   376 	@since  7.0s

   377 	*/

   378 	IMPORT_C TInt WriteDataToClient(const TDesC8& aDes);

   379 

   380 	/**

   381 	Copies the data back to the client.

   382 

   383 	This function can leave with one of the system-wide error codes. In particular, the leave code

   384 	KErrBadDescriptor will be used if the client did not provide a valid descriptor.

   385 

   386 	@param  aDes

   387 	        The data to be copied back to the client. Note that the client must have already

   388 	        created a descriptor of sufficient size for the data to be copied into.

   389 

   390 	@since 7.0s

   391 	*/

   392 	IMPORT_C void WriteDataToClientL(const TDesC8& aDes);

   393 

   394 	/**

   395 	Signals to the client that its request has been completed.

   396 

   397 	Equivalent to RMessage::Complete.

   398 

   399 	@param  aReason

   400 	        The result code to be given back to the client.

   401 

   402 	@since  7.0s

   403 	*/

   404 	IMPORT_C void Complete(TInt aReason);

   405 	

   406 	IMPORT_C void AdoptFileHandleFromClientL(TInt aFsHandleIndex, TInt aFileHandleIndex, RFile& aFile);

   407 

   408 	/**

   409 	Checks whether this message has already been completed.

   410 

   411 	@return A boolean indicating if the message has been completed. ETrue if the message has been 

   412 	        completed, EFalse if not.

   413 

   414 	@since  7.0s

   415 	*/

   416 	IMPORT_C TBool IsCompleted();

   417 

   418 	/**

   419 	Constructs a TMMFMessage from an RMmfIpcMessage.

   420 

   421 	@param	aMessage

   422 			The handle to the remote message.

   423 

   424 	@since  7.0s

   425 	*/

   426 	IMPORT_C TMMFMessage(const RMmfIpcMessage& aMessage);

   427 

   428 	/**

   429 	Gets the destination info from the client.

   430 

   431 	@since  7.0s

   432 	*/

   433 	IMPORT_C void FetchDestinationL();

   434 private:

   435 #ifdef __MMF_USE_IPC_V2__

   436 	/**

   437 	The encapsulated message

   438 	*/

   439 	RMessagePtr2 iMessage;

   440 	/**

   441 	The encapsulated function

   442 	*/

   443 	TInt iFunction;

   444 	/**

   445 	Private padding to preserve BC with earlier versions

   446 	*/

   447 	TInt iDummyPadding[6];

   448 #else

   449 	/**

   450 	The RMessage encapsulated by this object.

   451 	*/

   452 	RMessage iMessage;

   453 #endif // __MMF_USE_IPC_V2__

   454 

   455 	/**

   456 	The destination of this message.

   457 	*/

   458 	TMMFMessageDestination iDestination;

   459 

   460 	/**

   461 	Defines whether this object has yet to be completed.

   462 	*/

   463 	TBool iAmCompleted;

   464 	};

   465 

   466 /**

   467 @internalComponent

   468 

   469 Mixin class used by CLogonMonitor to inform about its state

   470 

   471 @since 9.3

   472 */

   473 class MLogonMonitorObserver

   474 	{

   475 public:

   476 	/**

   477 	The monitored thread has been terminated.

   478 	*/

   479 	virtual void ThreadTerminated() = 0;

   480 	};

   481 	

   482 /**

   483 @internalComponent

   484 

   485 RSessionBase-based client class to handle the creation of the controller thread and

   486 message sending over IPC.

   487 

   488 The controller proxy is responsible for sending and recieving messages over IPC; it does not

   489 care exactly what those messages are.

   490 

   491 Note the fact that, although this is an internal component, its size cannot be changed because 

   492 it's embedded in a publishedAll class (RMMFController) and the size of the latter would also be

   493 changed raising a binary compatibility problem.

   494 

   495 @since 7.0s

   496 */

   497 NONSHARABLE_CLASS(RMMFControllerProxy) : public RMmfSessionBase, public MLogonMonitorObserver

   498 	{

   499 public:

   500 

   501 	/**

   502 	Constructor.

   503 	@since 7.0s

   504 	*/

   505 	IMPORT_C RMMFControllerProxy();

   506 

   507 	/**

   508 	Create a new thread and load a controller plugin into that thread.

   509 	

   510 	@param  aControllerUid

   511 	        The UID of the controller plugin to be loaded.

   512 	@param	aUseSharedHeap

   513 			If this value is EFalse each controller is created with its own heap. The alternative,

   514 			if the value is ETrue, is that controllers share a special heap with other controllers

   515 			created the same way. Each heap uses a chunk, so this avoids situations where the

   516 			number of chunks per process is limited. The default behaviour is generally to be

   517 			preferred, and should give lower overall memory usage. However, if many controllers are

   518 			to be created for a particular thread, then ETrue should be provided to prevent running

   519 			out of heaps or chunks.

   520 

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

   522 	@since	7.0s

   523 	*/

   524 	IMPORT_C TInt LoadController(TUid aControllerUid, TBool aUseSharedHeap);

   525 

   526 	/**

   527 	Create a new thread and load a controller plugin into that thread.

   528 	

   529 	@param  aControllerInfo

   530 	        A reference to a CMMFControllerImplementationInformation object

   531 	        used for determining the controller UID and heap size

   532 	@param	aUseSharedHeap

   533 			If this value is EFalse each controller is created with its own heap. The alternative,

   534 			if the value is ETrue, is that controllers share a special heap with other controllers

   535 			created the same way. Each heap uses a chunk, so this avoids situations where the

   536 			number of chunks per process is limited. The default behaviour is generally to be

   537 			preferred, and should give lower overall memory usage. However, if many controllers are

   538 			to be created for a particular thread, then ETrue should be provided to prevent running

   539 			out of heaps or chunks.

   540 

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

   542 	@since	7.0s

   543 	*/

   544 	IMPORT_C TInt LoadController(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap);

   545 

   546 	/**

   547 	Create a new thread in another process through Secure DRM Plugin server and load a controller plugin 

   548 	into that thread.  The motivation of this model is to allow applications without DRM capability able 

   549 	to play protected content through MMF.

   550 	

   551 	@param  aControllerUid

   552 	        The UID of the controller plugin to be loaded.

   553 	@param	aUseSharedHeap

   554 			If this value is EFalse each controller is created with its own heap. The alternative,

   555 			if the value is ETrue, is that controllers share a special heap with other controllers

   556 			created the same way. Each heap uses a chunk, so this avoids situations where the

   557 			number of chunks per process is limited. The default behaviour is generally to be

   558 			preferred, and should give lower overall memory usage. However, if many controllers are

   559 			to be created for a particular thread, then ETrue should be provided to prevent running

   560 			out of heaps or chunks.

   561 

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

   563 	*/

   564 	IMPORT_C TInt LoadControllerInSecureDRMProcess(TUid aControllerUid, TBool aUseSharedHeap);

   565 	

   566 	/**

   567 	Create a new thread in another process through Secure DRM Plugin server and load a controller plugin 

   568 	into that thread.  The motivation of this model is to allow applications without DRM capability able 

   569 	to play protected content through MMF.

   570 	

   571 	@param  aControllerInfo

   572 	        A reference to a CMMFControllerImplementationInformation object

   573 	        used for determining the controller UID and heap size

   574 	@param	aUseSharedHeap

   575 			If this value is EFalse each controller is created with its own heap. The alternative,

   576 			if the value is ETrue, is that controllers share a special heap with other controllers

   577 			created the same way. Each heap uses a chunk, so this avoids situations where the

   578 			number of chunks per process is limited. The default behaviour is generally to be

   579 			preferred, and should give lower overall memory usage. However, if many controllers are

   580 			to be created for a particular thread, then ETrue should be provided to prevent running

   581 			out of heaps or chunks.

   582 

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

   584 	*/

   585 	IMPORT_C TInt LoadControllerInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap);

   586 	

   587 	/**

   588 	Delete the controller plugin and close its thread.

   589 	

   590 	Clients must call Close() on the controller proxy, otherwise leaks will occur.

   591 

   592 	@since	7.0s

   593 	*/

   594 	IMPORT_C void Close();

   595 

   596 	/**

   597 	Send a message synchronously to the controller thread.

   598 

   599 	The controller framework will analyze the message to determine its correct destination.

   600 

   601 	Note: This method will not return until the controller framework has serviced the command.

   602 

   603 	@param  aDestination

   604 	        The destination of the message, consisting of the uid of

   605 	        the interface of this message.

   606 	@param  aFunction

   607 	        The function number to indicate which function is to be called

   608 	        on the interface defined in the aDestination parameter.

   609 	@param  aDataTo1

   610 	        A reference to the first chunk of data to be copied to the controller

   611 	        framework. The exact contents of the data are dependent on the

   612 	        interface being called.  Can be NULL.

   613 	@param  aDataTo2

   614 	        A reference to the second chunk of data to be copied to the controller

   615 	        framework. The exact contents of the data are dependent on the

   616 	        interface being called.  Can be NULL.

   617 	@param  aDataFrom

   618 	        A reference to an area of memory to which the controller framework will

   619 	        write any data to be passed back to the client.  Can't be NULL.

   620 

   621 	@return The result of the request.  Exact range of values is dependent on the interface.

   622 	@since	7.0s

   623 	*/

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

   625 

   626 	/**

   627 	Send a message synchronously to the controller thread.

   628 

   629 	The controller framework will analyze the message to determine its correct destination.

   630 

   631 	Note: This method will not return until the controller framework has serviced the command.

   632 

   633 	@param  aDestination

   634 	        The destination of the message, consisting of the uid of

   635 	        the interface of this message.

   636 	@param  aFunction

   637 	        The function number to indicate which function is to be called

   638 	        on the interface defined in the aDestination parameter.

   639 	@param  aDataTo1

   640 	        A reference to the first chunk of data to be copied to the controller

   641 	        framework. The exact contents of the data are dependent on the

   642 	        interface being called.  Can be NULL.

   643 	@param  aDataTo2

   644 	        A reference to the second chunk of data to be copied to the controller

   645 	        framework. The exact contents of the data are dependent on the

   646 	        interface being called.  Can be NULL.

   647 

   648 	@return The result of the request.  Exact range of values is dependent on the interface.

   649 	@since	7.0s

   650 	*/

   651 	IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2) const;

   652 

   653 	/**

   654 	Send a message asynchronously to the controller thread.

   655 	

   656 	The controller framework will analyze the message to determine its correct destination.

   657 

   658 	Note: This method will return immediately.  The RunL of the active object owning the

   659 	aStatus parameter will be called when the command is completed by the

   660 	controller framework.

   661 

   662 	@param  aDestination

   663 	        The destination of the message, consisting of the uid of

   664 	        the interface of this message.

   665 	@param  aFunction

   666 	        The function number to indicate which function is to be called

   667 	        on the interface defined in the aDestination parameter.

   668 	@param  aDataTo1

   669 	        A reference to the first chunk of data to be copied to the controller

   670 	        framework. The exact contents of the data are dependent on the

   671 	        interface being called.  Can be NULL.

   672 	@param  aDataTo2

   673 	        A reference to the second chunk of data to be copied to the controller

   674 	        framework. The exact contents of the data are dependent on the

   675 	        interface being called.  Can be NULL.

   676 	@param  aDataFrom

   677 	        A reference to an area of memory to which the controller framework will

   678 	        write any data to be passed back to the client.  Can't be NULL.

   679 	@param  aStatus

   680 	        The TRequestStatus of an active object.  This will contain the

   681 	        result of the request on completion.  The exact range of

   682 	        result values is dependent on the interface.

   683 

   684 	@since	7.0s

   685 	*/

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

   687 

   688 	/**

   689 	Send a message asynchronously to the controller thread.

   690 	

   691 	The controller framework will analyze the message to determine its correct destination.

   692 	

   693 	Note: This method will return immediately.  The RunL of the active object owning the 

   694 	aStatus parameter will be called when the command is completed by the

   695 	controller framework.

   696 

   697 	@param  aDestination

   698 	        The destination of the message, consisting of the uid of

   699 	        the interface of this message.

   700 	@param  aFunction

   701 	        The function number to indicate which function is to be called

   702 	        on the interface defined in the aDestination parameter.

   703 	@param  aDataTo1

   704 	        A reference to the first chunk of data to be copied to the controller

   705 	        framework. The exact contents of the data are dependent on the

   706 	        interface being called.  Can be NULL.

   707 	@param  aDataTo2

   708 	        A reference to the second chunk of data to be copied to the controller

   709 	        framework. The exact contents of the data are dependent on the

   710 	        interface being called.  Can be NULL.

   711 	@param  aStatus

   712 	        The TRequestStatus of an active object.  This will contain the

   713 	        result of the request on completion.  The exact range of

   714 	        result values is dependent on the interface.

   715 

   716 	@since	7.0s

   717 	*/

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

   719 

   720 	IMPORT_C TInt SendSync(TInt aFunction, const TIpcArgs& aIpcArgs) const;

   721 	IMPORT_C void SendAsync(TInt aFunction, const TIpcArgs& aIpcArgs, TRequestStatus& aStatus) const;

   722 	/**

   723 	Register to receive events from the controller framework.

   724 	

   725 	Events can be generated at any time, and are generally associated with things that occur

   726 	due to something happening internally within the controller. For example, an event will

   727 	be generated if the controller stops playing due to reaching the end of a file.

   728 

   729 	@param  aEvent

   730 	        A reference to a TMMFEventPckg object that must be member data

   731 	        of the active object calling this method.  The details of the event

   732 	        will be copied into this object when an event occurs.

   733 	@param  aStatus

   734 	        The TRequestStatus of the active object calling this method.

   735 

   736 	@see	TMMFEvent

   737 	@see	CMMFControllerEventMonitor

   738 	@since	7.0s

   739 	*/

   740 	IMPORT_C void ReceiveEvents(TMMFEventPckg& aEvent, TRequestStatus& aStatus);

   741 

   742 	/**

   743 	Cancel a previous registration to receive events from the controller framework.

   744 

   745 	This must be called from the DoCancel() method of the active object using the

   746 	ReceiveEvents() API.

   747 

   748 	@return One of the standard system-wide error codes.

   749 

   750 	@see	TMMFEvent

   751 	@since	7.0s

   752 	*/

   753 	IMPORT_C TInt CancelReceiveEvents();

   754 	

   755 	/**

   756 	Set the priority of the controller's sub thread.

   757 	

   758 	This can be used to increase the responsiveness of the audio plugin to minimise

   759 	any lag in processing. This function should be used with care as it may have knock-on

   760 	effects elsewhere in the system.

   761 	

   762 	@param	aPriority

   763 			The TThreadPriority that the thread should run under.  The default is EPriorityNormal.

   764 	@return	TInt

   765 			A standard error code: KErrNone if successful, KErrNotReady if the thread does not have a

   766 			valid handle.

   767 	*/

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

   769 	

   770 	/**

   771 	The controller subthread has been terminated.

   772 	

   773 	This is called by CLogonMonitor when the the thread terminates

   774 	*/

   775 	void ThreadTerminated();

   776 private:

   777 	/**

   778 	Creates the new thread

   779 	*/

   780 	TInt DoCreateSubThread(RServer2* aServer2, TUint aMaxHeapSize, TBool aUseSharedHeap);

   781 

   782 	/**

   783 	Determines the maximum heap size required by the selected controller

   784 	*/

   785 	TUint ControllersMaxHeapSizeL(TUid aControllerUid);

   786 

   787 	/**

   788 	Load a controller by UID

   789 	

   790 	@param  aControllerUid

   791 	        The UID of the controller plugin to be loaded.

   792 	@param  aControllerInfo

   793 	        A reference to a CMMFControllerImplementationInformation object

   794 	        used for determining the heap size and DRM server supporting state.

   795 	@param	aUseSharedHeap

   796 			If this value is EFalse each controller is created with its own heap. The alternative,

   797 			if the value is ETrue, is that controllers share a special heap with other controllers

   798 			created the same way. Each heap uses a chunk, so this avoids situations where the

   799 			number of chunks per process is limited. The default behaviour is generally to be

   800 			preferred, and should give lower overall memory usage. However, if many controllers are

   801 			to be created for a particular thread, then ETrue should be provided to prevent running

   802 			out of heaps or chunks.

   803 	@param	aNoDRMCap

   804 			The indicator supplied from user used to determine whether the user's process has DRM 

   805 			capability

   806 	@return	TInt

   807 			One of the system-wide error codes.

   808 	*/

   809 	TInt LoadController(TUid aControllerUid, const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap,

   810 						TBool aNoDRMCap = EFalse);

   811 	

   812 	/**

   813 	Release heap - for use when a shared heap has been registered

   814 	*/

   815 	void ReleaseHeap();

   816 

   817 	/**

   818 	Create a session to handle situation of playing DRM protected content in

   819 	process with no DRM capability.

   820 	DRM server process will be created, if not yet created. This server is responsible to

   821 	manage and monitor all the MMF Controller servers created as seperate threads belong to 

   822 	DRM server process. Once the new MMF Controller server is running, a MMF Controller server 

   823 	session will be created and the handle is passing back.

   824 	*/

   825 	TInt DoCreateSessionForNoDRMCapClient(TUint aMaxHeapSize, TBool aUseSharedHeap);

   826 	

   827 private:

   828 	enum

   829 		{

   830 		/**

   831 		Shared heap has been opened for this object, and must be closed

   832 		*/

   833 		EFlagOpenedSharedHeap=0x01	

   834 		};

   835 

   836 private:

   837 	/**

   838 	The thread in which the controller plugin will run.

   839 	*/

   840 	RThread iSubThread;

   841 	/**

   842 	Used to hold destination for messages from the controller proxy

   843 	(not from clients calling SendSync/SendAsync!!)

   844 	*/

   845 	TMMFMessageDestinationPckg iDestinationPckg;

   846 	/**

   847 	Used to determine the success of a logon.  If the status is not pending, the logon has failed

   848 	and the thread should be closed.

   849 	*/

   850 	CLogonMonitor* iLogonAO;

   851 	/**

   852 	The priority at which the controller plugin thread runs.

   853 	*/

   854 	TThreadPriority iThreadPriority;

   855 	/**

   856 	Flags field

   857 	*/

   858 	TInt iFlags;	

   859 	/**

   860 	This member is internal and not intended for use.

   861 	*/

   862 	TInt iReserved1;

   863 	};

   864 

   865 /**

   866 @internalComponent

   867 

   868 Used to Kill the controller thread either immediately or after a timeout.

   869 Used by the controller thread on startup to prevent orphaning if no sessions are created to it.

   870 */

   871 class CMMFControllerProxyShutdown : public CTimer

   872 	{

   873 	enum {EMMFControllerProxyShutdownDelay=1000000};	// 1s

   874 public:

   875 

   876 	/**

   877 	Create a new shutdown timer.

   878 

   879 	This method can leave with one of the system-wide error codes.

   880 

   881 	@since 7.0s

   882 	*/

   883 	static CMMFControllerProxyShutdown* NewL();

   884 

   885 	/**

   886 	Start the shutdown timer.  The RunL of this active object will be called after

   887 	EMMFControllerProxyShutdownDelay microseconds.

   888 

   889 	@since 7.0s

   890 	*/

   891 	void Start();

   892 

   893 	/**

   894 	Shut down the controller thread immediately.

   895 	

   896 	Calls CActiveScheduler::Stop().

   897 

   898 	@since 7.0s

   899 	*/

   900 	void ShutdownNow();

   901 private:

   902 	CMMFControllerProxyShutdown();

   903 	void ConstructL();

   904 

   905 	/**

   906 	Calls ShutdownNow().

   907 

   908 	@since 7.0s

   909 	*/

   910 	void RunL();

   911 	};

   912 

   913 

   914 /**

   915 @publishedAll

   916 @released

   917 

   918 Mixin class to define an object capable of handling an event within the controller framework.

   919 */

   920 class MAsyncEventHandler

   921 	{

   922 public:

   923 

   924 	/**

   925 	Sends an event to the client.

   926 

   927 	@param  aEvent

   928 	        The event.

   929 

   930 	@since 7.0s

   931 	*/

   932 	virtual TInt SendEventToClient(const TMMFEvent& aEvent) = 0;

   933 	};

   934 

   935 /**

   936 @internalComponent

   937 

   938 Used to hold on to an TMMFMessage so we can complete it asynchronously to 

   939 send an event to the client.

   940 

   941 @since 7.0s

   942 */

   943 class CMMFEventReceiver : public CBase

   944 	{

   945 public:

   946 

   947 	/**

   948 	Constructs a new event receiver.

   949 	

   950 	This method may leave with one of the system-wide error codes.

   951 

   952 	@param  aMessage

   953 	        The message to be completed when an event occurs.

   954 

   955 	@return A pointer to the newly created event receiver.

   956 

   957 	@since  7.0s

   958 	*/

   959 	static CMMFEventReceiver* NewL(const TMMFMessage& aMessage);

   960 

   961 	/**

   962 	Destructor.

   963 

   964 	Completes the message with KErrCancel if the message hasn't already been completed.

   965 

   966 	@since 7.0s

   967 	*/

   968 	~CMMFEventReceiver();

   969 

   970 	/**

   971 	Sends an event to the client.

   972 

   973 	@param  aEvent

   974 	        The event.

   975 

   976 	@since  7.0s

   977 	*/

   978 	void SendEvent(const TMMFEvent& aEvent);

   979 private:

   980 

   981 	/**

   982 	Constructor.

   983 

   984 	@param  aMessage

   985 	        The message to be completed when an event occurs.

   986 

   987 	@since  7.0s

   988 	*/

   989 	CMMFEventReceiver(const TMMFMessage& aMessage);

   990 private:

   991 	/** 

   992 	The message to be completed when an event occurs.

   993 	*/

   994 	TMMFMessage iMessage;

   995 	};

   996 

   997 

   998 

   999 /**

  1000 @internalComponent

  1001 

  1002 The controller proxy server.

  1003 

  1004 The main server inside the controller thread, responsible for creating and destroying the single

  1005 session used to transmit messages from the client to the server.

  1006 

  1007 Every controller plugin runs in its own thread, and has its own controller proxy server.

  1008 

  1009 @since 7.0s

  1010 */

  1011 class CMMFControllerProxyServer : public CMmfIpcServer

  1012 	{

  1013 public:

  1014 	/**

  1015 	Construct the server.

  1016 

  1017 	This method may leave with one of the system-wide error codes.

  1018 

  1019 	@return The newly created server.

  1020 

  1021 	@since  7.0s

  1022 	*/

  1023 	static CMMFControllerProxyServer* NewL(RServer2* aServer2 );

  1024 

  1025 	/**

  1026 	Destructor.

  1027 

  1028 	@since 7.0s

  1029 	*/

  1030 	~CMMFControllerProxyServer();

  1031 

  1032 	/**

  1033 	Static thread function.

  1034 

  1035 	The address of this function is passed into RThread::Create.

  1036 

  1037 	Unpackages the startup parameters and calls DoStartThreadL().

  1038 

  1039 	@param  aAny

  1040 	        A pointer to the packaged startup parameters.

  1041 

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

  1043 

  1044 	@since 7.0s

  1045 	*/

  1046 	IMPORT_C static TInt StartThread(TAny* aParam);

  1047 

  1048 	/**

  1049 	Called by the active scheduler when the ServiceL of the session leaves.

  1050 	Completes the message with the error and restarts the server.

  1051 

  1052 	@param  aError

  1053 	        The error that the session ServiceL left with.

  1054 

  1055 	@return  KErrNone

  1056 	@since 7.0s

  1057 	*/

  1058 	TInt RunError(TInt aError);

  1059 

  1060 	/**

  1061 	Signals that the session has been created.

  1062 

  1063 	Stops the shutdown timer.

  1064 

  1065 	@since 7.0s

  1066 	*/

  1067 	void SessionCreated();

  1068 

  1069 	/**

  1070 	Signals that the session has been destroyed.

  1071 	Causes the server to shut down immediately.

  1072 

  1073 	@since 7.0s

  1074 	*/

  1075 	void SessionDestroyed();

  1076 private:

  1077 

  1078 	/**

  1079 	Thread startup code.

  1080 

  1081 	Creates the cleanup stack, installs the active scheduler and creates the server.

  1082 	Once all this is completed successfully, it signals the success back to the client.

  1083 

  1084 	This function may leave with one of the system-wide error codes.

  1085 

  1086 	@param  aParams

  1087 	        Used to signal startup success back to the client.

  1088 

  1089 	@since 7.0s

  1090 	*/

  1091 	static void DoStartThreadL(TAny* aParam);

  1092 

  1093 	/**

  1094 	Creates a new session.  Only one session may be created with the ControllerProxyServer.

  1095 

  1096 	This function may leave with one of the system-wide error codes.

  1097 

  1098 	@param  aVersion

  1099 	        The version number of the session.

  1100 

  1101 	@return A pointer to the new session.

  1102 

  1103 	@since 7.0s

  1104 	*/

  1105 	CMmfIpcSession* NewSessionL(const TVersion& aVersion) const;

  1106 

  1107 	/** 

  1108 	Constructor.

  1109 

  1110 	@since 7.0s

  1111 	*/

  1112 	CMMFControllerProxyServer();

  1113 

  1114 	/**

  1115 	Second phase constructor.

  1116 

  1117 	@since 7.0s

  1118 	*/

  1119 	void ConstructL(RServer2* aServer2);

  1120 	

  1121 	/**

  1122 	Renaming Controller Proxy Server name

  1123 	

  1124 	@since 9.2

  1125 	*/

  1126 	static void RenameControllerProxyThread();

  1127 

  1128 private:

  1129 	/** 

  1130 	The timer used to shut down the server in case the client fails to connect a session.

  1131 	*/

  1132 	CMMFControllerProxyShutdown* iShutdownTimer;

  1133 	/** 

  1134 	Indicates whether we have a session connected.  Only one session is allowed to connect to the server.