<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1" xml:lang="en"><title>Using

the extended notifier framework</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-41892CE3-A4CC-5761-9469-530D6D18EDFE"><title>The framework</title> <p>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, for example

UIQ and Series60, through what are known as notifier plug-ins. </p> <p>The

extended notifier framework is a system that loads these plug-in DLLs from <filepath>Z\sys\bin\notifiers</filepath>. </p> <p>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. </p> <p>The behaviour of

notifiers is supplied by providing an implementation of the <xref href="GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0.dita"><apiname>MEikSrvNotifierBase2</apiname></xref> 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. </p> <p>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 <xref href="GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0.dita"><apiname>MEikSrvNotifierBase2</apiname></xref> derived

class also needs to be implemented correctly. Notifiers run in the Uikon server

thread and are accessed on the client side via <xref href="GUID-A6B66713-FECA-3BE7-BB81-1AE5551AD83D.dita"><apiname>RNotifier</apiname></xref>.

Note that if a notifier panics it will lead to a device reset. </p> </section>

<section id="GUID-9322CFDB-D07E-54C3-86B1-13BFB082B175"><title>The factory

function</title> <p>The factory function at ordinal #1 is expected to return

an array of notifiers. The following is a typical implementation: </p> <codeblock id="GUID-F5B8C31B-110E-569A-BE9E-3986E94A506D" xml:space="preserve">EXPORT_C CArrayPtr&lt;MEikSrvNotifierBase2&gt;* 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);

    }

</codeblock> <p>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. </p> <p>Calling <codeph>Release()</codeph> on

a notifier should cause that notifier to free all of its resources, and as

a minimum should call <codeph>delete           this;</codeph>. See <xref href="GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0.dita#GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0/GUID-CF772B65-7D65-3ADC-B566-9ED2A263942F"><apiname>MEikSrvNotifierBase2::Release()</apiname></xref>. </p> <p>Returning

a <codeph>Null</codeph> value from this function causes the framework to leave

with <xref href="GUID-64F6761A-4716-37C3-8984-FF18FC8B7B7D.dita"><apiname>KErrNoMemory</apiname></xref>. </p> <p>The <codeph>CreateNotifiersL()</codeph> function

should be implemented as follows: </p> <codeblock id="GUID-15535A2D-A1F3-5A18-99B7-B2973BDFB255" xml:space="preserve">LOCAL_C void CreateNotifiersL(CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;* 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.

    }</codeblock> <p>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 <codeph>aNotifiers-&gt;AppendL(CMyNotifierA::NewL());</codeph>,

which, although shorter, will result in a memory leak if the <codeph>AppendL()</codeph> operation

fails. </p> </section>

</conbody></concept>