--- a/Symbian3/PDK/Source/GUID-E634E701-0DA2-572E-852B-8A1F88F05E5A.dita Tue Jul 20 12:00:49 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-E634E701-0DA2-572E-852B-8A1F88F05E5A.dita Fri Aug 13 16:47:46 2010 +0100
@@ -1,81 +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<MNotifierBase>* NotifierArray()
- {
- CArrayPtrFlat<MNotifierBase>* notifiers=new CArrayPtrFlat<MNotifierBase>(5);
- if (notifiers)
- {
- TRAPD(err, CreateNotifiersL(notifiers));
- if(err)
- {
- TInt count = notifiers->Count();
- while(count--)
- {
- (*notifiers)[count]->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<MNotifierBase>* aNotifiers)
- {
- MNotifierBase* notifier;
- notifier = CMyNotifierA::NewL();
- CleanupStack::PushL(notifier);
- aNotifiers->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->AppendL(CMyNotifierA::NewL());</codeph>,
-which, although shorter, will result in a memory leak if the <codeph>AppendL()</codeph> operation
-fails. </p> </section>
+<?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<MNotifierBase>* NotifierArray()
+ {
+ CArrayPtrFlat<MNotifierBase>* notifiers=new CArrayPtrFlat<MNotifierBase>(5);
+ if (notifiers)
+ {
+ TRAPD(err, CreateNotifiersL(notifiers));
+ if(err)
+ {
+ TInt count = notifiers->Count();
+ while(count--)
+ {
+ (*notifiers)[count]->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<MNotifierBase>* aNotifiers)
+ {
+ MNotifierBase* notifier;
+ notifier = CMyNotifierA::NewL();
+ CleanupStack::PushL(notifier);
+ aNotifiers->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->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