// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// which accompanies this distribution, and is available

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __MMFCONTROLLERFRAMEWORK_H__

#define __MMFCONTROLLERFRAMEWORK_H__

#include <e32base.h>

#include <e32std.h>

#include <f32file.h>

#include <mmf/common/mmfutilities.h>

#include <mmf/common/mmfcontrollerframeworkbase.h>

#include <mmf/common/mmfipc.h>

// fwd ref

class CMMFControllerImplementationInformation;

class CLogonMonitor;

_LIT(KMMFControllerProxyServerName, "MMFControllerProxyServer-");

/**

@publishedAll

@released

Signals that the message is destined for the controller

*/

const TInt KMMFObjectHandleController = -2;

/**

@publishedAll

@released

Null, or invalid, object handle

*/

const TInt KMMFObjectHandleNull = 0;

/**

@publishedAll

@released

Describes the destination of a message in the controller framework.

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

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

to send the message.

The controller plugin and controller proxy use the special constant handles

KMMFObjectHandleControllerProxy and KMMFObjectHandleController for

efficiency.

@since 7.0s

*/

class TMMFMessageDestination

	{

public:

	/**

	Default constructor.

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

	@since 7.0s

	*/

	IMPORT_C TMMFMessageDestination();

	/**

	Constructor for sending messages to the controller plugin.

	Assigns KMMFObjectHandleController to the destination handle.

	@param  aInterfaceId

	        The UID of the interface of this message destination.

	@since  7.0s

	*/

	IMPORT_C TMMFMessageDestination(TUid aInterfaceId);

	/**

	Full constructor.

	@param  aInterfaceId

	        The UID of the interface of this message destination.

	@param  aDestinationHandle

	        The handle of the destination object in the controller framework.

	@since  7.0s

	*/

	IMPORT_C TMMFMessageDestination(TUid aInterfaceId, TInt aDestinationHandle);

	/**

	Copy constructor.

	@param  aOther

	        The TMMFMessageDestination object to be copied.

	@since  7.0s

	*/

	IMPORT_C TMMFMessageDestination(const TMMFMessageDestination& aOther);

	/**

	Returns the UID of the interface of the message destination.

	@return	The interface UID.

	@since 7.0s

	*/

	IMPORT_C TUid InterfaceId() const;

	/**

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

	@return	The destination handle.

	@since 7.0s

	*/

	IMPORT_C TInt DestinationHandle() const;

	/**

	Compares two destinations.

	@param  aOther

	        The object to be compared with this object.

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

	        EFalse if the objects are different.

	@since 7.0s

	*/

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

private:

	TUid iInterfaceId;

	TInt iDestinationHandle;

	/**

	This member is internal and not intended for use.

	*/

	TInt iReserved1;

	TInt iReserved2;

	TInt iReserved3;

	};

/**

@publishedAll

@released

Package buffer for TMMFMessageDestination

*/

typedef TPckgBuf<TMMFMessageDestination> TMMFMessageDestinationPckg;

/**

@publishedAll

@released

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

from the changes occurring with secure APIs.

Adds required destination information to the message so the controller framework

can determine which object the message is for.

Adds capability to check whether the message has been completed.

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

@see RMMFControllerProxy::SendSync

@see RMMFControllerProxy::SendAsync

@since 7.0s

*/

class TMMFMessage

	{

friend class CMMFControllerProxySession;

friend class CMMFDevSoundSession;

public:

	/**

	Copy constructor.

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

	other event before completing it.

	@param  aMessage

	        The message object to copy.

	@since 7.0s

	*/

	IMPORT_C TMMFMessage(const TMMFMessage& aMessage);

	/**

	Returns the destination of the message.

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

			handle of the destination object.

	@since	7.0s

	*/

	IMPORT_C const TMMFMessageDestination& Destination();

	/**

	Returns an integer describing the function being called. Equivalent to 

	RMessage::Function().

	@return The function being called over IPC.

	@see    RMessage::Function()

	@since  7.0s

	*/

	IMPORT_C TInt Function();

	/**

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

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

	@return	The size of data 1.

	@since	7.0s

	*/

	IMPORT_C TInt SizeOfData1FromClient();

	/**

	Copy the first descriptor from the client.

	@param  aDes

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

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

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

	        if the client did not provide a valid descriptor.

	@since  7.0s

	*/

	IMPORT_C TInt ReadData1FromClient(TDes8& aDes);

	/**

	Copy the first descriptor from the client.

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

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

	@param  aDes

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

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

	@since 7.0s

	*/

	IMPORT_C void ReadData1FromClientL(TDes8& aDes);

	/**

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

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

	@return The size of data 2.

	@since  7.0s

	*/

	IMPORT_C TInt SizeOfData2FromClient();

	/**

	Copies the second descriptor from the client.

	@param  aDes

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

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

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

	        if the client did not provide a valid descriptor.

	@since  7.0s

	*/

	IMPORT_C TInt ReadData2FromClient(TDes8& aDes);

	/**

	Copies the second descriptor from the client.

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

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

	@param  aDes

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

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

	@since  7.0s

	*/

	IMPORT_C void ReadData2FromClientL(TDes8& aDes);

	/**

	Copies data back to the client.

	@param  aDes

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

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

	        copied into.

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

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

	@since  7.0s

	*/

	IMPORT_C TInt WriteDataToClient(const TDesC8& aDes);

	/**

	Copies the data back to the client.

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

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

	@param  aDes

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

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

	@since 7.0s

	*/

	IMPORT_C void WriteDataToClientL(const TDesC8& aDes);

	/**

	Signals to the client that its request has been completed.

	Equivalent to RMessage::Complete.

	@param  aReason

	        The result code to be given back to the client.

	@since  7.0s

	*/

	IMPORT_C void Complete(TInt aReason);

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

	/**

	Checks whether this message has already been completed.

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

	        completed, EFalse if not.

	@since  7.0s

	*/

	IMPORT_C TBool IsCompleted();

	/**

	Constructs a TMMFMessage from an RMmfIpcMessage.

	@param	aMessage

			The handle to the remote message.

	@since  7.0s

	*/

	IMPORT_C TMMFMessage(const RMmfIpcMessage& aMessage);

	/**

	Gets the destination info from the client.

	@since  7.0s

	*/

	IMPORT_C void FetchDestinationL();

private:

#ifdef __MMF_USE_IPC_V2__

	/**

	The encapsulated message

	*/

	RMessagePtr2 iMessage;

	/**

	The encapsulated function

	*/

	TInt iFunction;

	/**

	Private padding to preserve BC with earlier versions

	*/

	TInt iDummyPadding[6];

#else

	/**

	The RMessage encapsulated by this object.

	*/

	RMessage iMessage;

#endif // __MMF_USE_IPC_V2__

	/**

	The destination of this message.

	*/

	TMMFMessageDestination iDestination;

	/**

	Defines whether this object has yet to be completed.

	*/

	TBool iAmCompleted;

	};

/**

Mixin class used by CLogonMonitor to inform about its state

@since 9.3

*/

class MLogonMonitorObserver

	{

public:

	/**

	The monitored thread has been terminated.

	*/

	virtual void ThreadTerminated() = 0;

	};

/**

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

message sending over IPC.

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

care exactly what those messages are.

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

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

changed raising a binary compatibility problem.

@since 7.0s

*/

NONSHARABLE_CLASS(RMMFControllerProxy) : public RMmfSessionBase, public MLogonMonitorObserver

	{

public:

	/**

	Constructor.

	@since 7.0s

	*/

	IMPORT_C RMMFControllerProxy();

	/**

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

	@param  aControllerUid

	        The UID of the controller plugin to be loaded.

	@param	aUseSharedHeap

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

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

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

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

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

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

			out of heaps or chunks.

	@return One of the system-wide error codes.

	@since	7.0s

	*/

	IMPORT_C TInt LoadController(TUid aControllerUid, TBool aUseSharedHeap);

	/**

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

	@param  aControllerInfo

	        A reference to a CMMFControllerImplementationInformation object

	        used for determining the controller UID and heap size

	@param	aUseSharedHeap

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

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

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

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

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

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

			out of heaps or chunks.

	@return	One of the system-wide error codes.

	@since	7.0s

	*/

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

	/**

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

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

	to play protected content through MMF.

	@param  aControllerUid

	        The UID of the controller plugin to be loaded.

	@param	aUseSharedHeap

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

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

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

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

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

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