<?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 xml:lang="en" id="GUID-7C6D3479-2159-5A9B-9970-0B3E625442A6"><title>Using Environment Change Notifier</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Environment Change Notifier is provided so that an application can be notified of changes in the environment such as a switch in locale, crossing over past midnight and so on. </p> <p>The <codeph>TChanges</codeph> enumerator lists the possible events. This set of events may be extended as the operating system evolves. </p> <section><title>Introduction</title> <p>An environment change notifier is an instance of a <codeph>CEnvironmentChangeNotifier</codeph> class. This is an active object which allows an application to respond to change events easily. These change events are generated by a kernel side change notifier service. The <codeph>CEnvironmentChangeNotifier</codeph> class uses the kernel side change notifier service through an <codeph>RChangeNotifier</codeph> handle. </p> <p>An application supplies a callback function to <codeph>CEnvironmentChangeNotifier</codeph> when it is constructed. </p> <p>When an outstanding request for change events completes, <codeph>CEnvironmentChangeNotifier</codeph> issues another request for change events before calling the callback function (encapsulated in a <xref href="GUID-6C5766BC-05DE-32A8-993D-6BB582931F43.dita"><apiname>TCallBack</apiname></xref>). </p> <p>The implementation of the callback function depends on the application but, typically, it would flag the required changes and schedule other changes either to the application's engine or the application's user interface. </p> <p>Programs can use Environment Change Notifier to request for notifications for the following changes: </p> <ul><li id="GUID-616002CB-557F-5BCB-850A-811856CBDDE9"><p>change of system locale </p> </li> <li id="GUID-6B8DDABD-3B12-5997-BA5F-D24A26ACFFF4"><p>system time passes midnight </p> </li> <li id="GUID-252E53D1-CDD4-5CA3-9F38-79E7495D9BEA"><p>system time changes </p> </li> <li id="GUID-DB191A3A-3D2F-57A3-B1BC-320CB6F58F17"><p>any thread dies </p> </li> <li id="GUID-7BE23762-BB35-5D37-A561-B248787F2071"><p>status of the power supply changes </p> </li> </ul> </section> <section><title>Procedure</title> <p>To use the Environment Change Notifier, an application must perform the following: </p> <ol id="GUID-A6041480-76EA-59AE-A187-65175B244E65"><li id="GUID-6985BDF3-997C-57FF-832E-32731948C240"><p>Implement a callback function to handle the environment change. </p> <codeblock id="GUID-B9BD69A0-B37F-590D-BEF4-88F056C617EC" xml:space="preserve"> 

TInt CExHandleNotification::ChangeLangSettings()

    {

     //Code for changing the language settings.

    }

</codeblock> </li> <li id="GUID-498A463D-4CD3-5CEC-85E6-A7087E517BE9"><p>Construct a <codeph>CEnvironmentChangeNotifier</codeph> object using its <codeph>NewL()</codeph> function, specifying the active object priority and a pointer to the callback function encapsulated in a <codeph>TCallBack</codeph> object. </p> <p> <codeph>NewL()</codeph> also adds this <codeph>CEnvironmentChangeNotifier</codeph> active object to the current <keyword>active scheduler</keyword>. </p> <codeblock id="GUID-28216515-8F66-5A61-A12D-8E98BCC9E391" xml:space="preserve">

CExHandleNotification::Initialise()

                {

    //Creating a notifier object with ChangeLangSettings as the callback function.

                CEnvironmentChangeNotifier envNotifier = CEnvironmentChangeNotifier::NewL( EActivePriorityDefault,TCallBack(CExHandleNotification::ChangeLangSettings, this) );

                }</codeblock> </li> <li id="GUID-3E7AA7CA-F7A0-5D63-83A2-6A9DFEF7958A"><p>Issue a request for change events by calling the <codeph>Start()</codeph> member function. </p> </li> </ol> <p>Whenever a request completes, <codeph>CEnvironmentChangeNotifier</codeph> issues another request for change events before the callback function is invoked. </p> <p>The first call to the callback function occurs immediately after the first call to <codeph>Start()</codeph>. This is because of the way the underlying change notifier service is implemented; the changes reported are those defined by the <codeph>TChanges</codeph> enum. </p> <p>To stop the environment change notifier, an application must: </p> <ol id="GUID-3859F4AA-A656-5486-91C6-BE8F29FF9C0B"><li id="GUID-4B8C6E17-B904-5A8D-BB1C-3794664BB6B3"><p>Call <codeph>CEnvironmentChangeNotifier</codeph>'s <codeph>Cancel()</codeph> function. Note that this is a member of the <codeph>CActive</codeph> base class. </p> </li> <li id="GUID-11F57FDC-E773-551C-A0A9-79AAE8AC61BD"><p>Delete the <codeph>CEnvironmentChangeNotifier</codeph> object. </p> </li> </ol> </section> </conbody></concept>