diff -r 000000000000 -r a41df078684a kernel/eka/include/twintnotifier.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kernel/eka/include/twintnotifier.h Mon Oct 19 15:55:17 2009 +0100 @@ -0,0 +1,610 @@ +// Copyright (c) 1995-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 "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// e32\include\twintnotifier.h +// Text Window Server text notifiers. +// +// WARNING: This file contains some APIs which are internal and are subject +// to change without notice. Such APIs should therefore not be used +// outside the Kernel and Hardware Services package. +// + +#ifndef __TWINTNOTIFIER_H__ +#define __TWINTNOTIFIER_H__ + +#include + + +// Notifier Plugin architecture copied from UIKON + + + +/** +@internalComponent +*/ +_LIT(KNotifierPlugInExt,"*.*"); + + + +/** +@publishedPartner +@released + +Defines the path which is searched for notifier plugin DLLs. +*/ +_LIT(KNotifierPlugInSearchPath,"\\sys\\bin\\tnotifiers\\"); + + + +/** +@publishedPartner +@deprecated +*/ +const TUid KUidNotifierPlugIn={0x10005522}; + + + +/** +@publishedPartner +@released +*/ +const TUid KUidTextNotifierPlugInV2={0x101fe38b}; + + + +/** +@internalComponent +*/ +_LIT8(KNotifierPaused,"Eik_Notifier_Paused"); + + + +/** +@internalComponent +*/ +_LIT8(KNotifierResumed,"Eik_Notifier_Resumed"); + + + +enum TNotExtStatus +/** +@internalComponent +*/ + { + ENotExtRequestCompleted =0, + ENotExtRequestQueued =1, + }; + + + + +class MNotifierManager +/** +@publishedPartner +@released + +An interface that allows notifiers to manage their own startup and shutdown. + +This class is likely to be of interest to notifiers that observe engines +using publically available APIs rather than those that are run via RNotifier + +@see RNotifier +*/ + { +public: + /** + Starts the specified notifier. + + @param aNotifierUid The Uid that identifies the notifier. + @param aBuffer Data that can be passed from the client-side. + The format and meaning of any data + is implementation dependent. + @param aResponse Data that can be returned to the client-side. + The format and meaning of any data is implementation dependent. + */ + virtual void StartNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)=0; + + + + /** + Cancels the specified notifier. + + @param aNotifierUid The Uid that identifies the notifier. + */ + virtual void CancelNotifier(TUid aNotifierUid)=0; + + + /** + Updates a currently active notifier with new data. + + @param aNotifierUid The Uid that identifies the notifier. + @param aBuffer New data that can be passed from the client-side. + The format and meaning of any data is implementation dependent. + @param aResponse Data that can be returned to the client-side. + The format and meaning of any data is implementation dependent. + */ + virtual void UpdateNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)=0; + }; + + + + +class MNotifierBase2 +/** +@publishedPartner +@released + +Interface to a plug-in server side notifier for the text window server. + +Any number of MNotifierBase2 objects can be included in a single DLL. +All notifiers are loaded during device startup and are not destroyed until +the notifier server closes down. + +Note that the text window server is not used in production ROMs. +It is used when testing low level code. +*/ + { +public: + /** + Defines a set of notifier priorities. The use and application of these + values is implementation dependent. ENotifierPriorityAbsolute defines + the highest priority value; subsequent enum values define decreasing + priority values. + */ + enum TNotifierPriority + { + ENotifierPriorityAbsolute=500, + ENotifierPriorityVHigh=400, + ENotifierPriorityHigh=300, + ENotifierPriorityLow=200, + ENotifierPriorityVLow=100, + ENotifierPriorityLowest=0 + }; +public: + /** + Encapsulates the notifier parameters. + */ + class TNotifierInfo + { + public: + /** + The Uid that identifies the notifier. + */ + TUid iUid; + + /** + The Uid that identifies the channel to be used by + the notifier (e.g. the screen, an LED etc). + */ + TUid iChannel; + + /** + The notifier priority, typically chosen from the standard set. + + @see MNotifierBase2::TNotifierPriority + */ + TInt iPriority; + }; +public: + + + + /** + Frees all resources owned by this notifier. + + This function is called by the notifier framework when all resources + allocated by notifiers should be freed. As a minimum, the implementation + should delete this object (i.e. delete this;). + + Note that it is important to implement this function correctly + to avoid memory leaks. + */ + virtual void Release()=0; + + + + /** + Performs any initialisation that this notifier may require. + + The function is called when the notifier is first loaded, + i.e. when the plug-in DLL is loaded. It is called only once. + + As a minimum, the implementation should return a TNotifierInfo instance + describing the notifier parameters. A good implementation would be to set + up a TNotifierInfo as a data member, and then to return it. This is because + the same information is returned by Info(). + + The function is safe to leave from, so it is possible, + although rarely necessary, to allocate objects as you would normally do + in a ConstructL() function as part of two-phase construction. + + @return The parameters of the notifier. + + @see MNotifierBase2::Info + */ + virtual TNotifierInfo RegisterL()=0; + + + + /** + Gets the notifier parameters. + + This is the same information as returned by RegisterL(), although + the returned values may be varied at run-time. + */ + virtual TNotifierInfo Info() const=0; + + + + /** + Starts the notifier. + + This is called as a result of a client-side call + to RNotifier::StartNotifier(), which the client uses to start a notifier + from which it does not expect a response. + + The function is synchronous, but it should be implemented so that + it completes as soon as possible, allowing the notifier framework + to enforce its priority mechanism. + + It is not possible to wait for a notifier to complete before returning + from this function unless the notifier is likely to finish implementing + its functionality immediately. + + @param aBuffer Data that can be passed from the client-side. + The format and meaning of any data is implementation dependent. + + @return A pointer descriptor representing data for the initial response + + @see RNotifier::StartNotifier + */ + virtual TPtrC8 StartL(const TDesC8& aBuffer)=0; + + + + /** + Starts the notifier. + + This is called as a result of a client-side call to + the asynchronous function RNotifier::StartNotifierAndGetResponse(). + This means that the client is waiting, asynchronously, for the notifier + to tell the client that it has finished its work. + + It is important to return from this function as soon as possible, + + The implementation of a derived class must make sure that Complete() is + called on the RMessage2 object when the notifier is deactivated. + + This function may be called multiple times if more than one client starts + the notifier. + + @param aBuffer Data that can be passed from the client-side. The format + and meaning of any data is implementation dependent. + @param aReplySlot The offset within the message arguments for the reply. + This message argument will refer to a modifiable + descriptor, a TDes8 type, into which data + can be returned. The format and meaning + of any returned data is implementation dependent. + @param aMessage Encapsulates a client request. + + @see RNotifier::StartNotifierAndGetResponse + */ + virtual void StartL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage)=0; + + + + /** + Cancels an active notifier. + + This is called as a result of a client-side call + to RNotifier::CancelNotifier(). + + An implementation should free any relevant resources, and complete + any outstanding messages, if relevant. + + @see RNotifier::CancelNotifier + */ + virtual void Cancel()=0; + + + + /** + Updates a currently active notifier with new data. + + This is called as a result of a client-side call + to RNotifier::UpdateNotifier(). + + @param aBuffer Data that can be passed from the client-side. + The format and meaning of any data is + implementation dependent. + + @return A pointer descriptor representing data that may be returned. + The format and meaning of any data is implementation dependent. + + @see RNotifier::UpdateNotifier + */ + virtual TPtrC8 UpdateL(const TDesC8& aBuffer)=0; +public: + + + + /** + Sets the notifier manager. + + @param aManager A pointer to the notifier manager. + */ + void SetManager(MNotifierManager* aManager); +protected: + MNotifierManager* iManager; +private: + TInt iNotBSpare; + }; + + + + + + +// Remaining classes are internal to the text window server + + + +class CNotifierManager; + +/** +@internalComponent +*/ +class CNotifierServer : public CServer2 + { +public: + static CNotifierServer* NewL(); + ~CNotifierServer(); +public: // from CServer2 + CSession2* NewSessionL(const TVersion &aVersion,const RMessage2&) const; +public: + CNotifierServer(TInt aPriority); + inline CNotifierManager* Manager() const; +public: + void SetIsExiting(); + TBool IsExiting() const; +private: + void ConstructL(); +private: + CNotifierManager* iManager; + TBool iExiting; + }; + + + + +/** +@internalComponent +*/ +class CNotifierSession : public CSession2 + { +public: + CNotifierSession(const CNotifierServer& aServer); + ~CNotifierSession(); +public: // from CSession2 + void ServiceL(const RMessage2& aMessage); +private: + enum TNotifierPanic + { + ENotifierPanicInconsistentDescriptorLengths=0, + ENotifierPanicPasswordWindow, + }; +private: + void DisplayAlertL(const RMessage2& aMessage); + void DisplayInfoMsgL(const RMessage2& aMessage); + void DoStartNotifierL(const RMessage2& aMessage); + void DoUpdateNotifierL(const RMessage2& aMessage); + void StartNotifierAndGetResponseL(const RMessage2& aMessage,TBool& aCleanupComplete); + void PanicClient(const RMessage2& aMessage,TNotifierPanic aCode); + static TInt InfoPrintThread(TAny* aMessage); + void RunPasswordWindowL(const RMessage2& aMessage); +public: + static RSemaphore NotifierSemaphore; +private: + const CNotifierServer* iServer; + TInt iClientId; + }; + + + + +class CQueueItem; +class CChannelMonitor; +class CActivityMonitor; +class CNotifierQueue; + +/** +@internalComponent +*/ +class CNotifierManager : public CBase, public MNotifierManager + { +public: + static CNotifierManager* NewL(); + ~CNotifierManager(); + void RegisterL(RFs& aFs); + void NotifierStartL(TUid aNotifierUid,const TDesC8& aBuffer,TPtrC8* aResponse,TInt aClientId); + TInt NotifierUpdateL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8* aResponse,TInt aClientId); + TInt NotifierCancel(TUid aNotifierUid); + void NotifierStartAndGetResponseL(TUid aNotifierUid,const TDesC8& aBuffer,TInt aReplySlot, + const RMessage2& aMessage,TInt aClientId,TBool& aCleanupComplete); + void HandleClientExit(TInt aClientId); + void NotifierStartAndGetResponseL(TUid aNotifierUid,TUid aChannelUid,const TDesC8& aBuffer,TInt aReplySlot, + const RMessage2& aMessage,TInt aClientId,TBool& aCleanupComplete); +public: // from MNotifierManager + void StartNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse); + void CancelNotifier(TUid aNotifierUid); + void UpdateNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse); +private: + void DoAddPlugInL(const TDesC& aPath,const TDesC& aFileName,const TUidType& aUidType); + CNotifierManager(); + void ConstructL(); + void StartFromQueueL(CQueueItem* aItem); +private: + CArrayPtr* iObservedList; + CArrayFix* iLibraries; + CChannelMonitor* iChannelMonitor; + CActivityMonitor* iActivityMonitor; + CNotifierQueue* iQueue; + }; + + + + +/** +@internalComponent +*/ +class TChannelActivity + { +public: + inline TChannelActivity(TUid aChannel,TInt aHighestPriorityRunning); +public: + TUid iChannel; + TInt iHighestPriorityRunning; + }; + + + + +/** +@internalComponent +*/ +class CChannelMonitor : public CBase + { +public: + static CChannelMonitor* NewL(); + inline void AddNewChannelL(TUid aChannel); + TBool AlreadyHasChannel(TUid aChannel) const; + TInt ActivityLevel(TUid aChannel) const; + void UpdateChannel(TUid aChannel,TInt aLevel); +private: + CChannelMonitor(); +private: + CArrayFixFlat iMonitor; + }; + + + + +/** +@internalComponent +*/ +class CNotifierActivity : public CBase + { +public: + static CNotifierActivity* NewLC(const MNotifierBase2::TNotifierInfo& aInfo,TInt aClientId); + ~CNotifierActivity(); + TInt Find(TInt aClientId) const; +private: + CNotifierActivity(const MNotifierBase2::TNotifierInfo& aInfo); + void ConstructL(TInt aClientId); +public: + const MNotifierBase2::TNotifierInfo iInfo; + CArrayFixFlat iClientArray; + }; + + + + +/** +@internalComponent +*/ +class CActivityMonitor : public CBase + { +public: + static CActivityMonitor* NewL(); + ~CActivityMonitor(); + void AddL(const MNotifierBase2::TNotifierInfo& aInfo,TInt aClientId); + void Remove(TUid aNotifierUid,TInt aClientId); + void RemoveNotifier(TUid aNotifierUid,TUid aChannel); + void RemoveClient(TInt aClientId); + TBool IsNotifierActive(TUid aNotifierUid,TUid aChannel) const; + TBool IsChannelActive(TUid aChannel,TUid& aNotifier,MNotifierBase2::TNotifierPriority& aHighestPriority) const; + TBool IsClientPresent(TUid aNotifierUid,TUid aChannel,TInt aClientId) const; + TBool NotifierForClient(TUid& aNotifier,TInt aClientId) const; +private: + CActivityMonitor(); + TInt Find(TUid aNotifierUid) const; + TInt Find(TUid aNotifierUid,TUid aChannel) const; +private: + CArrayPtrFlat iMonitor; + }; + + + + +/** +@internalComponent +*/ +class CQueueItem : public CBase + { +public: + static CQueueItem* NewL(const MNotifierBase2::TNotifierInfo& aInfo,const TDesC8& aBuffer,TInt aReplySlot, + const RMessage2& aMessage,TInt aClientId); //Asynchronous + static CQueueItem* NewL(const MNotifierBase2::TNotifierInfo& aInfo,const TDesC8& aBuffer, + TInt aClientId); //synchronous + ~CQueueItem(); +private: + CQueueItem(const MNotifierBase2::TNotifierInfo& aInfo); + void ConstructL(const TDesC8& aBuffer,TInt aClientId); + void ConstructL(const TDesC8& aBuffer,const RMessage2& aMessage,TInt aClientId,TInt aReplySlot); +public: + const MNotifierBase2::TNotifierInfo iInfo; + HBufC8* iBuffer; + TBool iAsynchronous; + RMessage2 iMessage; // IMPORTANT, we need to keep a full RMessage object until suport for V1 notifiers is removed + TInt iClientId; + TInt iReplySlot; + }; + + + + +/** +@internalComponent +*/ +class CNotifierQueue : public CBase + { +public: + static CNotifierQueue* NewL(); + inline void QueueItemL(CQueueItem* aItem); + CQueueItem* FetchItem(TUid aChannel); + TBool IsAlreadyQueued(TUid aNotifier,TUid aChannel) const; + void RemoveClient(TInt aClientId); + TInt GetHighestQueuePriority(TUid aChannel); +private: + inline CNotifierQueue(); +private: + CArrayPtrFlat iQueue; + }; + +inline TChannelActivity::TChannelActivity(TUid aChannel, TInt aHighestPriorityRunning) + :iChannel(aChannel),iHighestPriorityRunning(aHighestPriorityRunning) + {} + +inline void CChannelMonitor::AddNewChannelL(TUid aChannel) + {iMonitor.AppendL(TChannelActivity(aChannel,0));} + +inline CNotifierManager* CNotifierServer::Manager() const + {return iManager;} + +inline void CNotifierQueue::QueueItemL(CQueueItem* aItem) + {iQueue.AppendL(aItem);} +inline CNotifierQueue::CNotifierQueue() + :iQueue(3) + {} + +#endif // __TWINTNOTIFIER_H__