Notifier +framework

The framework

The +text window server notifier framework is a system that loads plug-in DLLs +from \sys\bin\tnotifiers.

It is used only in +test ROMs and is never used in production code. For production code, use the +Extended Notifier Framework. The architecture of both frameworks is identical; +however, the interface classes have different names.

These DLLs are +expected to export a single factory function at ordinal #1 that returns an +array of notifiers. A special notifier target type is supported by makmake. +The second Uid for notifiers should be 0x10005522.

The behaviour of +notifiers is supplied by providing an implementation of the MNotifierBase interface. +A notifier is associated with a channel and a priority. Priority is used to +determine the order of activation if more than one notifier is activated at +any time. Priority only affects notifiers on the same channel (e.g. a screen +or LED). This means that two notifiers can be active at the same time provided +that they are on different channels.

The channel and priority used +by all the notifiers in the system needs to be considered carefully to avoid +them interfering with each other in unexpected ways. The MNotifierBase derived +class also needs to be implemented correctly. Text window server notifiers +run in the window server thread and are accessed on the client side via RNotifier. +Note that if a notifier panics it will lead to a device reset.

The factory +function

The factory function at ordinal #1 is expected to return +an array of notifiers. The following is a typical implementation:

EXPORT_C CArrayPtr<MNotifierBase>* NotifierArray() + { + CArrayPtrFlat<MNotifierBase>* notifiers=new CArrayPtrFlat<MNotifierBase>(5); + if (notifiers) + { + TRAPD(err, CreateNotifiersL(notifiers)); + if(err) + { + TInt count = notifiers->Count(); + while(count--) + { + (*notifiers)[count]->Release(); + } + delete notifiers; + notifiers = NULL; + } + } + return(notifiers); + } +

Note that ownership of the notifier array or its contents +is not transferred to the framework until this function returns. To avoid +memory leaks, all acquired resources must be freed if anything goes wrong +part of the way through its processing.

Calling Release() on +a notifier should cause that notifier to free all of its resources, and as +a minimum should call delete this;. See MNotifierBase::Release().

Returning +a Null value from this function causes the framework to leave +with KErrNoMemory.

The CreateNotifiersL() function +should be implemented as follows:

LOCAL_C void CreateNotifiersL(CArrayPtrFlat<MNotifierBase>* aNotifiers) + { + MNotifierBase* notifier; + notifier = CMyNotifierA::NewL(); + CleanupStack::PushL(notifier); + aNotifiers->AppendL(notifier); + CleanupStack::Pop(notifier); + ... + ... + // typically, repeat this procedure for as + // many notifiers as are implemented + // in the plug-in DLL. + }

Note the use of the standard Symbian platform technique +of using the cleanup stack to hold pointers to allocated objects for as long +as these objects have no owner; this prevents memory leaks. For this reason, +avoid using a technique such as aNotifiers->AppendL(CMyNotifierA::NewL());, +which, although shorter, will result in a memory leak if the AppendL() operation +fails.