|
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" 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"><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, for example |
|
21 UIQ and Series60, through what are known as notifier plug-ins. </p> <p>The |
|
22 extended notifier 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 (e.g. a screen |
|
30 or LED). This means that two notifiers can be active at the same time provided |
|
31 that they are on different channels. </p> <p>The channel and priority used |
|
32 by all the notifiers in the system needs to be considered carefully to avoid |
|
33 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"><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" xml:space="preserve">EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray() |
|
40 { |
|
41 CArrayPtrFlat<MEikSrvNotifierBase2>* notifiers=new CArrayPtrFlat<MEikSrvNotifierBase2>(5); |
|
42 if (notifiers) |
|
43 { |
|
44 TRAPD(err, CreateNotifiersL(notifiers)); |
|
45 if(err) |
|
46 { |
|
47 TInt count = notifiers->Count(); |
|
48 while(count--) |
|
49 { |
|
50 (*notifiers)[count]->Release(); |
|
51 } |
|
52 delete notifiers; |
|
53 notifiers = NULL; |
|
54 } |
|
55 } |
|
56 return(notifiers); |
|
57 } |
|
58 </codeblock> <p>Note that ownership of the notifier array or its contents |
|
59 is not transferred to the framework until this function returns. To avoid |
|
60 memory leaks, all acquired resources must be freed if anything goes wrong |
|
61 part of the way through its processing. </p> <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" xml:space="preserve">LOCAL_C void CreateNotifiersL(CArrayPtrFlat<MEikSrvNotifierBase2>* aNotifiers) |
|
67 { |
|
68 MEikSrvNotifierBase2* notifier; |
|
69 notifier = CMyNotifierA::NewL(); |
|
70 CleanupStack::PushL(notifier); |
|
71 aNotifiers->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> <p>Note the 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->AppendL(CMyNotifierA::NewL());</codeph>, |
|
82 which, although shorter, will result in a memory leak if the <codeph>AppendL()</codeph> operation |
|
83 fails. </p> </section> |
|
84 </conbody></concept> |