<?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-508DD478-1876-5DE2-9271-BDD99F51F579" xml:lang="en"><title>How

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>

<p>To use a change notifier, a thread:</p>

<ul>

<li id="GUID-1058B3E0-3185-55E1-B4FD-4C6EA533107D"><p>constructs an <codeph>RChangeNotifier</codeph> handle

and then calls its <codeph>Create()</codeph> member function to create the

associated Kernel side object. The <codeph>RChangeNotifier</codeph> handle

is <keyword>thread-relative</keyword> which means that the handle is closed

if the thread dies. </p> </li>

<li id="GUID-9BB3408F-F792-5310-8459-50E0DB375B6C"><p>issues a request to

be notified when the next change occurs, passing a <codeph>TRequestStatus</codeph> object.

This is a call to the <codeph>Logon()</codeph> function.</p> </li>

</ul>

<p>When a change occurs, the change information is made available to the thread

through the <codeph>TRequestStatus</codeph> object and the thread's <keyword>request

semaphore</keyword> is signalled to indicate that the request is complete.</p>

<p>The following code fragments demonstrates this:</p>

<codeblock id="GUID-07277DED-7C9A-5620-BA3D-0DE5D2C64969" xml:space="preserve">{

...

RChangeNotifier the_notifier;

TRequestStatus  the_status;

...

the_notifier.Create();

the_notifier.Logon(the_status);

User::WaitForRequest(the_status);

...

...// prepare for a long wait

...

TInt changes = the_status.Int();

if (changes & EChangesSystemTime)

    {

    // handle a change to system time

    }

if (changes & EChanges EChangesLocale)

    {

    // handle a change to locale

    }

...

the_notifier.Close();

...

}</codeblock>

<p>In practical code, an <codeph>RChangeNotifier</codeph> would be part of

an active object.</p>

<p>The <codeph>RChangeNotifier</codeph> handle also offers the <codeph>LogonCancel()</codeph> function.

Calling this function, causes the thread's <keyword>request semaphore</keyword> to

be signalled and any wait to complete. The <codeph>TRequestStatus</codeph> is

set to <codeph>KErrCancel</codeph>.</p>

<p>The above technique for checking changes is used because, at the completion

of a notification request, any, or all, changes may be reported. Code should

make no assumptions about the other bits in the returned value. In other words,

code should be prepared for a notification request to complete without an

'interesting' change.</p>

<p>Users should also note that the <i>first</i> notification request <i>after</i> creation

of an <codeph>RChangeNotifier</codeph>, completes <i>immediately</i>; the

changes reported are <i>all</i> those defined by the <codeph>TChanges</codeph> enum.</p>

<p>Also note that after a notification request completes, other changes may

occur before the user of the <codeph>RChangeNotifier</codeph> can issue the

next notification request. If this occurs, any change events are collected

by the change notifier; they are not lost; in this situation, the next notification

request completes immediately.</p>

</conbody></concept>