<?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-GENID-1-10-1-4-1-1-4-1-4-1" xml:lang="en"><title>Using+
−
the extended notifier framework</title><prolog><metadata><keywords/></metadata></prolog><conbody>+
−
<section id="GUID-41892CE3-A4CC-5761-9469-530D6D18EDFE-GENID-1-10-1-4-1-1-4-1-4-1-2-1"><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+
−
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 (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. </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-GENID-1-10-1-4-1-1-4-1-4-1-2-2"><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-GENID-1-10-1-4-1-1-4-1-4-1-2-2-3" xml:space="preserve">EXPORT_C CArrayPtr&lt;MEikSrvNotifierBase2&gt;* NotifierArray()+
−
    {+
−
    CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;* notifiers=new CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;(5);+
−
       if (notifiers)+
−
        {+
−
        TRAPD(err, CreateNotifiersL(notifiers));+
−
        if(err)+
−
            {+
−
            TInt count = notifiers-&gt;Count();+
−
            while(count--)+
−
                {+
−
                (*notifiers)[count]-&gt;Release();+
−
                }+
−
            delete notifiers;+
−
            notifiers = NULL;+
−
            }+
−
        }+
−
    return(notifiers);+
−
    }+
−
</codeblock> <note><p>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></note> <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-GENID-1-10-1-4-1-1-4-1-4-1-2-2-8" xml:space="preserve">LOCAL_C void CreateNotifiersL(CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;* aNotifiers)+
−
    {+
−
    MEikSrvNotifierBase2* notifier;+
−
    notifier = CMyNotifierA::NewL();+
−
    CleanupStack::PushL(notifier);+
−
       aNotifiers-&gt;AppendL(notifier);+
−
       CleanupStack::Pop(notifier);+
−
    ... +
−
    ...+
−
    // typically, repeat this procedure for as+
−
    // many notifiers as are implemented+
−
    // in the plug-in DLL.+
−
    }</codeblock> <note><p>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></note> </section>+
−
</conbody></concept>+
−