<?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-27CB7E85-8E6F-456B-8B90-55A605A0085E" xml:lang="en"><title>Setting

universal time and offset</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Internally, the kernel uses UTC (Coordinated Universal Time) and stores

an offset for the difference between UTC and local time which is made up of

both the time zone and any daylight saving time added. This removes the responsibility

for handling time zones and daylight saving from the kernel to a user side

"timezone" server. A positive offset indicates a time ahead of UTC: a negative

offset indicates a time behind UTC.</p>

<p>The API below is used to set and get the UTC offset values. </p>

<ul>

<li><p><xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-145F52E6-2A29-3FF1-8AD1-7009BE0074D7"><apiname>User::SetUTCTime()</apiname></xref></p></li>

<li><p><xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-68D881BA-E4BA-3795-90E0-236E07112325"><apiname>User::SetUTCOffset()</apiname></xref></p></li>

<li><p><xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-D1A4CF1D-1F4F-3745-BD3D-671925D16CD3"><apiname>User::SetUTCTimeAndOffset()</apiname></xref></p></li>

<li><p><xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-3CC64469-C1E1-330F-9B4D-B8F95957904F"><apiname>User::UTCOffset()</apiname></xref></p></li>

</ul>

<note><p>Setting the UTC time and offset requires the <codeph>WriteDeviceData</codeph> security

capability.</p></note>

<section id="GUID-D4CD566E-3DF6-4F40-8821-304F45C75C54"><title>Customizing

the default time zone setting</title>       <p>The local time zone is calculated

using an offset from UTC. <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-68D881BA-E4BA-3795-90E0-236E07112325"><apiname>User::SetUTCOffset()</apiname></xref> is used

to set the offset to the required value. This function is called by three

different components at boot up:  </p><ul>

<li><p><xref href="GUID-27CB7E85-8E6F-456B-8B90-55A605A0085E.dita#GUID-27CB7E85-8E6F-456B-8B90-55A605A0085E/GUID-C028BE6B-AE48-40AC-8D5F-BF1DED206450">EStart</xref> -

sets the offset at the start of the boot process and then provides the correct

time for parts of the system that are initialized before the TimeZone and

Locale services are running. </p></li>

<li><p><xref href="GUID-27CB7E85-8E6F-456B-8B90-55A605A0085E.dita#GUID-27CB7E85-8E6F-456B-8B90-55A605A0085E/GUID-EB566340-35CD-445B-8F93-960BB4D35769">InitialiseLocale</xref> -

sets and gets the locale information stored within the repository. This is

necessary if the TimeZoneServer is not included. </p></li>

<li><p><xref href="GUID-27CB7E85-8E6F-456B-8B90-55A605A0085E.dita#GUID-27CB7E85-8E6F-456B-8B90-55A605A0085E/GUID-6F418656-2D12-4090-90A3-C2DF3D749601">TimeZoneServer</xref> -

is an optional service that device manufactures can choose to include. It

is recommended that the offset is set both here and within InitialiseLocale.

 </p></li>

</ul></section>

<section id="GUID-C028BE6B-AE48-40AC-8D5F-BF1DED206450"><title>EStart</title><p>The

call in EStart is required for backwards compatibility with systems that do

not use the TimeZoneServer. The call in EStart also allows many parts of the

system to see the correct time before the timezone/locale services are up

and running. If the timezone offset is not set during startup then many components

may, for that period, see the wrong time.  </p><p> The data format for the

persisted locale data makes no allowance for daylight savings that are not

equal to one hour, but in new code the daylight savings flag is never used

(specifically because of this issue) and the offset is adjusted by the correct

amount instead.  </p><p> To alter the default time zone operation within <b>EStart</b>,

provide your own implementation of the EStart virtual function <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita#GUID-7A6C0343-7B98-3429-9162-4C0357594230/GUID-165D453E-8B09-3B22-96BC-076E01DB8F26"><apiname>TFSStartup::LoadLocale()</apiname></xref>.

See <xref href="GUID-BFE1422D-3B4A-5B25-A757-B5B68D6390F8.dita">EStart: customizing

code</xref>.   </p><p>The offset set through EStart is retrieved through <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-3CC64469-C1E1-330F-9B4D-B8F95957904F"><apiname>User::UTCOffset()</apiname></xref>.

 </p></section>

<section id="GUID-EB566340-35CD-445B-8F93-960BB4D35769"><title>InitialiseLocale</title><p>InitialiseLocale

initializes and persists changes to the system locale settings. The system

locale data is persisted using the central repository. The executable <codeph>initialiseLocale.exe</codeph> loads

the system locale data at device boot and ensures that changes to the system

locale data are persisted.   </p><p>Once <codeph>initialiseLocale.exe</codeph> has

been loaded (as part of the system boot sequence) the contents of the system

locale data are initialized and any subsequent changes to the system locale

settings are persisted without any intervention from the application or component

making the changes.  </p><p/><p><b>Changing System Locale Settings</b></p><p>Create

an empty <codeph>TExtendedLocale</codeph> object and use <codeph>LoadSystemSettings()</codeph> to

get the settings from the repository, make changes and save them with <codeph>SaveSystemSettings()</codeph>.

This function generates a notification for system locale changes so changes

to the locale information may not be immediate.  </p><p> For example, an application

that wishes to change the system time and date settings (without changing

any other locale settings) goes through the following steps: </p><ol>

<li id="GUID-049A63A9-D3AB-4E88-AB94-EEBD61B15027"><p>Create an empty instance

of <codeph>TExtendedLocale</codeph>.</p><codeblock xml:space="preserve">TExtendedLocale myExtendedLocale;

</codeblock></li>

<li id="GUID-362D9D13-2DAA-4A80-9EA1-ABE9E0EE8152"><p>Initialize it to the

current system settings.</p><codeblock xml:space="preserve">myExtendedLocale.LoadSystemSettings();

</codeblock></li>

<li id="GUID-FC7F35DA-2A46-4AF2-A580-D9EF292A031B"><p>Change the time and

date settings locally.</p><codeblock xml:space="preserve">myExtendedLocale.LoadLocaleAspect( ELocaleTimeDateSettings, KLocaleDllTimeDateSettings );

</codeblock></li>

<li id="GUID-B6C19192-C396-4A3E-A534-141AE5D8426B"><p>Write the new settings

to the system locale data.</p><codeblock xml:space="preserve">myExtendedLocale.SaveSystemSettings();</codeblock></li>

</ol><p>The <b>security capability</b> <codeph>WriteDeviceData</codeph> is

required to save settings.</p></section>

<section id="GUID-6F418656-2D12-4090-90A3-C2DF3D749601"><title>TimeZoneServer</title><p>The

time zone server simplifies the synchronisation between handsets in different

time zones. For example, if one handset is in the UK and another in the US

a meeting can be scheduled at the same time (UTC) and the local time is calculated

for each by the time zone server.  </p><p> The Time Zone Server converts UTC

to local time based on different time zones and DST rules, and publishes any

change to subscribing clients, for example the Calendar application. See <xref href="GUID-A81C65CF-CF4E-571C-8080-9D387F46AAD6.dita">Publish and Subscribe</xref>.</p><p>The

time zone server is an optional service that licensees can choose to include

otherwise another method can be used to supply the UTC offset, for example,

Network time update, see <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita#GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8/GUID-1676D1E4-AD15-3265-B1A8-1C7B9B56FB66"><apiname>RMobilePhone::GetNITZInfo()</apiname></xref>. Because

the time zone server may not be included in the product it is necessary to

persist the UTC offset as part of the locale data (<codeph>TLocale</codeph>).

The time zone server persists the current time zone and updates the UTC offset

based on whether daylight savings applies or not.  </p><p> The following code

example should help to illustrate the interactions that may occur if <xref href="GUID-1BD54E95-218F-3B43-B427-F9EA6DA9AB69.dita"><apiname>User:SetUTCOffset()</apiname></xref> or <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-D1A4CF1D-1F4F-3745-BD3D-671925D16CD3"><apiname>User::SetUTCTimeAndOffset()</apiname></xref> are called while the time zone server is running.  </p><p>Preconditions

for this code are:</p><ul>

<li><p>The time zone server is not already running. </p></li>

<li><p>It is assumed that the current UTC offset is not 36000 seconds (10

hours). For describing this example, we will take the UTC to be 18000 seconds

(5 hours). </p></li>

</ul><codeblock xml:space="preserve">void MainL()

    {

    RTz tz;

    TTimeIntervalSeconds offsetWhenTzRunningInitial;

    TTimeIntervalSeconds offsetWhenTzRunningAfterSetting;

    TTimeIntervalSeconds offsetWhenTzNotRunningInitial;

    TTimeIntervalSeconds offsetWhenTzNotRunningAfterSetting;

    TInt err = tz.Connect();

    User::LeaveIfError( err );

    offsetWhenTzRunningInitial = User::UTCOffset(); 

    User::SetUTCOffset( 36000 );

    User::After( 1*1000*1000 );

    offsetWhenTzRunningAfterSetting = User::UTCOffset(); 

    tz.Close();

    offsetWhenTzNotRunningInitial = User::UTCOffset(); 

    User::SetUTCOffset( 36000 );

    offsetWhenTzNotRunningAfterSetting = User::UTCOffset(); 

    }</codeblock><p>Given the preconditions listed, the values for the offsets

retrieved are:</p><ol>

<li id="GUID-9D41985D-620F-4954-897B-B2F2558304D1"><p><codeph>offsetWhenTzRunningInitial</codeph> 18000

(seconds). </p></li>

<li id="GUID-89867FF7-27ED-4B48-9CCE-0A011F14DF43"><p><codeph>offsetWhenTzRunningAfterSetting</codeph> 18000

(seconds). </p></li>

<li id="GUID-2A04B812-C409-4376-8964-856C75647D44"><p><codeph>offsetWhenTzNotRunningInitial</codeph> 18000

(seconds).</p></li>

<li id="GUID-5498BB66-8437-4A0A-A2D5-BE6E776A6810"><p><codeph>offsetWhenTzNotRunningAfterSetting</codeph> 36000

(seconds).</p></li>

</ol><p>The value of <codeph>offsetWhenTzRunningAfterSetting</codeph> is not

36000 as one might expect from just looking at the code. This is because the

time zone server observes the kernel setting of the UTC offset and when this

value is changed, it checks the current time zone and ensures that the offset

matches this value. The delay is placed in this example code to ensure that

the time zone server is given a chance to run and to change the value. </p><p>If

a call to <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-3CC64469-C1E1-330F-9B4D-B8F95957904F"><apiname>User::UTCOffset()</apiname></xref> were made before the call to <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-4FDD3CEB-9D30-33BD-BAF3-14A1E2D56B18"><apiname>User::After()</apiname></xref>,

then the value can be either 36000 or 18000 depending on the CPU load, presence

of other processes and their relative priorities. </p></section>

</conbody></concept>