epoc32/include/mmf/common/mmfcontrollerframework.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
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 __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 @publishedAll
    35 @released
    36 
    37 Signals that the message is destined for the controller
    38 */
    39 const TInt KMMFObjectHandleController = -2;
    40 
    41 /**
    42 @publishedAll
    43 @released
    44 
    45 Null, or invalid, object handle
    46 */
    47 const TInt KMMFObjectHandleNull = 0;
    48 
    49 /**
    50 @publishedAll
    51 @released
    52 
    53 Describes the destination of a message in the controller framework.
    54 
    55 The destination is defined by a UID describing the interface and an integer object handle.
    56 The controller framework uses this information when it receives a message to decide where
    57 to send the message.
    58 
    59 The controller plugin and controller proxy use the special constant handles
    60 KMMFObjectHandleControllerProxy and KMMFObjectHandleController for
    61 efficiency.
    62 
    63 @since 7.0s
    64 */
    65 class TMMFMessageDestination
    66 	{
    67 public:
    68 
    69 	/**
    70 	Default constructor.
    71 	
    72 	Assigns a null UID to the interface, and a null handle to the handle.
    73 
    74 	@since 7.0s
    75 	*/
    76 	IMPORT_C TMMFMessageDestination();
    77 
    78 	/**
    79 	Constructor for sending messages to the controller plugin.
    80 
    81 	Assigns KMMFObjectHandleController to the destination handle.
    82 
    83 	@param  aInterfaceId
    84 	        The UID of the interface of this message destination.
    85 
    86 	@since  7.0s
    87 	*/
    88 	IMPORT_C TMMFMessageDestination(TUid aInterfaceId);
    89 
    90 	/**
    91 	Full constructor.
    92 	
    93 	@param  aInterfaceId
    94 	        The UID of the interface of this message destination.
    95 	@param  aDestinationHandle
    96 	        The handle of the destination object in the controller framework.
    97 
    98 	@since  7.0s
    99 	*/
   100 	IMPORT_C TMMFMessageDestination(TUid aInterfaceId, TInt aDestinationHandle);
   101 
   102 	/**
   103 	Copy constructor.
   104 
   105 	@param  aOther
   106 	        The TMMFMessageDestination object to be copied.
   107 
   108 	@since  7.0s
   109 	*/
   110 	IMPORT_C TMMFMessageDestination(const TMMFMessageDestination& aOther);
   111 
   112 	/**
   113 	Returns the UID of the interface of the message destination.
   114 
   115 	@return	The interface UID.
   116 
   117 	@since 7.0s
   118 	*/
   119 	IMPORT_C TUid InterfaceId() const;
   120 
   121 	/**
   122 	Returns the handle of the destination object in the controller framework.
   123 
   124 	@return	The destination handle.
   125 
   126 	@since 7.0s
   127 	*/
   128 	IMPORT_C TInt DestinationHandle() const;
   129 
   130 	/**
   131 	Compares two destinations.
   132 
   133 	@param  aOther
   134 	        The object to be compared with this object.
   135 
   136 	@return A boolean indicating if the objects are the same. ETrue if the objects are the same, 
   137 	        EFalse if the objects are different.
   138 
   139 	@since 7.0s
   140 	*/
   141 	IMPORT_C TBool operator==(const TMMFMessageDestination& aOther) const;
   142 
   143 private:
   144 	TUid iInterfaceId;
   145 	TInt iDestinationHandle;
   146 	/**
   147 	This member is internal and not intended for use.
   148 	*/
   149 	TInt iReserved1;
   150 	TInt iReserved2;
   151 	TInt iReserved3;
   152 	};
   153 
   154 /**
   155 @publishedAll
   156 @released
   157 
   158 Package buffer for TMMFMessageDestination
   159 */
   160 typedef TPckgBuf<TMMFMessageDestination> TMMFMessageDestinationPckg;
   161 
   162 
   163 /**
   164 @publishedAll
   165 @released
   166 
   167 Encapsulation of an RMessage or an RMessage2 to provide protection to controller plugins
   168 from the changes occurring with secure APIs.
   169 
   170 Adds required destination information to the message so the controller framework
   171 can determine which object the message is for.
   172 
   173 Adds capability to check whether the message has been completed.
   174 
   175 Allows two descriptors to be read from the client, and one descriptor to be copied to the client.
   176 
   177 @see RMMFControllerProxy::SendSync
   178 @see RMMFControllerProxy::SendAsync
   179 
   180 @since 7.0s
   181 */
   182 class TMMFMessage
   183 	{
   184 friend class CMMFControllerProxySession;
   185 friend class CMMFDevSoundSession;
   186 public:
   187 
   188 	/**
   189 	Copy constructor.
   190 	
   191 	A controller plugin should use this to take a copy of the message when it must wait for some
   192 	other event before completing it.
   193 
   194 	@param  aMessage
   195 	        The message object to copy.
   196 
   197 	@since 7.0s
   198 	*/
   199 	IMPORT_C TMMFMessage(const TMMFMessage& aMessage);
   200 
   201 	/**
   202 	Returns the destination of the message.
   203 
   204 	@return	The destination of the message, consisting of a UID defining the interface and the
   205 			handle of the destination object.
   206 
   207 	@since	7.0s
   208 	*/
   209 	IMPORT_C const TMMFMessageDestination& Destination();
   210 
   211 	/**
   212 	Returns an integer describing the function being called. Equivalent to 
   213 	RMessage::Function().
   214 
   215 	@return The function being called over IPC.
   216 
   217 	@see    RMessage::Function()
   218 
   219 	@since  7.0s
   220 	*/
   221 	IMPORT_C TInt Function();
   222 
   223 	/**
   224 	Returns the size of the first descriptor that can be copied over from the client.
   225 	
   226 	Use this to create a descriptor of appropriate size before reading the data from the client.
   227 
   228 	@return	The size of data 1.
   229 	@since	7.0s
   230 	*/
   231 	IMPORT_C TInt SizeOfData1FromClient();
   232 
   233 	/**
   234 	Copy the first descriptor from the client.
   235 	
   236 	@param  aDes
   237 	        A descriptor defining the area of memory into which the data from the client
   238 	        will be copied. Note, the descriptor must be of sufficient size.
   239 
   240 	@return	One of the system-wide error codes. In particular, KErrBadDescriptor will be returned
   241 	        if the client did not provide a valid descriptor.
   242 
   243 	@since  7.0s
   244 	*/
   245 	IMPORT_C TInt ReadData1FromClient(TDes8& aDes);
   246 
   247 	/**
   248 	Copy the first descriptor from the client.
   249 
   250 	This functino can leave with one of the system-wide error codes. In particular, the leave code 
   251 	KErrBadDescriptor will be used if the client did not provide a valid descriptor.
   252 
   253 	@param  aDes
   254 	        A descriptor defining the area of memory into which the data from the client
   255 	        will be copied. Note, the descriptor must be of sufficient size.
   256 
   257 	@since 7.0s
   258 	*/
   259 	IMPORT_C void ReadData1FromClientL(TDes8& aDes);
   260 
   261 
   262 	/**
   263 	Returns the size of the second descriptor that can be copied over from the client.
   264 	
   265 	Use this to create a descriptor of appropriate size before reading the data from the client.
   266 
   267 	@return The size of data 2.
   268 
   269 	@since  7.0s
   270 	*/
   271 	IMPORT_C TInt SizeOfData2FromClient();
   272 
   273 	/**
   274 	Copies the second descriptor from the client.
   275 
   276 	@param  aDes
   277 	        A descriptor defining the area of memory into which the data from the client
   278 	        will be copied. Note, the descriptor must be of sufficient size.
   279 
   280 	@return One of the system-wide error codes. In particular, KErrBadDescriptor will be returned
   281 	        if the client did not provide a valid descriptor.
   282 
   283 	@since  7.0s
   284 	*/
   285 	IMPORT_C TInt ReadData2FromClient(TDes8& aDes);
   286 
   287 	/**
   288 	Copies the second descriptor from the client.
   289 
   290 	This function can leave with one of the system-wide error codes. In particular, the leave code
   291 	KErrBadDescriptor will be used if the client did not provide a valid descriptor.
   292 
   293 	@param  aDes
   294 	        A descriptor defining the area of memory into which the data from the client
   295 	        will be copied. Note, the descriptor must be of sufficient size.
   296 
   297 	@since  7.0s
   298 	*/
   299 	IMPORT_C void ReadData2FromClientL(TDes8& aDes);
   300 
   301 	/**
   302 	Copies data back to the client.
   303 
   304 	@param  aDes
   305 	        The data to be copied back to the client.  Note that the client must
   306 	        have already created a descriptor of sufficient size for the data to be
   307 	        copied into.
   308 
   309 	@return One of the system-wide error codes. In particular, the error code KErrBadDescriptor will 
   310 	        be returned if the client did not provide a valid descriptor.
   311 
   312 	@since  7.0s
   313 	*/
   314 	IMPORT_C TInt WriteDataToClient(const TDesC8& aDes);
   315 
   316 	/**
   317 	Copies the data back to the client.
   318 
   319 	This function can leave with one of the system-wide error codes. In particular, the leave code
   320 	KErrBadDescriptor will be used if the client did not provide a valid descriptor.
   321 
   322 	@param  aDes
   323 	        The data to be copied back to the client. Note that the client must have already
   324 	        created a descriptor of sufficient size for the data to be copied into.
   325 
   326 	@since 7.0s
   327 	*/
   328 	IMPORT_C void WriteDataToClientL(const TDesC8& aDes);
   329 
   330 	/**
   331 	Signals to the client that its request has been completed.
   332 
   333 	Equivalent to RMessage::Complete.
   334 
   335 	@param  aReason
   336 	        The result code to be given back to the client.
   337 
   338 	@since  7.0s
   339 	*/
   340 	IMPORT_C void Complete(TInt aReason);
   341 	
   342 	IMPORT_C void AdoptFileHandleFromClientL(TInt aFsHandleIndex, TInt aFileHandleIndex, RFile& aFile);
   343 
   344 	/**
   345 	Checks whether this message has already been completed.
   346 
   347 	@return A boolean indicating if the message has been completed. ETrue if the message has been 
   348 	        completed, EFalse if not.
   349 
   350 	@since  7.0s
   351 	*/
   352 	IMPORT_C TBool IsCompleted();
   353 
   354 	/**
   355 	Constructs a TMMFMessage from an RMmfIpcMessage.
   356 
   357 	@param	aMessage
   358 			The handle to the remote message.
   359 
   360 	@since  7.0s
   361 	*/
   362 	IMPORT_C TMMFMessage(const RMmfIpcMessage& aMessage);
   363 
   364 	/**
   365 	Gets the destination info from the client.
   366 
   367 	@since  7.0s
   368 	*/
   369 	IMPORT_C void FetchDestinationL();
   370 private:
   371 #ifdef __MMF_USE_IPC_V2__
   372 	/**
   373 	The encapsulated message
   374 	*/
   375 	RMessagePtr2 iMessage;
   376 	/**
   377 	The encapsulated function
   378 	*/
   379 	TInt iFunction;
   380 	/**
   381 	Private padding to preserve BC with earlier versions
   382 	*/
   383 	TInt iDummyPadding[6];
   384 #else
   385 	/**
   386 	The RMessage encapsulated by this object.
   387 	*/
   388 	RMessage iMessage;
   389 #endif // __MMF_USE_IPC_V2__
   390 
   391 	/**
   392 	The destination of this message.
   393 	*/
   394 	TMMFMessageDestination iDestination;
   395 
   396 	/**
   397 	Defines whether this object has yet to be completed.
   398 	*/
   399 	TBool iAmCompleted;
   400 	};
   401 
   402 /**
   403 @publishedAll
   404 
   405 Mixin class used by CLogonMonitor to inform about its state
   406 
   407 @since 9.3
   408 */
   409 class MLogonMonitorObserver
   410 	{
   411 public:
   412 	/**
   413 	The monitored thread has been terminated.
   414 	*/
   415 	virtual void ThreadTerminated() = 0;
   416 	};
   417 	
   418 /**
   419 @publishedAll
   420 
   421 RSessionBase-based client class to handle the creation of the controller thread and
   422 message sending over IPC.
   423 
   424 The controller proxy is responsible for sending and recieving messages over IPC; it does not
   425 care exactly what those messages are.
   426 
   427 Note the fact that, although this is an internal component, its size cannot be changed because 
   428 it's embedded in a publishedAll class (RMMFController) and the size of the latter would also be
   429 changed raising a binary compatibility problem.
   430 
   431 @since 7.0s
   432 */
   433 NONSHARABLE_CLASS(RMMFControllerProxy) : public RMmfSessionBase, public MLogonMonitorObserver
   434 	{
   435 public:
   436 
   437 	/**
   438 	Constructor.
   439 	@since 7.0s
   440 	*/
   441 	IMPORT_C RMMFControllerProxy();
   442 
   443 	/**
   444 	Create a new thread and load a controller plugin into that thread.
   445 	
   446 	@param  aControllerUid
   447 	        The UID of the controller plugin to be loaded.
   448 	@param	aUseSharedHeap
   449 			If this value is EFalse each controller is created with its own heap. The alternative,
   450 			if the value is ETrue, is that controllers share a special heap with other controllers
   451 			created the same way. Each heap uses a chunk, so this avoids situations where the
   452 			number of chunks per process is limited. The default behaviour is generally to be
   453 			preferred, and should give lower overall memory usage. However, if many controllers are
   454 			to be created for a particular thread, then ETrue should be provided to prevent running
   455 			out of heaps or chunks.
   456 
   457 	@return One of the system-wide error codes.
   458 	@since	7.0s
   459 	*/
   460 	IMPORT_C TInt LoadController(TUid aControllerUid, TBool aUseSharedHeap);
   461 
   462 	/**
   463 	Create a new thread and load a controller plugin into that thread.
   464 	
   465 	@param  aControllerInfo
   466 	        A reference to a CMMFControllerImplementationInformation object
   467 	        used for determining the controller UID and heap size
   468 	@param	aUseSharedHeap
   469 			If this value is EFalse each controller is created with its own heap. The alternative,
   470 			if the value is ETrue, is that controllers share a special heap with other controllers
   471 			created the same way. Each heap uses a chunk, so this avoids situations where the
   472 			number of chunks per process is limited. The default behaviour is generally to be
   473 			preferred, and should give lower overall memory usage. However, if many controllers are
   474 			to be created for a particular thread, then ETrue should be provided to prevent running
   475 			out of heaps or chunks.
   476 
   477 	@return	One of the system-wide error codes.
   478 	@since	7.0s
   479 	*/
   480 	IMPORT_C TInt LoadController(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap);
   481 
   482 	/**
   483 	Create a new thread in another process through Secure DRM Plugin server and load a controller plugin 
   484 	into that thread.  The motivation of this model is to allow applications without DRM capability able 
   485 	to play protected content through MMF.
   486 	
   487 	@param  aControllerUid
   488 	        The UID of the controller plugin to be loaded.
   489 	@param	aUseSharedHeap
   490 			If this value is EFalse each controller is created with its own heap. The alternative,
   491 			if the value is ETrue, is that controllers share a special heap with other controllers
   492 			created the same way. Each heap uses a chunk, so this avoids situations where the
   493 			number of chunks per process is limited. The default behaviour is generally to be
   494 			preferred, and should give lower overall memory usage. However, if many controllers are
   495 			to be created for a particular thread, then ETrue should be provided to prevent running
   496 			out of heaps or chunks.
   497 
   498 	@return One of the system-wide error codes.
   499 	*/
   500 	IMPORT_C TInt LoadControllerInSecureDRMProcess(TUid aControllerUid, TBool aUseSharedHeap);
   501 	
   502 	/**
   503 	Create a new thread in another process through Secure DRM Plugin server and load a controller plugin 
   504 	into that thread.  The motivation of this model is to allow applications without DRM capability able 
   505 	to play protected content through MMF.
   506 	
   507 	@param  aControllerInfo
   508 	        A reference to a CMMFControllerImplementationInformation object
   509 	        used for determining the controller UID and heap size
   510 	@param	aUseSharedHeap
   511 			If this value is EFalse each controller is created with its own heap. The alternative,
   512 			if the value is ETrue, is that controllers share a special heap with other controllers
   513 			created the same way. Each heap uses a chunk, so this avoids situations where the
   514 			number of chunks per process is limited. The default behaviour is generally to be
   515 			preferred, and should give lower overall memory usage. However, if many controllers are
   516 			to be created for a particular thread, then ETrue should be provided to prevent running
   517 			out of heaps or chunks.
   518 
   519 	@return	One of the system-wide error codes.
   520 	*/
   521 	IMPORT_C TInt LoadControllerInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap);
   522 	
   523 	/**
   524 	Delete the controller plugin and close its thread.
   525 	
   526 	Clients must call Close() on the controller proxy, otherwise leaks will occur.
   527 
   528 	@since	7.0s
   529 	*/
   530 	IMPORT_C void Close();
   531 
   532 	/**
   533 	Send a message synchronously to the controller thread.
   534 
   535 	The controller framework will analyze the message to determine its correct destination.
   536 
   537 	Note: This method will not return until the controller framework has serviced the command.
   538 
   539 	@param  aDestination
   540 	        The destination of the message, consisting of the uid of
   541 	        the interface of this message.
   542 	@param  aFunction
   543 	        The function number to indicate which function is to be called
   544 	        on the interface defined in the aDestination parameter.
   545 	@param  aDataTo1
   546 	        A reference to the first chunk of data to be copied to the controller
   547 	        framework. The exact contents of the data are dependent on the
   548 	        interface being called.  Can be NULL.
   549 	@param  aDataTo2
   550 	        A reference to the second chunk of data to be copied to the controller
   551 	        framework. The exact contents of the data are dependent on the
   552 	        interface being called.  Can be NULL.
   553 	@param  aDataFrom
   554 	        A reference to an area of memory to which the controller framework will
   555 	        write any data to be passed back to the client.  Can't be NULL.
   556 
   557 	@return The result of the request.  Exact range of values is dependent on the interface.
   558 	@since	7.0s
   559 	*/
   560 	IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom) const;
   561 
   562 	/**
   563 	Send a message synchronously to the controller thread.
   564 
   565 	The controller framework will analyze the message to determine its correct destination.
   566 
   567 	Note: This method will not return until the controller framework has serviced the command.
   568 
   569 	@param  aDestination
   570 	        The destination of the message, consisting of the uid of
   571 	        the interface of this message.
   572 	@param  aFunction
   573 	        The function number to indicate which function is to be called
   574 	        on the interface defined in the aDestination parameter.
   575 	@param  aDataTo1
   576 	        A reference to the first chunk of data to be copied to the controller
   577 	        framework. The exact contents of the data are dependent on the
   578 	        interface being called.  Can be NULL.
   579 	@param  aDataTo2
   580 	        A reference to the second chunk of data to be copied to the controller
   581 	        framework. The exact contents of the data are dependent on the
   582 	        interface being called.  Can be NULL.
   583 
   584 	@return The result of the request.  Exact range of values is dependent on the interface.
   585 	@since	7.0s
   586 	*/
   587 	IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2) const;
   588 
   589 	/**
   590 	Send a message asynchronously to the controller thread.
   591 	
   592 	The controller framework will analyze the message to determine its correct destination.
   593 
   594 	Note: This method will return immediately.  The RunL of the active object owning the
   595 	aStatus parameter will be called when the command is completed by the
   596 	controller framework.
   597 
   598 	@param  aDestination
   599 	        The destination of the message, consisting of the uid of
   600 	        the interface of this message.
   601 	@param  aFunction
   602 	        The function number to indicate which function is to be called
   603 	        on the interface defined in the aDestination parameter.
   604 	@param  aDataTo1
   605 	        A reference to the first chunk of data to be copied to the controller
   606 	        framework. The exact contents of the data are dependent on the
   607 	        interface being called.  Can be NULL.
   608 	@param  aDataTo2
   609 	        A reference to the second chunk of data to be copied to the controller
   610 	        framework. The exact contents of the data are dependent on the
   611 	        interface being called.  Can be NULL.
   612 	@param  aDataFrom
   613 	        A reference to an area of memory to which the controller framework will
   614 	        write any data to be passed back to the client.  Can't be NULL.
   615 	@param  aStatus
   616 	        The TRequestStatus of an active object.  This will contain the
   617 	        result of the request on completion.  The exact range of
   618 	        result values is dependent on the interface.
   619 
   620 	@since	7.0s
   621 	*/
   622 	IMPORT_C void SendAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction,  const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus) const;
   623 
   624 	/**
   625 	Send a message asynchronously to the controller thread.
   626 	
   627 	The controller framework will analyze the message to determine its correct destination.
   628 	
   629 	Note: This method will return immediately.  The RunL of the active object owning the 
   630 	aStatus parameter will be called when the command is completed by the
   631 	controller framework.
   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 	@param  aStatus
   648 	        The TRequestStatus of an active object.  This will contain the
   649 	        result of the request on completion.  The exact range of
   650 	        result values is dependent on the interface.
   651 
   652 	@since	7.0s
   653 	*/
   654 	IMPORT_C void SendAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction,  const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus) const;
   655 
   656 	IMPORT_C TInt SendSync(TInt aFunction, const TIpcArgs& aIpcArgs) const;
   657 	IMPORT_C void SendAsync(TInt aFunction, const TIpcArgs& aIpcArgs, TRequestStatus& aStatus) const;
   658 	/**
   659 	Register to receive events from the controller framework.
   660 	
   661 	Events can be generated at any time, and are generally associated with things that occur
   662 	due to something happening internally within the controller. For example, an event will
   663 	be generated if the controller stops playing due to reaching the end of a file.
   664 
   665 	@param  aEvent
   666 	        A reference to a TMMFEventPckg object that must be member data
   667 	        of the active object calling this method.  The details of the event
   668 	        will be copied into this object when an event occurs.
   669 	@param  aStatus
   670 	        The TRequestStatus of the active object calling this method.
   671 
   672 	@see	TMMFEvent
   673 	@see	CMMFControllerEventMonitor
   674 	@since	7.0s
   675 	*/
   676 	IMPORT_C void ReceiveEvents(TMMFEventPckg& aEvent, TRequestStatus& aStatus);
   677 
   678 	/**
   679 	Cancel a previous registration to receive events from the controller framework.
   680 
   681 	This must be called from the DoCancel() method of the active object using the
   682 	ReceiveEvents() API.
   683 
   684 	@return One of the standard system-wide error codes.
   685 
   686 	@see	TMMFEvent
   687 	@since	7.0s
   688 	*/
   689 	IMPORT_C TInt CancelReceiveEvents();
   690 	
   691 	/**
   692 	Set the priority of the controller's sub thread.
   693 	
   694 	This can be used to increase the responsiveness of the audio plugin to minimise
   695 	any lag in processing. This function should be used with care as it may have knock-on
   696 	effects elsewhere in the system.
   697 	
   698 	@param	aPriority
   699 			The TThreadPriority that the thread should run under.  The default is EPriorityNormal.
   700 	@return	TInt
   701 			A standard error code: KErrNone if successful, KErrNotReady if the thread does not have a
   702 			valid handle.
   703 	*/
   704 	IMPORT_C TInt SetThreadPriority(const TThreadPriority& aPriority) const;
   705 	
   706 	/**
   707 	The controller subthread has been terminated.
   708 	
   709 	This is called by CLogonMonitor when the the thread terminates
   710 	*/
   711 	void ThreadTerminated();
   712 private:
   713 	/**
   714 	Creates the new thread
   715 	*/
   716 	TInt DoCreateSubThread(RServer2* aServer2, TUint aMaxHeapSize, TBool aUseSharedHeap, TUint aStackSize);
   717 
   718 	/**
   719 	Determines the maximum heap size required by the selected controller
   720 	*/
   721 	TUint ControllersMaxHeapSizeL(TUid aControllerUid);
   722 
   723 	/**
   724 	Load a controller by UID
   725 	
   726 	@param  aControllerUid
   727 	        The UID of the controller plugin to be loaded.
   728 	@param  aControllerInfo
   729 	        A reference to a CMMFControllerImplementationInformation object
   730 	        used for determining the heap size and DRM server supporting state.
   731 	@param	aUseSharedHeap
   732 			If this value is EFalse each controller is created with its own heap. The alternative,
   733 			if the value is ETrue, is that controllers share a special heap with other controllers
   734 			created the same way. Each heap uses a chunk, so this avoids situations where the
   735 			number of chunks per process is limited. The default behaviour is generally to be
   736 			preferred, and should give lower overall memory usage. However, if many controllers are
   737 			to be created for a particular thread, then ETrue should be provided to prevent running
   738 			out of heaps or chunks.
   739 	@param	aNoDRMCap
   740 			The indicator supplied from user used to determine whether the user's process has DRM 
   741 			capability
   742 	@return	TInt
   743 			One of the system-wide error codes.
   744 	*/
   745 	TInt LoadController(TUid aControllerUid, const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap,
   746 						TBool aNoDRMCap = EFalse);
   747 	
   748 	/**
   749 	Release heap - for use when a shared heap has been registered
   750 	*/
   751 	void ReleaseHeap();
   752 
   753 	/**
   754 	Create a session to handle situation of playing DRM protected content in
   755 	process with no DRM capability.
   756 	DRM server process will be created, if not yet created. This server is responsible to
   757 	manage and monitor all the MMF Controller servers created as seperate threads belong to 
   758 	DRM server process. Once the new MMF Controller server is running, a MMF Controller server 
   759 	session will be created and the handle is passing back.
   760 	*/
   761 	TInt DoCreateSessionForNoDRMCapClient(TUint aMaxHeapSize, TBool aUseSharedHeap, TUint aStackSize);
   762 	
   763 private:
   764 	enum
   765 		{
   766 		/**
   767 		Shared heap has been opened for this object, and must be closed
   768 		*/
   769 		EFlagOpenedSharedHeap=0x01	
   770 		};
   771 
   772 private:
   773 	/**
   774 	The thread in which the controller plugin will run.
   775 	*/
   776 	RThread iSubThread;
   777 	/**
   778 	Used to hold destination for messages from the controller proxy
   779 	(not from clients calling SendSync/SendAsync!!)
   780 	*/
   781 	TMMFMessageDestinationPckg iDestinationPckg;
   782 	/**
   783 	Used to determine the success of a logon.  If the status is not pending, the logon has failed
   784 	and the thread should be closed.
   785 	*/
   786 	CLogonMonitor* iLogonAO;
   787 	/**
   788 	The priority at which the controller plugin thread runs.
   789 	*/
   790 	TThreadPriority iThreadPriority;
   791 	/**
   792 	Flags field
   793 	*/
   794 	TInt iFlags;	
   795 	/**
   796 	This member is internal and not intended for use.
   797 	*/
   798 	TInt iReserved1;
   799 	};
   800 
   801 /**
   802 @publishedAll
   803 @released
   804 
   805 Mixin class to define an object capable of handling an event within the controller framework.
   806 */
   807 class MAsyncEventHandler
   808 	{
   809 public:
   810 
   811 	/**
   812 	Sends an event to the client.
   813 
   814 	@param  aEvent
   815 	        The event.
   816 
   817 	@since 7.0s
   818 	*/
   819 	virtual TInt SendEventToClient(const TMMFEvent& aEvent) = 0;
   820 	};
   821 
   822 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
   823 #include <mmf/common/mmfcontrollerframeworkclasses.h>
   824 #endif
   825 
   826 #endif