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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-E634E701-0DA2-572E-852B-8A1F88F05E5A" xml:lang="en"><title>Notifier

    13 framework</title><shortdesc>This document describes the notifier framework.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-CED154FC-CFBE-5E07-843B-D409660C5816"><title>The framework</title> <p>The

    15 text window server notifier framework is a system that loads plug-in DLLs

    16 from <filepath>\sys\bin\tnotifiers</filepath>. </p> <p>It is used only in

    17 test ROMs and is never used in production code. For production code, use the

    18 Extended Notifier Framework. The architecture of both frameworks is identical;

    19 however, the interface classes have different names. </p> <p>These DLLs are

    20 expected to export a single factory function at ordinal #1 that returns an

    21 array of notifiers. A special notifier target type is supported by makmake.

    22 The second Uid for notifiers should be 0x10005522. </p> <p>The behaviour of

    23 notifiers is supplied by providing an implementation of the <xref href="GUID-E2C0E005-4138-3C2A-839C-ADB9C935F64B.dita"><apiname>MNotifierBase</apiname></xref> interface.

    24 A notifier is associated with a channel and a priority. Priority is used to

    25 determine the order of activation if more than one notifier is activated at

    26 any time. Priority only affects notifiers on the same channel (e.g. a screen

    27 or LED). This means that two notifiers can be active at the same time provided

    28 that they are on different channels. </p> <p>The channel and priority used

    29 by all the notifiers in the system needs to be considered carefully to avoid

    30 them interfering with each other in unexpected ways. The <xref href="GUID-E2C0E005-4138-3C2A-839C-ADB9C935F64B.dita"><apiname>MNotifierBase</apiname></xref> derived

    31 class also needs to be implemented correctly. Text window server notifiers

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

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

    34 <section id="GUID-DA49D735-4C8E-5EFD-A170-5E5A23D30884"><title>The factory

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

    36 an array of notifiers. The following is a typical implementation: </p> <codeblock id="GUID-389A6F11-4700-5423-B7CA-B8F5F0E4391D" xml:space="preserve">EXPORT_C CArrayPtr&lt;MNotifierBase&gt;* NotifierArray()

    37     {

    38     CArrayPtrFlat<MNotifierBase>* notifiers=new CArrayPtrFlat<MNotifierBase>(5);

    39        if (notifiers)

    40         {

    41         TRAPD(err, CreateNotifiersL(notifiers));

    42         if(err)

    43             {

    44             TInt count = notifiers->Count();

    45             while(count--)

    46                 {

    47                 (*notifiers)[count]->Release();

    48                 }

    49             delete notifiers;

    50             notifiers = NULL;

    51             }

    52         }

    53     return(notifiers);

    54     }

    55 </codeblock> <p>Note that ownership of the notifier array or its contents

    56 is not transferred to the framework until this function returns. To avoid

    57 memory leaks, all acquired resources must be freed if anything goes wrong

    58 part of the way through its processing. </p> <p>Calling <codeph>Release()</codeph> on

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

    60 a minimum should call <codeph>delete           this;</codeph>. See <xref href="GUID-E2C0E005-4138-3C2A-839C-ADB9C935F64B.dita#GUID-E2C0E005-4138-3C2A-839C-ADB9C935F64B/GUID-ADFAC896-1888-3BFF-9335-1CF83B9726A4"><apiname>MNotifierBase::Release()</apiname></xref>. </p> <p>Returning

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

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

    63 should be implemented as follows: </p> <codeblock id="GUID-3CC86675-ECC5-59E4-8CD3-86AD0BAE0B90" xml:space="preserve">LOCAL_C void CreateNotifiersL(CArrayPtrFlat&lt;MNotifierBase&gt;* aNotifiers)

    64     {

    65     MNotifierBase* notifier;

    66     notifier = CMyNotifierA::NewL();

    67     CleanupStack::PushL(notifier);

    68        aNotifiers->AppendL(notifier);

    69        CleanupStack::Pop(notifier);

    70     ... 

    71     ...

    72     // typically, repeat this procedure for as

    73     // many notifiers as are implemented

    74     // in the plug-in DLL.

    75     }</codeblock> <p>Note the use of the standard Symbian platform technique

    76 of using the cleanup stack to hold pointers to allocated objects for as long

    77 as these objects have no owner; this prevents memory leaks. For this reason,

    78 avoid using a technique such as <codeph>aNotifiers-&gt;AppendL(CMyNotifierA::NewL());</codeph>,

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

    80 fails. </p> </section>

    81 </conbody></concept>