|
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-508DD478-1876-5DE2-9271-BDD99F51F579" xml:lang="en"><title>How |
|
13 to use a change notifier</title><shortdesc>Provides code snippets to show you how to use a change notifier.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>To use a change notifier, a thread:</p> |
|
15 <ul> |
|
16 <li id="GUID-1058B3E0-3185-55E1-B4FD-4C6EA533107D"><p>constructs an <codeph>RChangeNotifier</codeph> handle |
|
17 and then calls its <codeph>Create()</codeph> member function to create the |
|
18 associated Kernel side object. The <codeph>RChangeNotifier</codeph> handle |
|
19 is <keyword>thread-relative</keyword> which means that the handle is closed |
|
20 if the thread dies. </p> </li> |
|
21 <li id="GUID-9BB3408F-F792-5310-8459-50E0DB375B6C"><p>issues a request to |
|
22 be notified when the next change occurs, passing a <codeph>TRequestStatus</codeph> object. |
|
23 This is a call to the <codeph>Logon()</codeph> function.</p> </li> |
|
24 </ul> |
|
25 <p>When a change occurs, the change information is made available to the thread |
|
26 through the <codeph>TRequestStatus</codeph> object and the thread's <keyword>request |
|
27 semaphore</keyword> is signalled to indicate that the request is complete.</p> |
|
28 <p>The following code fragments demonstrates this:</p> |
|
29 <codeblock id="GUID-07277DED-7C9A-5620-BA3D-0DE5D2C64969" xml:space="preserve">{ |
|
30 ... |
|
31 RChangeNotifier the_notifier; |
|
32 TRequestStatus the_status; |
|
33 ... |
|
34 the_notifier.Create(); |
|
35 the_notifier.Logon(the_status); |
|
36 User::WaitForRequest(the_status); |
|
37 ... |
|
38 ...// prepare for a long wait |
|
39 ... |
|
40 TInt changes = the_status.Int(); |
|
41 if (changes & EChangesSystemTime) |
|
42 { |
|
43 // handle a change to system time |
|
44 } |
|
45 if (changes & EChanges EChangesLocale) |
|
46 { |
|
47 // handle a change to locale |
|
48 } |
|
49 ... |
|
50 the_notifier.Close(); |
|
51 ... |
|
52 }</codeblock> |
|
53 <p>In practical code, an <codeph>RChangeNotifier</codeph> would be part of |
|
54 an active object.</p> |
|
55 <p>The <codeph>RChangeNotifier</codeph> handle also offers the <codeph>LogonCancel()</codeph> function. |
|
56 Calling this function, causes the thread's <keyword>request semaphore</keyword> to |
|
57 be signalled and any wait to complete. The <codeph>TRequestStatus</codeph> is |
|
58 set to <codeph>KErrCancel</codeph>.</p> |
|
59 <p>The above technique for checking changes is used because, at the completion |
|
60 of a notification request, any, or all, changes may be reported. Code should |
|
61 make no assumptions about the other bits in the returned value. In other words, |
|
62 code should be prepared for a notification request to complete without an |
|
63 'interesting' change.</p> |
|
64 <p>Users should also note that the <i>first</i> notification request <i>after</i> creation |
|
65 of an <codeph>RChangeNotifier</codeph>, completes <i>immediately</i>; the |
|
66 changes reported are <i>all</i> those defined by the <codeph>TChanges</codeph> enum.</p> |
|
67 <p>Also note that after a notification request completes, other changes may |
|
68 occur before the user of the <codeph>RChangeNotifier</codeph> can issue the |
|
69 next notification request. If this occurs, any change events are collected |
|
70 by the change notifier; they are not lost; in this situation, the next notification |
|
71 request completes immediately.</p> |
|
72 </conbody></concept> |