Using -the extended notifier framework

The framework

Notifiers -allow components with no direct UI linkage to interact with the user via an -interface such as a dialog box. For example, a low level component might want -to warn the user about a low battery level. Typically, such a component would -not have direct access, or knowledge of, a UI. The solution to this problem -is provided by what are known as notifiers and the extended notifier framework. -The UI element (the dialog box) is provided by the device's UI -through what are known as notifier plug-ins.

The extended notifier -framework is a system that loads these plug-in DLLs from Z\sys\bin\notifiers.

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 MEikSrvNotifierBase2 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 (for example, -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 MEikSrvNotifierBase2 derived -class also needs to be implemented correctly. Notifiers run in the UIKON 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<MEikSrvNotifierBase2>* NotifierArray() - { - CArrayPtrFlat<MEikSrvNotifierBase2>* notifiers=new CArrayPtrFlat<MEikSrvNotifierBase2>(5); - if (notifiers) - { - TRAPD(err, CreateNotifiersL(notifiers)); - if(err) - { - TInt count = notifiers->Count(); - while(count--) - { - (*notifiers)[count]->Release(); - } - delete notifiers; - notifiers = NULL; - } - } - return(notifiers); - } -

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 MEikSrvNotifierBase2::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<MEikSrvNotifierBase2>* aNotifiers) - { - MEikSrvNotifierBase2* 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. - }

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.