--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-E634E701-0DA2-572E-852B-8A1F88F05E5A.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,81 @@
+<?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-E634E701-0DA2-572E-852B-8A1F88F05E5A" xml:lang="en"><title>Notifier
+framework</title><shortdesc>This document describes the notifier framework.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-CED154FC-CFBE-5E07-843B-D409660C5816"><title>The framework</title> <p>The
+text window server notifier framework is a system that loads plug-in DLLs
+from <filepath>\sys\bin\tnotifiers</filepath>. </p> <p>It is used only in
+test ROMs and is never used in production code. For production code, use the
+Extended Notifier Framework. The architecture of both frameworks is identical;
+however, the interface classes have different names. </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-E2C0E005-4138-3C2A-839C-ADB9C935F64B.dita"><apiname>MNotifierBase</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-E2C0E005-4138-3C2A-839C-ADB9C935F64B.dita"><apiname>MNotifierBase</apiname></xref> derived
+class also needs to be implemented correctly. Text window server notifiers
+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>.
+Note that if a notifier panics it will lead to a device reset. </p> </section>
+<section id="GUID-DA49D735-4C8E-5EFD-A170-5E5A23D30884"><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-389A6F11-4700-5423-B7CA-B8F5F0E4391D" xml:space="preserve">EXPORT_C CArrayPtr&lt;MNotifierBase&gt;* NotifierArray()
+    {
+    CArrayPtrFlat&lt;MNotifierBase&gt;* notifiers=new CArrayPtrFlat&lt;MNotifierBase&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> <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-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
+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-3CC86675-ECC5-59E4-8CD3-86AD0BAE0B90" xml:space="preserve">LOCAL_C void CreateNotifiersL(CArrayPtrFlat&lt;MNotifierBase&gt;* aNotifiers)
+    {
+    MNotifierBase* 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> <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>
\ No newline at end of file