--- /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 <f32file.h>
+
+
+// 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<MNotifierBase2>* iObservedList;
+ CArrayFix<RLibrary>* 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<TChannelActivity> 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<TInt> 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<CNotifierActivity> 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<CQueueItem> 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__