1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/twintnotifier.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,610 @@
1.4 +// Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// e32\include\twintnotifier.h
1.18 +// Text Window Server text notifiers.
1.19 +//
1.20 +// WARNING: This file contains some APIs which are internal and are subject
1.21 +// to change without notice. Such APIs should therefore not be used
1.22 +// outside the Kernel and Hardware Services package.
1.23 +//
1.24 +
1.25 +#ifndef __TWINTNOTIFIER_H__
1.26 +#define __TWINTNOTIFIER_H__
1.27 +
1.28 +#include <f32file.h>
1.29 +
1.30 +
1.31 +// Notifier Plugin architecture copied from UIKON
1.32 +
1.33 +
1.34 +
1.35 +/**
1.36 +@internalComponent
1.37 +*/
1.38 +_LIT(KNotifierPlugInExt,"*.*");
1.39 +
1.40 +
1.41 +
1.42 +/**
1.43 +@publishedPartner
1.44 +@released
1.45 +
1.46 +Defines the path which is searched for notifier plugin DLLs.
1.47 +*/
1.48 +_LIT(KNotifierPlugInSearchPath,"\\sys\\bin\\tnotifiers\\");
1.49 +
1.50 +
1.51 +
1.52 +/**
1.53 +@publishedPartner
1.54 +@deprecated
1.55 +*/
1.56 +const TUid KUidNotifierPlugIn={0x10005522};
1.57 +
1.58 +
1.59 +
1.60 +/**
1.61 +@publishedPartner
1.62 +@released
1.63 +*/
1.64 +const TUid KUidTextNotifierPlugInV2={0x101fe38b};
1.65 +
1.66 +
1.67 +
1.68 +/**
1.69 +@internalComponent
1.70 +*/
1.71 +_LIT8(KNotifierPaused,"Eik_Notifier_Paused");
1.72 +
1.73 +
1.74 +
1.75 +/**
1.76 +@internalComponent
1.77 +*/
1.78 +_LIT8(KNotifierResumed,"Eik_Notifier_Resumed");
1.79 +
1.80 +
1.81 +
1.82 +enum TNotExtStatus
1.83 +/**
1.84 +@internalComponent
1.85 +*/
1.86 + {
1.87 + ENotExtRequestCompleted =0,
1.88 + ENotExtRequestQueued =1,
1.89 + };
1.90 +
1.91 +
1.92 +
1.93 +
1.94 +class MNotifierManager
1.95 +/**
1.96 +@publishedPartner
1.97 +@released
1.98 +
1.99 +An interface that allows notifiers to manage their own startup and shutdown.
1.100 +
1.101 +This class is likely to be of interest to notifiers that observe engines
1.102 +using publically available APIs rather than those that are run via RNotifier
1.103 +
1.104 +@see RNotifier
1.105 +*/
1.106 + {
1.107 +public:
1.108 + /**
1.109 + Starts the specified notifier.
1.110 +
1.111 + @param aNotifierUid The Uid that identifies the notifier.
1.112 + @param aBuffer Data that can be passed from the client-side.
1.113 + The format and meaning of any data
1.114 + is implementation dependent.
1.115 + @param aResponse Data that can be returned to the client-side.
1.116 + The format and meaning of any data is implementation dependent.
1.117 + */
1.118 + virtual void StartNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)=0;
1.119 +
1.120 +
1.121 +
1.122 + /**
1.123 + Cancels the specified notifier.
1.124 +
1.125 + @param aNotifierUid The Uid that identifies the notifier.
1.126 + */
1.127 + virtual void CancelNotifier(TUid aNotifierUid)=0;
1.128 +
1.129 +
1.130 + /**
1.131 + Updates a currently active notifier with new data.
1.132 +
1.133 + @param aNotifierUid The Uid that identifies the notifier.
1.134 + @param aBuffer New data that can be passed from the client-side.
1.135 + The format and meaning of any data is implementation dependent.
1.136 + @param aResponse Data that can be returned to the client-side.
1.137 + The format and meaning of any data is implementation dependent.
1.138 + */
1.139 + virtual void UpdateNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)=0;
1.140 + };
1.141 +
1.142 +
1.143 +
1.144 +
1.145 +class MNotifierBase2
1.146 +/**
1.147 +@publishedPartner
1.148 +@released
1.149 +
1.150 +Interface to a plug-in server side notifier for the text window server.
1.151 +
1.152 +Any number of MNotifierBase2 objects can be included in a single DLL.
1.153 +All notifiers are loaded during device startup and are not destroyed until
1.154 +the notifier server closes down.
1.155 +
1.156 +Note that the text window server is not used in production ROMs.
1.157 +It is used when testing low level code.
1.158 +*/
1.159 + {
1.160 +public:
1.161 + /**
1.162 + Defines a set of notifier priorities. The use and application of these
1.163 + values is implementation dependent. ENotifierPriorityAbsolute defines
1.164 + the highest priority value; subsequent enum values define decreasing
1.165 + priority values.
1.166 + */
1.167 + enum TNotifierPriority
1.168 + {
1.169 + ENotifierPriorityAbsolute=500,
1.170 + ENotifierPriorityVHigh=400,
1.171 + ENotifierPriorityHigh=300,
1.172 + ENotifierPriorityLow=200,
1.173 + ENotifierPriorityVLow=100,
1.174 + ENotifierPriorityLowest=0
1.175 + };
1.176 +public:
1.177 + /**
1.178 + Encapsulates the notifier parameters.
1.179 + */
1.180 + class TNotifierInfo
1.181 + {
1.182 + public:
1.183 + /**
1.184 + The Uid that identifies the notifier.
1.185 + */
1.186 + TUid iUid;
1.187 +
1.188 + /**
1.189 + The Uid that identifies the channel to be used by
1.190 + the notifier (e.g. the screen, an LED etc).
1.191 + */
1.192 + TUid iChannel;
1.193 +
1.194 + /**
1.195 + The notifier priority, typically chosen from the standard set.
1.196 +
1.197 + @see MNotifierBase2::TNotifierPriority
1.198 + */
1.199 + TInt iPriority;
1.200 + };
1.201 +public:
1.202 +
1.203 +
1.204 +
1.205 + /**
1.206 + Frees all resources owned by this notifier.
1.207 +
1.208 + This function is called by the notifier framework when all resources
1.209 + allocated by notifiers should be freed. As a minimum, the implementation
1.210 + should delete this object (i.e. delete this;).
1.211 +
1.212 + Note that it is important to implement this function correctly
1.213 + to avoid memory leaks.
1.214 + */
1.215 + virtual void Release()=0;
1.216 +
1.217 +
1.218 +
1.219 + /**
1.220 + Performs any initialisation that this notifier may require.
1.221 +
1.222 + The function is called when the notifier is first loaded,
1.223 + i.e. when the plug-in DLL is loaded. It is called only once.
1.224 +
1.225 + As a minimum, the implementation should return a TNotifierInfo instance
1.226 + describing the notifier parameters. A good implementation would be to set
1.227 + up a TNotifierInfo as a data member, and then to return it. This is because
1.228 + the same information is returned by Info().
1.229 +
1.230 + The function is safe to leave from, so it is possible,
1.231 + although rarely necessary, to allocate objects as you would normally do
1.232 + in a ConstructL() function as part of two-phase construction.
1.233 +
1.234 + @return The parameters of the notifier.
1.235 +
1.236 + @see MNotifierBase2::Info
1.237 + */
1.238 + virtual TNotifierInfo RegisterL()=0;
1.239 +
1.240 +
1.241 +
1.242 + /**
1.243 + Gets the notifier parameters.
1.244 +
1.245 + This is the same information as returned by RegisterL(), although
1.246 + the returned values may be varied at run-time.
1.247 + */
1.248 + virtual TNotifierInfo Info() const=0;
1.249 +
1.250 +
1.251 +
1.252 + /**
1.253 + Starts the notifier.
1.254 +
1.255 + This is called as a result of a client-side call
1.256 + to RNotifier::StartNotifier(), which the client uses to start a notifier
1.257 + from which it does not expect a response.
1.258 +
1.259 + The function is synchronous, but it should be implemented so that
1.260 + it completes as soon as possible, allowing the notifier framework
1.261 + to enforce its priority mechanism.
1.262 +
1.263 + It is not possible to wait for a notifier to complete before returning
1.264 + from this function unless the notifier is likely to finish implementing
1.265 + its functionality immediately.
1.266 +
1.267 + @param aBuffer Data that can be passed from the client-side.
1.268 + The format and meaning of any data is implementation dependent.
1.269 +
1.270 + @return A pointer descriptor representing data for the initial response
1.271 +
1.272 + @see RNotifier::StartNotifier
1.273 + */
1.274 + virtual TPtrC8 StartL(const TDesC8& aBuffer)=0;
1.275 +
1.276 +
1.277 +
1.278 + /**
1.279 + Starts the notifier.
1.280 +
1.281 + This is called as a result of a client-side call to
1.282 + the asynchronous function RNotifier::StartNotifierAndGetResponse().
1.283 + This means that the client is waiting, asynchronously, for the notifier
1.284 + to tell the client that it has finished its work.
1.285 +
1.286 + It is important to return from this function as soon as possible,
1.287 +
1.288 + The implementation of a derived class must make sure that Complete() is
1.289 + called on the RMessage2 object when the notifier is deactivated.
1.290 +
1.291 + This function may be called multiple times if more than one client starts
1.292 + the notifier.
1.293 +
1.294 + @param aBuffer Data that can be passed from the client-side. The format
1.295 + and meaning of any data is implementation dependent.
1.296 + @param aReplySlot The offset within the message arguments for the reply.
1.297 + This message argument will refer to a modifiable
1.298 + descriptor, a TDes8 type, into which data
1.299 + can be returned. The format and meaning
1.300 + of any returned data is implementation dependent.
1.301 + @param aMessage Encapsulates a client request.
1.302 +
1.303 + @see RNotifier::StartNotifierAndGetResponse
1.304 + */
1.305 + virtual void StartL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage)=0;
1.306 +
1.307 +
1.308 +
1.309 + /**
1.310 + Cancels an active notifier.
1.311 +
1.312 + This is called as a result of a client-side call
1.313 + to RNotifier::CancelNotifier().
1.314 +
1.315 + An implementation should free any relevant resources, and complete
1.316 + any outstanding messages, if relevant.
1.317 +
1.318 + @see RNotifier::CancelNotifier
1.319 + */
1.320 + virtual void Cancel()=0;
1.321 +
1.322 +
1.323 +
1.324 + /**
1.325 + Updates a currently active notifier with new data.
1.326 +
1.327 + This is called as a result of a client-side call
1.328 + to RNotifier::UpdateNotifier().
1.329 +
1.330 + @param aBuffer Data that can be passed from the client-side.
1.331 + The format and meaning of any data is
1.332 + implementation dependent.
1.333 +
1.334 + @return A pointer descriptor representing data that may be returned.
1.335 + The format and meaning of any data is implementation dependent.
1.336 +
1.337 + @see RNotifier::UpdateNotifier
1.338 + */
1.339 + virtual TPtrC8 UpdateL(const TDesC8& aBuffer)=0;
1.340 +public:
1.341 +
1.342 +
1.343 +
1.344 + /**
1.345 + Sets the notifier manager.
1.346 +
1.347 + @param aManager A pointer to the notifier manager.
1.348 + */
1.349 + void SetManager(MNotifierManager* aManager);
1.350 +protected:
1.351 + MNotifierManager* iManager;
1.352 +private:
1.353 + TInt iNotBSpare;
1.354 + };
1.355 +
1.356 +
1.357 +
1.358 +
1.359 +
1.360 +
1.361 +// Remaining classes are internal to the text window server
1.362 +
1.363 +
1.364 +
1.365 +class CNotifierManager;
1.366 +
1.367 +/**
1.368 +@internalComponent
1.369 +*/
1.370 +class CNotifierServer : public CServer2
1.371 + {
1.372 +public:
1.373 + static CNotifierServer* NewL();
1.374 + ~CNotifierServer();
1.375 +public: // from CServer2
1.376 + CSession2* NewSessionL(const TVersion &aVersion,const RMessage2&) const;
1.377 +public:
1.378 + CNotifierServer(TInt aPriority);
1.379 + inline CNotifierManager* Manager() const;
1.380 +public:
1.381 + void SetIsExiting();
1.382 + TBool IsExiting() const;
1.383 +private:
1.384 + void ConstructL();
1.385 +private:
1.386 + CNotifierManager* iManager;
1.387 + TBool iExiting;
1.388 + };
1.389 +
1.390 +
1.391 +
1.392 +
1.393 +/**
1.394 +@internalComponent
1.395 +*/
1.396 +class CNotifierSession : public CSession2
1.397 + {
1.398 +public:
1.399 + CNotifierSession(const CNotifierServer& aServer);
1.400 + ~CNotifierSession();
1.401 +public: // from CSession2
1.402 + void ServiceL(const RMessage2& aMessage);
1.403 +private:
1.404 + enum TNotifierPanic
1.405 + {
1.406 + ENotifierPanicInconsistentDescriptorLengths=0,
1.407 + ENotifierPanicPasswordWindow,
1.408 + };
1.409 +private:
1.410 + void DisplayAlertL(const RMessage2& aMessage);
1.411 + void DisplayInfoMsgL(const RMessage2& aMessage);
1.412 + void DoStartNotifierL(const RMessage2& aMessage);
1.413 + void DoUpdateNotifierL(const RMessage2& aMessage);
1.414 + void StartNotifierAndGetResponseL(const RMessage2& aMessage,TBool& aCleanupComplete);
1.415 + void PanicClient(const RMessage2& aMessage,TNotifierPanic aCode);
1.416 + static TInt InfoPrintThread(TAny* aMessage);
1.417 + void RunPasswordWindowL(const RMessage2& aMessage);
1.418 +public:
1.419 + static RSemaphore NotifierSemaphore;
1.420 +private:
1.421 + const CNotifierServer* iServer;
1.422 + TInt iClientId;
1.423 + };
1.424 +
1.425 +
1.426 +
1.427 +
1.428 +class CQueueItem;
1.429 +class CChannelMonitor;
1.430 +class CActivityMonitor;
1.431 +class CNotifierQueue;
1.432 +
1.433 +/**
1.434 +@internalComponent
1.435 +*/
1.436 +class CNotifierManager : public CBase, public MNotifierManager
1.437 + {
1.438 +public:
1.439 + static CNotifierManager* NewL();
1.440 + ~CNotifierManager();
1.441 + void RegisterL(RFs& aFs);
1.442 + void NotifierStartL(TUid aNotifierUid,const TDesC8& aBuffer,TPtrC8* aResponse,TInt aClientId);
1.443 + TInt NotifierUpdateL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8* aResponse,TInt aClientId);
1.444 + TInt NotifierCancel(TUid aNotifierUid);
1.445 + void NotifierStartAndGetResponseL(TUid aNotifierUid,const TDesC8& aBuffer,TInt aReplySlot,
1.446 + const RMessage2& aMessage,TInt aClientId,TBool& aCleanupComplete);
1.447 + void HandleClientExit(TInt aClientId);
1.448 + void NotifierStartAndGetResponseL(TUid aNotifierUid,TUid aChannelUid,const TDesC8& aBuffer,TInt aReplySlot,
1.449 + const RMessage2& aMessage,TInt aClientId,TBool& aCleanupComplete);
1.450 +public: // from MNotifierManager
1.451 + void StartNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse);
1.452 + void CancelNotifier(TUid aNotifierUid);
1.453 + void UpdateNotifierL(TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse);
1.454 +private:
1.455 + void DoAddPlugInL(const TDesC& aPath,const TDesC& aFileName,const TUidType& aUidType);
1.456 + CNotifierManager();
1.457 + void ConstructL();
1.458 + void StartFromQueueL(CQueueItem* aItem);
1.459 +private:
1.460 + CArrayPtr<MNotifierBase2>* iObservedList;
1.461 + CArrayFix<RLibrary>* iLibraries;
1.462 + CChannelMonitor* iChannelMonitor;
1.463 + CActivityMonitor* iActivityMonitor;
1.464 + CNotifierQueue* iQueue;
1.465 + };
1.466 +
1.467 +
1.468 +
1.469 +
1.470 +/**
1.471 +@internalComponent
1.472 +*/
1.473 +class TChannelActivity
1.474 + {
1.475 +public:
1.476 + inline TChannelActivity(TUid aChannel,TInt aHighestPriorityRunning);
1.477 +public:
1.478 + TUid iChannel;
1.479 + TInt iHighestPriorityRunning;
1.480 + };
1.481 +
1.482 +
1.483 +
1.484 +
1.485 +/**
1.486 +@internalComponent
1.487 +*/
1.488 +class CChannelMonitor : public CBase
1.489 + {
1.490 +public:
1.491 + static CChannelMonitor* NewL();
1.492 + inline void AddNewChannelL(TUid aChannel);
1.493 + TBool AlreadyHasChannel(TUid aChannel) const;
1.494 + TInt ActivityLevel(TUid aChannel) const;
1.495 + void UpdateChannel(TUid aChannel,TInt aLevel);
1.496 +private:
1.497 + CChannelMonitor();
1.498 +private:
1.499 + CArrayFixFlat<TChannelActivity> iMonitor;
1.500 + };
1.501 +
1.502 +
1.503 +
1.504 +
1.505 +/**
1.506 +@internalComponent
1.507 +*/
1.508 +class CNotifierActivity : public CBase
1.509 + {
1.510 +public:
1.511 + static CNotifierActivity* NewLC(const MNotifierBase2::TNotifierInfo& aInfo,TInt aClientId);
1.512 + ~CNotifierActivity();
1.513 + TInt Find(TInt aClientId) const;
1.514 +private:
1.515 + CNotifierActivity(const MNotifierBase2::TNotifierInfo& aInfo);
1.516 + void ConstructL(TInt aClientId);
1.517 +public:
1.518 + const MNotifierBase2::TNotifierInfo iInfo;
1.519 + CArrayFixFlat<TInt> iClientArray;
1.520 + };
1.521 +
1.522 +
1.523 +
1.524 +
1.525 +/**
1.526 +@internalComponent
1.527 +*/
1.528 +class CActivityMonitor : public CBase
1.529 + {
1.530 +public:
1.531 + static CActivityMonitor* NewL();
1.532 + ~CActivityMonitor();
1.533 + void AddL(const MNotifierBase2::TNotifierInfo& aInfo,TInt aClientId);
1.534 + void Remove(TUid aNotifierUid,TInt aClientId);
1.535 + void RemoveNotifier(TUid aNotifierUid,TUid aChannel);
1.536 + void RemoveClient(TInt aClientId);
1.537 + TBool IsNotifierActive(TUid aNotifierUid,TUid aChannel) const;
1.538 + TBool IsChannelActive(TUid aChannel,TUid& aNotifier,MNotifierBase2::TNotifierPriority& aHighestPriority) const;
1.539 + TBool IsClientPresent(TUid aNotifierUid,TUid aChannel,TInt aClientId) const;
1.540 + TBool NotifierForClient(TUid& aNotifier,TInt aClientId) const;
1.541 +private:
1.542 + CActivityMonitor();
1.543 + TInt Find(TUid aNotifierUid) const;
1.544 + TInt Find(TUid aNotifierUid,TUid aChannel) const;
1.545 +private:
1.546 + CArrayPtrFlat<CNotifierActivity> iMonitor;
1.547 + };
1.548 +
1.549 +
1.550 +
1.551 +
1.552 +/**
1.553 +@internalComponent
1.554 +*/
1.555 +class CQueueItem : public CBase
1.556 + {
1.557 +public:
1.558 + static CQueueItem* NewL(const MNotifierBase2::TNotifierInfo& aInfo,const TDesC8& aBuffer,TInt aReplySlot,
1.559 + const RMessage2& aMessage,TInt aClientId); //Asynchronous
1.560 + static CQueueItem* NewL(const MNotifierBase2::TNotifierInfo& aInfo,const TDesC8& aBuffer,
1.561 + TInt aClientId); //synchronous
1.562 + ~CQueueItem();
1.563 +private:
1.564 + CQueueItem(const MNotifierBase2::TNotifierInfo& aInfo);
1.565 + void ConstructL(const TDesC8& aBuffer,TInt aClientId);
1.566 + void ConstructL(const TDesC8& aBuffer,const RMessage2& aMessage,TInt aClientId,TInt aReplySlot);
1.567 +public:
1.568 + const MNotifierBase2::TNotifierInfo iInfo;
1.569 + HBufC8* iBuffer;
1.570 + TBool iAsynchronous;
1.571 + RMessage2 iMessage; // IMPORTANT, we need to keep a full RMessage object until suport for V1 notifiers is removed
1.572 + TInt iClientId;
1.573 + TInt iReplySlot;
1.574 + };
1.575 +
1.576 +
1.577 +
1.578 +
1.579 +/**
1.580 +@internalComponent
1.581 +*/
1.582 +class CNotifierQueue : public CBase
1.583 + {
1.584 +public:
1.585 + static CNotifierQueue* NewL();
1.586 + inline void QueueItemL(CQueueItem* aItem);
1.587 + CQueueItem* FetchItem(TUid aChannel);
1.588 + TBool IsAlreadyQueued(TUid aNotifier,TUid aChannel) const;
1.589 + void RemoveClient(TInt aClientId);
1.590 + TInt GetHighestQueuePriority(TUid aChannel);
1.591 +private:
1.592 + inline CNotifierQueue();
1.593 +private:
1.594 + CArrayPtrFlat<CQueueItem> iQueue;
1.595 + };
1.596 +
1.597 +inline TChannelActivity::TChannelActivity(TUid aChannel, TInt aHighestPriorityRunning)
1.598 + :iChannel(aChannel),iHighestPriorityRunning(aHighestPriorityRunning)
1.599 + {}
1.600 +
1.601 +inline void CChannelMonitor::AddNewChannelL(TUid aChannel)
1.602 + {iMonitor.AppendL(TChannelActivity(aChannel,0));}
1.603 +
1.604 +inline CNotifierManager* CNotifierServer::Manager() const
1.605 + {return iManager;}
1.606 +
1.607 +inline void CNotifierQueue::QueueItemL(CQueueItem* aItem)
1.608 + {iQueue.AppendL(aItem);}
1.609 +inline CNotifierQueue::CNotifierQueue()
1.610 + :iQueue(3)
1.611 + {}
1.612 +
1.613 +#endif // __TWINTNOTIFIER_H__