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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // e32\include\twintnotifier.h

    15 // Text Window Server text notifiers.

    16 // 

    17 // WARNING: This file contains some APIs which are internal and are subject

    18 //          to change without notice. Such APIs should therefore not be used

    19 //          outside the Kernel and Hardware Services package.

    20 //

    21 

    22 #ifndef __TWINTNOTIFIER_H__

    23 #define __TWINTNOTIFIER_H__

    24 

    25 #include <f32file.h>

    26 

    27 

    28 //  Notifier Plugin architecture copied from UIKON

    29 

    30 

    31 

    32 /**

    33 @internalComponent

    34 */

    35 _LIT(KNotifierPlugInExt,"*.*");

    36 

    37 

    38 

    39 /**

    40 @publishedPartner

    41 @released

    42 

    43 Defines the path which is searched for notifier plugin DLLs.

    44 */

    45 _LIT(KNotifierPlugInSearchPath,"\\sys\\bin\\tnotifiers\\");

    46 

    47 

    48 

    49 /**

    50 @publishedPartner

    51 @deprecated

    52 */

    53 const TUid KUidNotifierPlugIn={0x10005522}; 

    54 

    55 

    56 

    57 /**

    58 @publishedPartner

    59 @released

    60 */

    61 const TUid KUidTextNotifierPlugInV2={0x101fe38b}; 

    62 

    63 

    64 

    65 /**

    66 @internalComponent

    67 */

    68 _LIT8(KNotifierPaused,"Eik_Notifier_Paused");

    69 

    70 

    71 

    72 /**

    73 @internalComponent

    74 */

    75 _LIT8(KNotifierResumed,"Eik_Notifier_Resumed");

    76 

    77 

    78 

    79 enum TNotExtStatus

    80 /**

    81 @internalComponent

    82 */

    83 	{

    84 	ENotExtRequestCompleted	=0,

    85 	ENotExtRequestQueued	=1,

    86 	};

    87 

    88 

    89 

    90 

    91 class MNotifierManager

    92 /**

    93 @publishedPartner

    94 @released

    95 

    96 An interface that allows notifiers to manage their own startup and shutdown.

    97 

    98 This class is likely to be of interest to notifiers that observe engines

    99 using publically available APIs rather than those that are run via RNotifier

   100 

   101 @see RNotifier

   102 */

   103 	{

   104 public:

   105     /**

   106     Starts the specified notifier.

   107 

   108 	@param aNotifierUid The Uid that identifies the notifier.

   109 	@param aBuffer      Data that can be passed from the client-side.

   110 	                    The format and meaning of any data

   111 	                    is implementation dependent.

   112 	@param aResponse    Data that can be returned to the client-side.

   113 						The format and meaning of any data is implementation dependent.

   114 	*/

   115 	virtual void StartNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)=0;

   116 	

   117 	

   118 	

   119     /**

   120     Cancels the specified notifier.

   121  	

   122  	@param aNotifierUid The Uid that identifies the notifier.

   123     */

   124 	virtual void CancelNotifier(TUid aNotifierUid)=0;

   125 	

   126 	

   127     /**

   128     Updates a currently active notifier with new data.

   129     

   130     @param aNotifierUid The Uid that identifies the notifier.

   131     @param aBuffer      New data that can be passed from the client-side.

   132                         The format and meaning of any data is implementation dependent.

   133     @param aResponse    Data that can be returned to the client-side.

   134                         The format and meaning of any data is implementation dependent.

   135     */

   136 	virtual void UpdateNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)=0;

   137 	};

   138 

   139 

   140 

   141 

   142 class MNotifierBase2

   143 /**

   144 @publishedPartner

   145 @released

   146 

   147 Interface to a plug-in server side notifier for the text window server.

   148 

   149 Any number of MNotifierBase2 objects can be included in a single DLL.

   150 All notifiers are loaded during device startup and are not destroyed until

   151 the notifier server closes down.

   152 

   153 Note that the text window server is not used in production ROMs.

   154 It is used when testing low level code.

   155 */

   156 	{

   157 public:

   158     /**

   159     Defines a set of notifier priorities. The use and application of these

   160     values is implementation dependent. ENotifierPriorityAbsolute defines

   161     the highest priority value; subsequent enum values define decreasing

   162     priority values.

   163     */

   164 	enum TNotifierPriority

   165 		{

   166 		ENotifierPriorityAbsolute=500,

   167 		ENotifierPriorityVHigh=400,	

   168 		ENotifierPriorityHigh=300,	

   169 		ENotifierPriorityLow=200,	

   170 		ENotifierPriorityVLow=100,	

   171 		ENotifierPriorityLowest=0	

   172 		};

   173 public:

   174     /**

   175     Encapsulates the notifier parameters.

   176     */

   177 	class TNotifierInfo

   178 		{

   179 	public:

   180 	    /**

   181 	    The Uid that identifies the notifier.

   182         */

   183 		TUid iUid;

   184 		

   185 		/**

   186 		The Uid that identifies the channel to be used by

   187 		the notifier (e.g. the screen, an LED etc).

   188 	    */

   189 		TUid iChannel;

   190 		

   191 	    /**

   192 	    The notifier priority, typically chosen from the standard set.

   193 	    

   194 	    @see MNotifierBase2::TNotifierPriority

   195 	    */

   196 		TInt iPriority;

   197 		};

   198 public:

   199 

   200 

   201 

   202 	/**

   203 	Frees all resources owned by this notifier.

   204 

   205     This function is called by the notifier framework when all resources

   206     allocated by notifiers should be freed. As a minimum, the implementation

   207     should delete this object (i.e. delete this;).

   208 

   209     Note that it is important to implement this function correctly

   210     to avoid memory leaks.

   211 	*/

   212 	virtual void Release()=0;

   213 

   214 

   215 		

   216     /**

   217     Performs any initialisation that this notifier may require.

   218 

   219     The function is called when the notifier is first loaded,

   220     i.e. when the plug-in DLL is loaded. It is called only once.

   221 

   222     As a minimum, the implementation should return a TNotifierInfo instance

   223     describing the notifier parameters. A good implementation would be to set

   224     up a TNotifierInfo as a data member, and then to return it. This is because

   225     the same information is returned by Info().

   226 

   227     The function is safe to leave from, so it is possible,

   228     although rarely necessary, to allocate objects as you would normally do

   229     in a ConstructL() function as part of two-phase construction.

   230 

   231 	@return The parameters of the notifier.

   232 

   233 	@see MNotifierBase2::Info

   234     */	 

   235 	virtual TNotifierInfo RegisterL()=0;

   236 

   237 

   238 

   239 	/**

   240 	Gets the notifier parameters.

   241 

   242     This is the same information as returned by RegisterL(), although

   243     the returned values may be varied at run-time.

   244 	*/

   245 	virtual TNotifierInfo Info() const=0;

   246 

   247 

   248 

   249 	/**

   250 	Starts the notifier.

   251 

   252     This is called as a result of a client-side call

   253     to RNotifier::StartNotifier(), which the client uses to start a notifier

   254     from which it does not expect a response.

   255 

   256     The function is synchronous, but it should be implemented so that

   257     it completes as soon as possible, allowing the notifier framework

   258     to enforce its priority mechanism.

   259 

   260     It is not possible to wait for a notifier to complete before returning

   261     from this function unless the notifier is likely to finish implementing

   262     its functionality immediately.

   263 

   264 	@param	aBuffer Data that can be passed from the client-side.

   265 	        The format and meaning of any data is implementation dependent.

   266 	        

   267 	@return A pointer descriptor representing data for the initial response

   268 

   269 	@see RNotifier::StartNotifier

   270 	*/ 

   271 	virtual TPtrC8 StartL(const TDesC8& aBuffer)=0;

   272 

   273 

   274 

   275 	/**

   276 	Starts the notifier.

   277 

   278     This is called as a result of a client-side call to

   279     the asynchronous function RNotifier::StartNotifierAndGetResponse().

   280     This means that the client is waiting, asynchronously, for the notifier

   281     to tell the client that it has finished its work.

   282 

   283     It is important to return from this function as soon as possible,

   284     

   285     The implementation of a derived class must make sure that Complete() is

   286     called on the RMessage2 object when the notifier is deactivated.

   287 

   288     This function may be called multiple times if more than one client starts

   289     the notifier.

   290 

   291     @param aBuffer    Data that can be passed from the client-side. The format

   292                       and meaning of any data is implementation dependent.

   293     @param aReplySlot The offset within the message arguments for the reply.

   294                       This message argument will refer to a modifiable

   295                       descriptor, a TDes8 type, into which data

   296                       can be returned. The format and meaning

   297                       of any returned data is implementation dependent.

   298     @param aMessage   Encapsulates a client request.

   299     

   300     @see RNotifier::StartNotifierAndGetResponse

   301     */

   302 	virtual void StartL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage)=0;

   303 	

   304 	

   305 	

   306 	/**

   307 	Cancels an active notifier.

   308 

   309     This is called as a result of a client-side call

   310     to RNotifier::CancelNotifier().

   311 

   312     An implementation should free any relevant resources, and complete

   313     any outstanding messages, if relevant.

   314     

   315     @see RNotifier::CancelNotifier

   316 	*/ 

   317 	virtual void Cancel()=0;

   318 

   319 

   320 

   321 	/**

   322 	Updates a currently active notifier with new data.

   323 

   324 	This is called as a result of a client-side call

   325 	to RNotifier::UpdateNotifier().

   326 	

   327 	@param aBuffer Data that can be passed from the client-side.

   328 	               The format and meaning of any data is

   329 	               implementation dependent.

   330 	

   331 	@return A pointer descriptor representing data that may be returned.

   332 	        The format and meaning of any data is implementation dependent.

   333 

   334 	@see RNotifier::UpdateNotifier

   335 	*/ 

   336 	virtual TPtrC8 UpdateL(const TDesC8& aBuffer)=0;

   337 public:

   338 

   339 

   340 

   341 	/**

   342 	Sets the notifier manager.

   343 

   344 	@param aManager A pointer to the notifier manager.

   345 	*/

   346 	void SetManager(MNotifierManager* aManager);

   347 protected:

   348 	MNotifierManager* iManager;

   349 private:

   350 	TInt iNotBSpare;

   351 	};

   352 

   353 

   354 

   355 

   356 

   357 

   358 // Remaining classes are internal to the text window server

   359 

   360 

   361 

   362 class CNotifierManager;

   363 

   364 /**

   365 @internalComponent

   366 */

   367 class CNotifierServer : public CServer2

   368 	{

   369 public:

   370 	static CNotifierServer* NewL();

   371 	~CNotifierServer();

   372 public: // from CServer2

   373 	CSession2* NewSessionL(const TVersion &aVersion,const RMessage2&) const;

   374 public:

   375 	CNotifierServer(TInt aPriority);

   376 	inline CNotifierManager* Manager() const;

   377 public:

   378 	void SetIsExiting();

   379 	TBool IsExiting() const;

   380 private:

   381 	void ConstructL();

   382 private:

   383 	CNotifierManager* iManager;

   384 	TBool iExiting;

   385 	};

   386 

   387 

   388 

   389 

   390 /**

   391 @internalComponent

   392 */

   393 class CNotifierSession : public CSession2

   394 	{

   395 public:

   396 	CNotifierSession(const CNotifierServer& aServer);

   397 	~CNotifierSession();

   398 public: // from CSession2

   399 	void ServiceL(const RMessage2& aMessage);

   400 private:

   401 	enum TNotifierPanic

   402 		{

   403 		ENotifierPanicInconsistentDescriptorLengths=0,

   404 		ENotifierPanicPasswordWindow,

   405 		};

   406 private:

   407 	void DisplayAlertL(const RMessage2& aMessage);

   408 	void DisplayInfoMsgL(const RMessage2& aMessage);

   409 	void DoStartNotifierL(const RMessage2& aMessage);

   410 	void DoUpdateNotifierL(const RMessage2& aMessage);

   411 	void StartNotifierAndGetResponseL(const RMessage2& aMessage,TBool& aCleanupComplete);

   412 	void PanicClient(const RMessage2& aMessage,TNotifierPanic aCode);

   413 	static TInt InfoPrintThread(TAny* aMessage);

   414 	void RunPasswordWindowL(const RMessage2& aMessage);

   415 public:

   416 	static RSemaphore NotifierSemaphore;

   417 private:

   418 	const CNotifierServer* iServer;

   419 	TInt iClientId;

   420 	};

   421 

   422 

   423 

   424 

   425 class CQueueItem;

   426 class CChannelMonitor;

   427 class CActivityMonitor;

   428 class CNotifierQueue;

   429 

   430 /**

   431 @internalComponent

   432 */

   433 class CNotifierManager : public CBase, public MNotifierManager

   434 	{

   435 public:

   436 	static CNotifierManager* NewL();

   437 	~CNotifierManager();

   438 	void RegisterL(RFs& aFs);

   439 	void NotifierStartL(TUid aNotifierUid,const TDesC8& aBuffer,TPtrC8* aResponse,TInt aClientId);

   440 	TInt NotifierUpdateL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8* aResponse,TInt aClientId);

   441 	TInt NotifierCancel(TUid aNotifierUid);

   442 	void NotifierStartAndGetResponseL(TUid aNotifierUid,const TDesC8& aBuffer,TInt aReplySlot,

   443 										const RMessage2& aMessage,TInt aClientId,TBool& aCleanupComplete);

   444 	void HandleClientExit(TInt aClientId);

   445 	void NotifierStartAndGetResponseL(TUid aNotifierUid,TUid aChannelUid,const TDesC8& aBuffer,TInt aReplySlot,

   446 										const RMessage2& aMessage,TInt aClientId,TBool& aCleanupComplete);

   447 public: // from MNotifierManager

   448 	void StartNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse);

   449 	void CancelNotifier(TUid aNotifierUid);

   450 	void UpdateNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse);

   451 private:

   452 	void DoAddPlugInL(const TDesC& aPath,const TDesC& aFileName,const TUidType& aUidType);

   453 	CNotifierManager();

   454 	void ConstructL();

   455 	void StartFromQueueL(CQueueItem* aItem);

   456 private:

   457 	CArrayPtr<MNotifierBase2>* iObservedList;

   458 	CArrayFix<RLibrary>* iLibraries;

   459 	CChannelMonitor* iChannelMonitor;

   460 	CActivityMonitor* iActivityMonitor;

   461 	CNotifierQueue* iQueue;

   462 	};

   463 

   464 

   465 

   466 

   467 /**

   468 @internalComponent

   469 */

   470 class TChannelActivity

   471 	{

   472 public:

   473 	inline TChannelActivity(TUid aChannel,TInt aHighestPriorityRunning);

   474 public:

   475 	TUid iChannel;

   476 	TInt iHighestPriorityRunning;

   477 	};

   478 

   479 

   480 

   481 	

   482 /**

   483 @internalComponent

   484 */

   485 class CChannelMonitor : public CBase

   486 	{

   487 public:

   488 	static CChannelMonitor* NewL();

   489 	inline void AddNewChannelL(TUid aChannel);

   490 	TBool AlreadyHasChannel(TUid aChannel) const;

   491 	TInt ActivityLevel(TUid aChannel) const;

   492 	void UpdateChannel(TUid aChannel,TInt aLevel);

   493 private:

   494 	CChannelMonitor();

   495 private:

   496 	CArrayFixFlat<TChannelActivity> iMonitor;

   497 	};

   498 

   499 

   500 

   501 

   502 /**

   503 @internalComponent

   504 */

   505 class CNotifierActivity : public CBase

   506 	{

   507 public:

   508 	static CNotifierActivity* NewLC(const MNotifierBase2::TNotifierInfo& aInfo,TInt aClientId);

   509 	~CNotifierActivity();

   510 	TInt Find(TInt aClientId) const;

   511 private:

   512 	CNotifierActivity(const MNotifierBase2::TNotifierInfo& aInfo);

   513 	void ConstructL(TInt aClientId);

   514 public:

   515 	const MNotifierBase2::TNotifierInfo iInfo;

   516 	CArrayFixFlat<TInt> iClientArray;

   517 	};

   518 

   519 

   520 

   521 

   522 /**

   523 @internalComponent

   524 */

   525 class CActivityMonitor : public CBase

   526 	{

   527 public:

   528 	static CActivityMonitor* NewL();

   529 	~CActivityMonitor();

   530 	void AddL(const MNotifierBase2::TNotifierInfo& aInfo,TInt aClientId);

   531 	void Remove(TUid aNotifierUid,TInt aClientId);

   532 	void RemoveNotifier(TUid aNotifierUid,TUid aChannel);

   533 	void RemoveClient(TInt aClientId);

   534 	TBool IsNotifierActive(TUid aNotifierUid,TUid aChannel) const;

   535 	TBool IsChannelActive(TUid aChannel,TUid& aNotifier,MNotifierBase2::TNotifierPriority& aHighestPriority) const;

   536 	TBool IsClientPresent(TUid aNotifierUid,TUid aChannel,TInt aClientId) const;

   537 	TBool NotifierForClient(TUid& aNotifier,TInt aClientId) const;

   538 private:

   539 	CActivityMonitor();

   540 	TInt Find(TUid aNotifierUid) const;

   541 	TInt Find(TUid aNotifierUid,TUid aChannel) const;

   542 private:

   543 	CArrayPtrFlat<CNotifierActivity> iMonitor;

   544 	};

   545 

   546 

   547 

   548 

   549 /**

   550 @internalComponent

   551 */

   552 class CQueueItem : public CBase

   553 	{

   554 public:

   555 	static CQueueItem* NewL(const MNotifierBase2::TNotifierInfo& aInfo,const TDesC8& aBuffer,TInt aReplySlot,

   556 										const RMessage2& aMessage,TInt aClientId); //Asynchronous

   557 	static CQueueItem* NewL(const MNotifierBase2::TNotifierInfo& aInfo,const TDesC8& aBuffer,

   558 										TInt aClientId); //synchronous

   559 	~CQueueItem();

   560 private:

   561 	CQueueItem(const MNotifierBase2::TNotifierInfo& aInfo);

   562 	void ConstructL(const TDesC8& aBuffer,TInt aClientId);

   563 	void ConstructL(const TDesC8& aBuffer,const RMessage2& aMessage,TInt aClientId,TInt aReplySlot);

   564 public:

   565 	const MNotifierBase2::TNotifierInfo iInfo;

   566 	HBufC8* iBuffer;

   567 	TBool iAsynchronous;

   568 	RMessage2 iMessage;  // IMPORTANT, we need to keep a full RMessage object until suport for V1 notifiers is removed

   569 	TInt iClientId;

   570 	TInt iReplySlot;

   571 	};

   572 

   573 

   574 

   575 

   576 /**

   577 @internalComponent

   578 */

   579 class CNotifierQueue : public CBase

   580 	{

   581 public:

   582 	static CNotifierQueue* NewL();

   583 	inline void QueueItemL(CQueueItem* aItem);

   584 	CQueueItem* FetchItem(TUid aChannel);

   585 	TBool IsAlreadyQueued(TUid aNotifier,TUid aChannel) const;

   586 	void RemoveClient(TInt aClientId);

   587 	TInt GetHighestQueuePriority(TUid aChannel);

   588 private:

   589 	inline CNotifierQueue();

   590 private:

   591 	CArrayPtrFlat<CQueueItem> iQueue;

   592 	};

   593 

   594 inline TChannelActivity::TChannelActivity(TUid aChannel, TInt aHighestPriorityRunning)

   595 	:iChannel(aChannel),iHighestPriorityRunning(aHighestPriorityRunning)

   596 	{}

   597 

   598 inline void CChannelMonitor::AddNewChannelL(TUid aChannel)

   599 	{iMonitor.AppendL(TChannelActivity(aChannel,0));}

   600 

   601 inline CNotifierManager* CNotifierServer::Manager() const

   602 	{return iManager;}

   603 

   604 inline void CNotifierQueue::QueueItemL(CQueueItem* aItem)

   605 	{iQueue.AppendL(aItem);}

   606 inline CNotifierQueue::CNotifierQueue()

   607 	:iQueue(3)

   608 	{}

   609 

   610 #endif	// __TWINTNOTIFIER_H__