// 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__