Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-10-1-6-1-1-3-1-10-1.dita
changeset 8 ae94777fff8f
equal deleted inserted replaced
7:51a74ef9ed63 8:ae94777fff8f
       
     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-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-10-1-6-1-1-3-1-10-1" xml:lang="en"><title>Using
       
    13 the extended notifier framework</title><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    14 <section id="GUID-41892CE3-A4CC-5761-9469-530D6D18EDFE-GENID-1-10-1-6-1-1-3-1-10-1-2-1"><title>The framework</title> <p>Notifiers
       
    15 allow components with no direct UI linkage to interact with the user via an
       
    16 interface such as a dialog box. For example, a low level component might want
       
    17 to warn the user about a low battery level. Typically, such a component would
       
    18 not have direct access, or knowledge of, a UI. The solution to this problem
       
    19 is provided by what are known as notifiers and the extended notifier framework.
       
    20 The UI element (the dialog box) is provided by the device's UI
       
    21 through what are known as notifier plug-ins. </p> <p>The extended notifier
       
    22 framework is a system that loads these plug-in DLLs from <filepath>Z\sys\bin\notifiers</filepath>. </p> <p>These
       
    23 DLLs are expected to export a single factory function at ordinal #1 that returns
       
    24 an array of notifiers. A special notifier target type is supported by makmake.
       
    25 The second Uid for notifiers should be 0x10005522. </p> <p>The behaviour of
       
    26 notifiers is supplied by providing an implementation of the <xref href="GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0.dita"><apiname>MEikSrvNotifierBase2</apiname></xref> interface
       
    27 . A notifier is associated with a channel and a priority. Priority is used
       
    28 to determine the order of activation if more than one notifier is activated
       
    29 at any time. Priority only affects notifiers on the same channel (for example,
       
    30 a screen or LED). This means that two notifiers can be active at the same
       
    31 time provided that they are on different channels. </p> <p>The channel and
       
    32 priority used by all the notifiers in the system needs to be considered carefully
       
    33 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
       
    34 class also needs to be implemented correctly. Notifiers run in the UIKON server
       
    35 thread and are accessed on the client side via <xref href="GUID-A6B66713-FECA-3BE7-BB81-1AE5551AD83D.dita"><apiname>RNotifier</apiname></xref>.
       
    36 Note that if a notifier panics it will lead to a device reset. </p> </section>
       
    37 <section id="GUID-9322CFDB-D07E-54C3-86B1-13BFB082B175-GENID-1-10-1-6-1-1-3-1-10-1-2-2"><title>The factory
       
    38 function</title> <p>The factory function at ordinal #1 is expected to return
       
    39 an array of notifiers. The following is a typical implementation: </p> <codeblock id="GUID-F5B8C31B-110E-569A-BE9E-3986E94A506D-GENID-1-10-1-6-1-1-3-1-10-1-2-2-3" xml:space="preserve">EXPORT_C CArrayPtr&lt;MEikSrvNotifierBase2&gt;* NotifierArray()
       
    40     {
       
    41     CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;* notifiers=new CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;(5);
       
    42        if (notifiers)
       
    43         {
       
    44         TRAPD(err, CreateNotifiersL(notifiers));
       
    45         if(err)
       
    46             {
       
    47             TInt count = notifiers-&gt;Count();
       
    48             while(count--)
       
    49                 {
       
    50                 (*notifiers)[count]-&gt;Release();
       
    51                 }
       
    52             delete notifiers;
       
    53             notifiers = NULL;
       
    54             }
       
    55         }
       
    56     return(notifiers);
       
    57     }
       
    58 </codeblock> <note><p>Ownership of the notifier array or its contents is not
       
    59 transferred to the framework until this function returns. To avoid memory
       
    60 leaks, all acquired resources must be freed if anything goes wrong part of
       
    61 the way through its processing. </p></note> <p>Calling <codeph>Release()</codeph> on
       
    62 a notifier should cause that notifier to free all of its resources, and as
       
    63 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
       
    64 a <codeph>Null</codeph> value from this function causes the framework to leave
       
    65 with <xref href="GUID-64F6761A-4716-37C3-8984-FF18FC8B7B7D.dita"><apiname>KErrNoMemory</apiname></xref>. </p> <p>The <codeph>CreateNotifiersL()</codeph> function
       
    66 should be implemented as follows: </p> <codeblock id="GUID-15535A2D-A1F3-5A18-99B7-B2973BDFB255-GENID-1-10-1-6-1-1-3-1-10-1-2-2-8" xml:space="preserve">LOCAL_C void CreateNotifiersL(CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;* aNotifiers)
       
    67     {
       
    68     MEikSrvNotifierBase2* notifier;
       
    69     notifier = CMyNotifierA::NewL();
       
    70     CleanupStack::PushL(notifier);
       
    71        aNotifiers-&gt;AppendL(notifier);
       
    72        CleanupStack::Pop(notifier);
       
    73     ... 
       
    74     ...
       
    75     // typically, repeat this procedure for as
       
    76     // many notifiers as are implemented
       
    77     // in the plug-in DLL.
       
    78     }</codeblock> <note><p>Use of the standard Symbian platform technique
       
    79 of using the cleanup stack to hold pointers to allocated objects for as long
       
    80 as these objects have no owner; this prevents memory leaks. For this reason,
       
    81 avoid using a technique such as <codeph>aNotifiers-&gt;AppendL(CMyNotifierA::NewL());</codeph>,
       
    82 which, although shorter, will result in a memory leak if the <codeph>AppendL()</codeph> operation
       
    83 fails. </p></note> </section>
       
    84 </conbody></concept>