diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mmf/common/mmfcontrollerframework.h --- a/epoc32/include/mmf/common/mmfcontrollerframework.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mmf/common/mmfcontrollerframework.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,1268 @@ -mmfcontrollerframework.h +// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// 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 +// which accompanies this distribution, and is available +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + + +#ifndef __MMFCONTROLLERFRAMEWORK_H__ +#define __MMFCONTROLLERFRAMEWORK_H__ + +#include +#include +#include +#include +#include +#include + +// fwd ref +class CMMFControllerImplementationInformation; +class CLogonMonitor; + +_LIT(KMMFControllerProxyServerName, "MMFControllerProxyServer-"); + +/** +@internalComponent +*/ +#define KMMFControllerProxyVersion TVersion(7,1,1) + +/** +@internalComponent +*/ +const TInt KMMFControllerProxyMaxHeapSize = 0x1000000;//16MB + +/** +@internalComponent +*/ +const TInt KMMFControllerProxyMaxCachedMessages = 10; + +/** +@internalComponent + +Signals that the message is destined for the controller proxy +*/ +const TInt KMMFObjectHandleControllerProxy = -1; + +/** +@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; +/** +@internalComponent + +The first valid object handle. The MMF Object container will +begin iterating from here when generating object handles. +*/ +const TInt KMMFObjectHandleFirstValid = 1; + +/** +@internalComponent +*/ +const TInt KMmfControllerThreadShutdownTimeout = 20000000; // 20 seconds + +/** +@internalComponent + +The UID and messages associated with the controller proxy interface. +*/ +const TUid KUidInterfaceMMFControllerProxy = {0x101F77E7}; + +/** +@internalComponent + +Struct to allow RMMFController to pass several parameters to new CControllerProxyServer threads. +*/ +struct TControllerProxyServerParams + { + RServer2* iServer; + TBool iUsingSharedHeap; + }; + + +/** +@internalComponent +*/ +enum TMMFControllerProxyMessages + { + EMMFControllerProxyLoadControllerPluginByUid, + EMMFControllerProxyReceiveEvents, + EMMFControllerProxyCancelReceiveEvents + }; + + +/** +@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 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; + }; + +/** +@internalComponent + +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; + }; + +/** +@internalComponent + +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 + out of heaps or chunks. + + @return One of the system-wide error codes. + */ + IMPORT_C TInt LoadControllerInSecureDRMProcess(TUid aControllerUid, 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 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. + */ + IMPORT_C TInt LoadControllerInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap); + + /** + Delete the controller plugin and close its thread. + + Clients must call Close() on the controller proxy, otherwise leaks will occur. + + @since 7.0s + */ + IMPORT_C void Close(); + + /** + Send a message synchronously to the controller thread. + + The controller framework will analyze the message to determine its correct destination. + + Note: This method will not return until the controller framework has serviced the command. + + @param aDestination + The destination of the message, consisting of the uid of + the interface of this message. + @param aFunction + The function number to indicate which function is to be called + on the interface defined in the aDestination parameter. + @param aDataTo1 + A reference to the first chunk of data to be copied to the controller + framework. The exact contents of the data are dependent on the + interface being called. Can be NULL. + @param aDataTo2 + A reference to the second chunk of data to be copied to the controller + framework. The exact contents of the data are dependent on the + interface being called. Can be NULL. + @param aDataFrom + A reference to an area of memory to which the controller framework will + write any data to be passed back to the client. Can't be NULL. + + @return The result of the request. Exact range of values is dependent on the interface. + @since 7.0s + */ + IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom) const; + + /** + Send a message synchronously to the controller thread. + + The controller framework will analyze the message to determine its correct destination. + + Note: This method will not return until the controller framework has serviced the command. + + @param aDestination + The destination of the message, consisting of the uid of + the interface of this message. + @param aFunction + The function number to indicate which function is to be called + on the interface defined in the aDestination parameter. + @param aDataTo1 + A reference to the first chunk of data to be copied to the controller + framework. The exact contents of the data are dependent on the + interface being called. Can be NULL. + @param aDataTo2 + A reference to the second chunk of data to be copied to the controller + framework. The exact contents of the data are dependent on the + interface being called. Can be NULL. + + @return The result of the request. Exact range of values is dependent on the interface. + @since 7.0s + */ + IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2) const; + + /** + Send a message asynchronously to the controller thread. + + The controller framework will analyze the message to determine its correct destination. + + Note: This method will return immediately. The RunL of the active object owning the + aStatus parameter will be called when the command is completed by the + controller framework. + + @param aDestination + The destination of the message, consisting of the uid of + the interface of this message. + @param aFunction + The function number to indicate which function is to be called + on the interface defined in the aDestination parameter. + @param aDataTo1 + A reference to the first chunk of data to be copied to the controller + framework. The exact contents of the data are dependent on the + interface being called. Can be NULL. + @param aDataTo2 + A reference to the second chunk of data to be copied to the controller + framework. The exact contents of the data are dependent on the + interface being called. Can be NULL. + @param aDataFrom + A reference to an area of memory to which the controller framework will + write any data to be passed back to the client. Can't be NULL. + @param aStatus + The TRequestStatus of an active object. This will contain the + result of the request on completion. The exact range of + result values is dependent on the interface. + + @since 7.0s + */ + IMPORT_C void SendAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus) const; + + /** + Send a message asynchronously to the controller thread. + + The controller framework will analyze the message to determine its correct destination. + + Note: This method will return immediately. The RunL of the active object owning the + aStatus parameter will be called when the command is completed by the + controller framework. + + @param aDestination + The destination of the message, consisting of the uid of + the interface of this message. + @param aFunction + The function number to indicate which function is to be called + on the interface defined in the aDestination parameter. + @param aDataTo1 + A reference to the first chunk of data to be copied to the controller + framework. The exact contents of the data are dependent on the + interface being called. Can be NULL. + @param aDataTo2 + A reference to the second chunk of data to be copied to the controller + framework. The exact contents of the data are dependent on the + interface being called. Can be NULL. + @param aStatus + The TRequestStatus of an active object. This will contain the + result of the request on completion. The exact range of + result values is dependent on the interface. + + @since 7.0s + */ + IMPORT_C void SendAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus) const; + + IMPORT_C TInt SendSync(TInt aFunction, const TIpcArgs& aIpcArgs) const; + IMPORT_C void SendAsync(TInt aFunction, const TIpcArgs& aIpcArgs, TRequestStatus& aStatus) const; + /** + Register to receive events from the controller framework. + + Events can be generated at any time, and are generally associated with things that occur + due to something happening internally within the controller. For example, an event will + be generated if the controller stops playing due to reaching the end of a file. + + @param aEvent + A reference to a TMMFEventPckg object that must be member data + of the active object calling this method. The details of the event + will be copied into this object when an event occurs. + @param aStatus + The TRequestStatus of the active object calling this method. + + @see TMMFEvent + @see CMMFControllerEventMonitor + @since 7.0s + */ + IMPORT_C void ReceiveEvents(TMMFEventPckg& aEvent, TRequestStatus& aStatus); + + /** + Cancel a previous registration to receive events from the controller framework. + + This must be called from the DoCancel() method of the active object using the + ReceiveEvents() API. + + @return One of the standard system-wide error codes. + + @see TMMFEvent + @since 7.0s + */ + IMPORT_C TInt CancelReceiveEvents(); + + /** + Set the priority of the controller's sub thread. + + This can be used to increase the responsiveness of the audio plugin to minimise + any lag in processing. This function should be used with care as it may have knock-on + effects elsewhere in the system. + + @param aPriority + The TThreadPriority that the thread should run under. The default is EPriorityNormal. + @return TInt + A standard error code: KErrNone if successful, KErrNotReady if the thread does not have a + valid handle. + */ + IMPORT_C TInt SetThreadPriority(const TThreadPriority& aPriority) const; + + /** + The controller subthread has been terminated. + + This is called by CLogonMonitor when the the thread terminates + */ + void ThreadTerminated(); +private: + /** + Creates the new thread + */ + TInt DoCreateSubThread(RServer2* aServer2, TUint aMaxHeapSize, TBool aUseSharedHeap); + + /** + Determines the maximum heap size required by the selected controller + */ + TUint ControllersMaxHeapSizeL(TUid aControllerUid); + + /** + Load a controller by UID + + @param aControllerUid + The UID of the controller plugin to be loaded. + @param aControllerInfo + A reference to a CMMFControllerImplementationInformation object + used for determining the heap size and DRM server supporting state. + @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. + @param aNoDRMCap + The indicator supplied from user used to determine whether the user's process has DRM + capability + @return TInt + One of the system-wide error codes. + */ + TInt LoadController(TUid aControllerUid, const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap, + TBool aNoDRMCap = EFalse); + + /** + Release heap - for use when a shared heap has been registered + */ + void ReleaseHeap(); + + /** + Create a session to handle situation of playing DRM protected content in + process with no DRM capability. + DRM server process will be created, if not yet created. This server is responsible to + manage and monitor all the MMF Controller servers created as seperate threads belong to + DRM server process. Once the new MMF Controller server is running, a MMF Controller server + session will be created and the handle is passing back. + */ + TInt DoCreateSessionForNoDRMCapClient(TUint aMaxHeapSize, TBool aUseSharedHeap); + +private: + enum + { + /** + Shared heap has been opened for this object, and must be closed + */ + EFlagOpenedSharedHeap=0x01 + }; + +private: + /** + The thread in which the controller plugin will run. + */ + RThread iSubThread; + /** + Used to hold destination for messages from the controller proxy + (not from clients calling SendSync/SendAsync!!) + */ + TMMFMessageDestinationPckg iDestinationPckg; + /** + Used to determine the success of a logon. If the status is not pending, the logon has failed + and the thread should be closed. + */ + CLogonMonitor* iLogonAO; + /** + The priority at which the controller plugin thread runs. + */ + TThreadPriority iThreadPriority; + /** + Flags field + */ + TInt iFlags; + /** + This member is internal and not intended for use. + */ + TInt iReserved1; + }; + +/** +@internalComponent + +Used to Kill the controller thread either immediately or after a timeout. +Used by the controller thread on startup to prevent orphaning if no sessions are created to it. +*/ +class CMMFControllerProxyShutdown : public CTimer + { + enum {EMMFControllerProxyShutdownDelay=1000000}; // 1s +public: + + /** + Create a new shutdown timer. + + This method can leave with one of the system-wide error codes. + + @since 7.0s + */ + static CMMFControllerProxyShutdown* NewL(); + + /** + Start the shutdown timer. The RunL of this active object will be called after + EMMFControllerProxyShutdownDelay microseconds. + + @since 7.0s + */ + void Start(); + + /** + Shut down the controller thread immediately. + + Calls CActiveScheduler::Stop(). + + @since 7.0s + */ + void ShutdownNow(); +private: + CMMFControllerProxyShutdown(); + void ConstructL(); + + /** + Calls ShutdownNow(). + + @since 7.0s + */ + void RunL(); + }; + + +/** +@publishedAll +@released + +Mixin class to define an object capable of handling an event within the controller framework. +*/ +class MAsyncEventHandler + { +public: + + /** + Sends an event to the client. + + @param aEvent + The event. + + @since 7.0s + */ + virtual TInt SendEventToClient(const TMMFEvent& aEvent) = 0; + }; + +/** +@internalComponent + +Used to hold on to an TMMFMessage so we can complete it asynchronously to +send an event to the client. + +@since 7.0s +*/ +class CMMFEventReceiver : public CBase + { +public: + + /** + Constructs a new event receiver. + + This method may leave with one of the system-wide error codes. + + @param aMessage + The message to be completed when an event occurs. + + @return A pointer to the newly created event receiver. + + @since 7.0s + */ + static CMMFEventReceiver* NewL(const TMMFMessage& aMessage); + + /** + Destructor. + + Completes the message with KErrCancel if the message hasn't already been completed. + + @since 7.0s + */ + ~CMMFEventReceiver(); + + /** + Sends an event to the client. + + @param aEvent + The event. + + @since 7.0s + */ + void SendEvent(const TMMFEvent& aEvent); +private: + + /** + Constructor. + + @param aMessage + The message to be completed when an event occurs. + + @since 7.0s + */ + CMMFEventReceiver(const TMMFMessage& aMessage); +private: + /** + The message to be completed when an event occurs. + */ + TMMFMessage iMessage; + }; + + + +/** +@internalComponent + +The controller proxy server. + +The main server inside the controller thread, responsible for creating and destroying the single +session used to transmit messages from the client to the server. + +Every controller plugin runs in its own thread, and has its own controller proxy server. + +@since 7.0s +*/ +class CMMFControllerProxyServer : public CMmfIpcServer + { +public: + /** + Construct the server. + + This method may leave with one of the system-wide error codes. + + @return The newly created server. + + @since 7.0s + */ + static CMMFControllerProxyServer* NewL(RServer2* aServer2 ); + + /** + Destructor. + + @since 7.0s + */ + ~CMMFControllerProxyServer(); + + /** + Static thread function. + + The address of this function is passed into RThread::Create. + + Unpackages the startup parameters and calls DoStartThreadL(). + + @param aAny + A pointer to the packaged startup parameters. + + @return One of the system-wide error codes. + + @since 7.0s + */ + IMPORT_C static TInt StartThread(TAny* aParam); + + /** + Called by the active scheduler when the ServiceL of the session leaves. + Completes the message with the error and restarts the server. + + @param aError + The error that the session ServiceL left with. + + @return KErrNone + @since 7.0s + */ + TInt RunError(TInt aError); + + /** + Signals that the session has been created. + + Stops the shutdown timer. + + @since 7.0s + */ + void SessionCreated(); + + /** + Signals that the session has been destroyed. + Causes the server to shut down immediately. + + @since 7.0s + */ + void SessionDestroyed(); +private: + + /** + Thread startup code. + + Creates the cleanup stack, installs the active scheduler and creates the server. + Once all this is completed successfully, it signals the success back to the client. + + This function may leave with one of the system-wide error codes. + + @param aParams + Used to signal startup success back to the client. + + @since 7.0s + */ + static void DoStartThreadL(TAny* aParam); + + /** + Creates a new session. Only one session may be created with the ControllerProxyServer. + + This function may leave with one of the system-wide error codes. + + @param aVersion + The version number of the session. + + @return A pointer to the new session. + + @since 7.0s + */ + CMmfIpcSession* NewSessionL(const TVersion& aVersion) const; + + /** + Constructor. + + @since 7.0s + */ + CMMFControllerProxyServer(); + + /** + Second phase constructor. + + @since 7.0s + */ + void ConstructL(RServer2* aServer2); + + /** + Renaming Controller Proxy Server name + + @since 9.2 + */ + static void RenameControllerProxyThread(); + +private: + /** + The timer used to shut down the server in case the client fails to connect a session. + */ + CMMFControllerProxyShutdown* iShutdownTimer; + /** + Indicates whether we have a session connected. Only one session is allowed to connect to the server. + */ + TBool iHaveSession; + }; + +class CMMFController; + +/** +@internalComponent + +The controller proxy session. + +Only one session can be connected to a controller proxy server. + +@since 7.0s +*/ +class CMMFControllerProxySession : public CMmfIpcSession, public MAsyncEventHandler + { +public: + + /** + Construct the session. + + This method may leave with one of the system-wide error codes. + + @return The newly created server. + + @since 7.0s + */ + static CMMFControllerProxySession* NewL(); + + /** + Second phase constructor called by the CServer base class. + + This function may leave with one of the system-wide error codes. + + @param aServer + A reference to the server to which this session is attached. + + @since 7.0s + */ + void CreateL(const CMmfIpcServer& aServer); + + /** + Destructor. + */ + ~CMMFControllerProxySession(); + + /** + Called by the CServer baseclass when a request has been made by the client. + + This function may leave with on of the system-wide error codes. If + a leave occurs, the message will be automatically completed by the + RunError() of the Controller Proxy Server. + + @param aMessage + The request to be handled. The controller proxy session will create + a TMMFMessage from this, and pass on the request to the controller + base class to handle. + + @since 7.0s + */ + void ServiceL(const RMmfIpcMessage& aMessage); + + /** + Derived from MAsyncEventHandler. + + @see MAsyncEventHandler + + @since 7.0s + */ + TInt SendEventToClient(const TMMFEvent& aEvent); +private: + /** + Constructor + */ + CMMFControllerProxySession(); + + /** + Handle a request from the client to register to receive events from the controller framework. + + This function may leave with one of the system-wide error codes. + + @param aMessage + The request to be handled. + + @return ETrue if the message is to be completed now, EFalse if the message will be completed + later. + */ + TBool ReceiveEventsL(TMMFMessage& aMessage); + + /** + Handle a request from the client to stop receiving events from the controller framework. + + This function may leave with one of the system-wide error codes. + + @param aMessage + The request to be handled. + + @return ETrue if the message is to be completed now, EFalse if the message will be completed later. + */ + TBool CancelReceiveEvents(TMMFMessage& aMessage); + + /** + Handle a request from the client to load a controller plugin. + + This function may leave with one of the system-wide error codes. + + @param aMessage + The request to be handled. + + @return ETrue if the message is to be completed now, EFalse if the message will be completed later. + */ + TBool LoadControllerL(TMMFMessage& aMessage); +private: + /** + The controller plugin. + */ + CMMFController* iController; + /** + A pointer to the server. + */ + CMMFControllerProxyServer* iServer; + /** + The event receiver. Used to send events to the client. + */ + CMMFEventReceiver* iEventReceiver; + /** + The events waiting to be sent to the client. + */ + RArray iEvents; + }; + + +#endif