--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-10-1-6-1-1-3-1-10-1.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,84 @@
+<?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-6-1-1-3-1-10-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-6-1-1-3-1-10-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-6-1-1-3-1-10-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-6-1-1-3-1-10-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-6-1-1-3-1-10-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>
\ No newline at end of file