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.

+ + + + + +Notifier +frameworkThis document describes the 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.

\ No newline at end of file