|
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-27CB7E85-8E6F-456B-8B90-55A605A0085E" xml:lang="en"><title>Setting |
|
13 universal time and offset</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Internally, the kernel uses UTC (Coordinated Universal Time) and stores |
|
15 an offset for the difference between UTC and local time which is made up of |
|
16 both the time zone and any daylight saving time added. This removes the responsibility |
|
17 for handling time zones and daylight saving from the kernel to a user side |
|
18 "timezone" server. A positive offset indicates a time ahead of UTC: a negative |
|
19 offset indicates a time behind UTC.</p> |
|
20 <p>The API below is used to set and get the UTC offset values. </p> |
|
21 <ul> |
|
22 <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> |
|
23 <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> |
|
24 <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> |
|
25 <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> |
|
26 </ul> |
|
27 <note><p>Setting the UTC time and offset requires the <codeph>WriteDeviceData</codeph> security |
|
28 capability.</p></note> |
|
29 <section id="GUID-D4CD566E-3DF6-4F40-8821-304F45C75C54"><title>Customizing |
|
30 the default time zone setting</title> <p>The local time zone is calculated |
|
31 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 |
|
32 to set the offset to the required value. This function is called by three |
|
33 different components at boot up: </p><ul> |
|
34 <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> - |
|
35 sets the offset at the start of the boot process and then provides the correct |
|
36 time for parts of the system that are initialized before the TimeZone and |
|
37 Locale services are running. </p></li> |
|
38 <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> - |
|
39 sets and gets the locale information stored within the repository. This is |
|
40 necessary if the TimeZoneServer is not included. </p></li> |
|
41 <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> - |
|
42 is an optional service that device manufactures can choose to include. It |
|
43 is recommended that the offset is set both here and within InitialiseLocale. |
|
44 </p></li> |
|
45 </ul></section> |
|
46 <section id="GUID-C028BE6B-AE48-40AC-8D5F-BF1DED206450"><title>EStart</title><p>The |
|
47 call in EStart is required for backwards compatibility with systems that do |
|
48 not use the TimeZoneServer. The call in EStart also allows many parts of the |
|
49 system to see the correct time before the timezone/locale services are up |
|
50 and running. If the timezone offset is not set during startup then many components |
|
51 may, for that period, see the wrong time. </p><p> The data format for the |
|
52 persisted locale data makes no allowance for daylight savings that are not |
|
53 equal to one hour, but in new code the daylight savings flag is never used |
|
54 (specifically because of this issue) and the offset is adjusted by the correct |
|
55 amount instead. </p><p> To alter the default time zone operation within <b>EStart</b>, |
|
56 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>. |
|
57 See <xref href="GUID-BFE1422D-3B4A-5B25-A757-B5B68D6390F8.dita">EStart: customizing |
|
58 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>. |
|
59 </p></section> |
|
60 <section id="GUID-EB566340-35CD-445B-8F93-960BB4D35769"><title>InitialiseLocale</title><p>InitialiseLocale |
|
61 initializes and persists changes to the system locale settings. The system |
|
62 locale data is persisted using the central repository. The executable <codeph>initialiseLocale.exe</codeph> loads |
|
63 the system locale data at device boot and ensures that changes to the system |
|
64 locale data are persisted. </p><p>Once <codeph>initialiseLocale.exe</codeph> has |
|
65 been loaded (as part of the system boot sequence) the contents of the system |
|
66 locale data are initialized and any subsequent changes to the system locale |
|
67 settings are persisted without any intervention from the application or component |
|
68 making the changes. </p><p/><p><b>Changing System Locale Settings</b></p><p>Create |
|
69 an empty <codeph>TExtendedLocale</codeph> object and use <codeph>LoadSystemSettings()</codeph> to |
|
70 get the settings from the repository, make changes and save them with <codeph>SaveSystemSettings()</codeph>. |
|
71 This function generates a notification for system locale changes so changes |
|
72 to the locale information may not be immediate. </p><p> For example, an application |
|
73 that wishes to change the system time and date settings (without changing |
|
74 any other locale settings) goes through the following steps: </p><ol> |
|
75 <li id="GUID-049A63A9-D3AB-4E88-AB94-EEBD61B15027"><p>Create an empty instance |
|
76 of <codeph>TExtendedLocale</codeph>.</p><codeblock xml:space="preserve">TExtendedLocale myExtendedLocale; |
|
77 </codeblock></li> |
|
78 <li id="GUID-362D9D13-2DAA-4A80-9EA1-ABE9E0EE8152"><p>Initialize it to the |
|
79 current system settings.</p><codeblock xml:space="preserve">myExtendedLocale.LoadSystemSettings(); |
|
80 </codeblock></li> |
|
81 <li id="GUID-FC7F35DA-2A46-4AF2-A580-D9EF292A031B"><p>Change the time and |
|
82 date settings locally.</p><codeblock xml:space="preserve">myExtendedLocale.LoadLocaleAspect( ELocaleTimeDateSettings, KLocaleDllTimeDateSettings ); |
|
83 </codeblock></li> |
|
84 <li id="GUID-B6C19192-C396-4A3E-A534-141AE5D8426B"><p>Write the new settings |
|
85 to the system locale data.</p><codeblock xml:space="preserve">myExtendedLocale.SaveSystemSettings();</codeblock></li> |
|
86 </ol><p>The <b>security capability</b> <codeph>WriteDeviceData</codeph> is |
|
87 required to save settings.</p></section> |
|
88 <section id="GUID-6F418656-2D12-4090-90A3-C2DF3D749601"><title>TimeZoneServer</title><p>The |
|
89 time zone server simplifies the synchronisation between handsets in different |
|
90 time zones. For example, if one handset is in the UK and another in the US |
|
91 a meeting can be scheduled at the same time (UTC) and the local time is calculated |
|
92 for each by the time zone server. </p><p> The Time Zone Server converts UTC |
|
93 to local time based on different time zones and DST rules, and publishes any |
|
94 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 |
|
95 time zone server is an optional service that licensees can choose to include |
|
96 otherwise another method can be used to supply the UTC offset, for example, |
|
97 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 |
|
98 the time zone server may not be included in the product it is necessary to |
|
99 persist the UTC offset as part of the locale data (<codeph>TLocale</codeph>). |
|
100 The time zone server persists the current time zone and updates the UTC offset |
|
101 based on whether daylight savings applies or not. </p><p> The following code |
|
102 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 |
|
103 for this code are:</p><ul> |
|
104 <li><p>The time zone server is not already running. </p></li> |
|
105 <li><p>It is assumed that the current UTC offset is not 36000 seconds (10 |
|
106 hours). For describing this example, we will take the UTC to be 18000 seconds |
|
107 (5 hours). </p></li> |
|
108 </ul><codeblock xml:space="preserve">void MainL() |
|
109 { |
|
110 RTz tz; |
|
111 TTimeIntervalSeconds offsetWhenTzRunningInitial; |
|
112 TTimeIntervalSeconds offsetWhenTzRunningAfterSetting; |
|
113 TTimeIntervalSeconds offsetWhenTzNotRunningInitial; |
|
114 TTimeIntervalSeconds offsetWhenTzNotRunningAfterSetting; |
|
115 |
|
116 TInt err = tz.Connect(); |
|
117 User::LeaveIfError( err ); |
|
118 offsetWhenTzRunningInitial = User::UTCOffset(); |
|
119 User::SetUTCOffset( 36000 ); |
|
120 User::After( 1*1000*1000 ); |
|
121 offsetWhenTzRunningAfterSetting = User::UTCOffset(); |
|
122 tz.Close(); |
|
123 |
|
124 offsetWhenTzNotRunningInitial = User::UTCOffset(); |
|
125 User::SetUTCOffset( 36000 ); |
|
126 offsetWhenTzNotRunningAfterSetting = User::UTCOffset(); |
|
127 }</codeblock><p>Given the preconditions listed, the values for the offsets |
|
128 retrieved are:</p><ol> |
|
129 <li id="GUID-9D41985D-620F-4954-897B-B2F2558304D1"><p><codeph>offsetWhenTzRunningInitial</codeph> 18000 |
|
130 (seconds). </p></li> |
|
131 <li id="GUID-89867FF7-27ED-4B48-9CCE-0A011F14DF43"><p><codeph>offsetWhenTzRunningAfterSetting</codeph> 18000 |
|
132 (seconds). </p></li> |
|
133 <li id="GUID-2A04B812-C409-4376-8964-856C75647D44"><p><codeph>offsetWhenTzNotRunningInitial</codeph> 18000 |
|
134 (seconds).</p></li> |
|
135 <li id="GUID-5498BB66-8437-4A0A-A2D5-BE6E776A6810"><p><codeph>offsetWhenTzNotRunningAfterSetting</codeph> 36000 |
|
136 (seconds).</p></li> |
|
137 </ol><p>The value of <codeph>offsetWhenTzRunningAfterSetting</codeph> is not |
|
138 36000 as one might expect from just looking at the code. This is because the |
|
139 time zone server observes the kernel setting of the UTC offset and when this |
|
140 value is changed, it checks the current time zone and ensures that the offset |
|
141 matches this value. The delay is placed in this example code to ensure that |
|
142 the time zone server is given a chance to run and to change the value. </p><p>If |
|
143 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>, |
|
144 then the value can be either 36000 or 18000 depending on the CPU load, presence |
|
145 of other processes and their relative priorities. </p></section> |
|
146 </conbody></concept> |