class RTz : public RSessionBase |
The client interface to the time zone server.
This class performs two basic functions:
1. Converts between UTC time and local time. 2. Sets the current local time zone.
NOTE: The presence of a time zone server will alter the behaviour of the time zone related function calls User::SetUTCOffset() and User::SetUTCTimeAndOffset(). The time zone server is shutdown when the last session (RTz) is closed. Therefore, to maintain consistent time related behaviour, licensees may want to keep a system level time zone server session open at all times.
Exceptional cases occur when a user requests conversion for a non-existent local time or a double local time.
Non-existent local times occur when the local time changes from winter to summer for DST.
For example, 01:59 local time is non-existent on the day of a change to BST in Europe/London since the time changes directly from 12:59:59 to 2:00.
A double local time occurs when the local time changes from summer to winter.
For example, if the time changes at 02:00 AM BST to 01:00 AM GMT then local times between 01:00 and 01:59 occur twice.
The conversion applies the DST offset if the local time value is double and applies the standard UTC offset if the local time does not exists.
This decision makes the conversion process asymmetrical around the discontinuity in the local time when there is a DST change.
An example conversion from a double local time to UTC and from UTC to a double local time is:
01:59 AM BST => 00:59 AM UTC 01:59 AM UTC => 01:59 AM GMT
An example conversion from a non-existent local time to UTC and from UTC to local time is:
01:59 AM GMT => 01:59 AM UTC 01:59 AM UTC => 02:59 AM BST
Private Member Functions | |
---|---|
TInt | DoConnect() |
TInt | StartServer() |
void | doConvertL(const CTzId &, TTime &, TTzTimeReference) |
void | doConvertL(TTime &, TTzTimeReference) |
Inherited Enumerations | |
---|---|
RHandleBase:TAttributes | |
RSessionBase:TAttachMode |
Private Attributes | |
---|---|
CTzRuleHolder * | iRulesHolder |
Inherited Attributes | |
---|---|
RHandleBase::iHandle |
IMPORT_C TInt | AutoUpdateSettingL | ( | ) |
Retrieves the daylight saving auto-update functionality.
IMPORT_C TInt | Connect | ( | ) |
IMPORT_C TInt | ConvertToLocalTime | ( | TTime & | aTime | ) | const |
Converts a time from UTC to local (wall-clock) time for the current system time zone. If caching has been enabled by the CTzConverter class, then the conversion will be done using the cache instead of issuing a request to the server.
TTime & aTime | On entry, contains the UTC time to be converted, and the converted value on exit. |
IMPORT_C TInt | ConvertToLocalTime | ( | TTime & | aTime, |
const CTzId & | aZone | |||
) | const |
Converts a time from UTC to the local (wall-clock) time for the specified time zone.
IMPORT_C TInt | ConvertToUniversalTime | ( | TTime & | aTime | ) | const |
Converts a local (wall-clock) time for the current system time zone, to UTC. If caching has been enabled by the CTzConverter class, then the conversion will be done using the cache instead of issuing a request to the server.
TTime & aTime | On entry, contains the local time to be converted, and the converted value on exit. |
IMPORT_C TInt | ConvertToUniversalTime | ( | TTime & | aTime, |
const CTzId & | aZone | |||
) | const |
Converts a local (wall-clock) time for the specified time zone, to UTC.
CTzId * | CreateUserTimeZoneL | ( | const CTzRules & | aTzUserRules, |
const CTzUserNames & | aTzUserNames | |||
) |
const CTzRules & aTzUserRules | |
const CTzUserNames & aTzUserNames |
void | DeleteUserTimeZoneL | ( | const CTzId & | aTzId | ) |
const CTzId & aTzId |
IMPORT_C void | GetOffsetsForTimeZoneIdsL | ( | const RArray< TInt > & | aTzNumericIds, |
RArray< TInt > & | aOffsets | |||
) | const |
Retrieves the UTC offset for an array of numeric time zone ids. The offset is written back into aOffsets.
IMPORT_C CTzId * | GetTimeZoneIdL | ( | ) | const |
This should not be used externally.
IMPORT_C CTzRules * | GetTimeZoneRulesL | ( | const TTime & | aStartTime, |
const TTime & | aEndTime, | |||
TTzTimeReference | aTimeRef | |||
) | const |
Retrieves the time zone rules for the current home time zone.
const TTime & aStartTime | The start date to generate the time zone rules from. |
const TTime & aEndTime | The end date to generate the time zone rules to. |
TTzTimeReference aTimeRef | Whether to generate the rules relative to UTC or local time. Use ETzUtcTimeReference to generate from UTC, ETzWallTimeReference to generate from local time. |
IMPORT_C CTzRules * | GetTimeZoneRulesL | ( | const CTzId & | aZone, |
const TTime & | aStartTime, | |||
const TTime & | aEndTime, | |||
TTzTimeReference | aTimeRef | |||
) | const |
Retrieves the time zone rules for a specified time zone.
const CTzId & aZone | The time zone to generate the rules for. |
const TTime & aStartTime | The start date to generate the time zone rules from. |
const TTime & aEndTime | The end date to generate the time zone rules to. |
TTzTimeReference aTimeRef | Whether to generate the rules relative to UTC or local time. Use ETzUtcTimeReference to generate from UTC, ETzWallTimeReference to generate from local time. |
void | GetUserTimeZoneIdsL | ( | RPointerArray< CTzId > & | aTzIds | ) | const |
RPointerArray< CTzId > & aTzIds |
CTzUserNames * | GetUserTimeZoneNamesL | ( | const CTzId & | aTzId | ) | const |
const CTzId & aTzId |
IMPORT_C TBool | IsDaylightSavingOnL | ( | CTzId & | aZone | ) | const |
Tells if daylight savings are applied at the specified zone at the current time
CTzId & aZone | The time zone ID. |
IMPORT_C TBool | IsDaylightSavingOnL | ( | CTzId & | aZone, |
const TTime & | aUTCTime | |||
) | const |
Tells if daylight savings are applied at the specified zone at a specified time
IMPORT_C void | LocalizationDeleteCityL | ( | const TDesC & | aCityName, |
TInt | aCityTzId | |||
) |
Deletes aCity from the user added cities database table. The city is checked first to ensure it exists. Name checking is case sensitive.
IMPORT_C CTzLocalizedCityRecord * | LocalizationReadCachedTimeZoneCityL | ( | TInt | aFrequentlyUsedZone | ) |
Retrieves the city used to select this time zone if set. If the time zone was not originally set using a city then the default city for the time zone will be returned instead.
TInt aFrequentlyUsedZone | - The cached zone to find the city for |
IMPORT_C void | LocalizationReadCitiesInGroupL | ( | RPointerArray< CTzLocalizedCityRecord > & | aCities, |
TUint8 | aGroupId | |||
) |
Reads all the user defined cities stored in the database with a matching group id. If the database is empty the returned array will contain no elements.
RPointerArray< CTzLocalizedCityRecord > & aCities | Array of cities to add the user defined cities to. |
TUint8 aGroupId | A city group id |
IMPORT_C void | LocalizationReadCitiesL | ( | RPointerArray< CTzLocalizedCityRecord > & | aCities | ) |
Reads all the user defined cities stored in the database. If the database is empty the returned array will contain no elements.
RPointerArray< CTzLocalizedCityRecord > & aCities | Array of cities to add the user defined to. |
IMPORT_C void | LocalizationReadCitiesL | ( | RPointerArray< CTzLocalizedCityRecord > & | aCities, |
TInt | aTimeZoneId | |||
) |
Reads all the user defined cities stored in the database that are members of the time zone referenced by aTimeZoneid. If the database is empty the returned array will contain no elements.
RPointerArray< CTzLocalizedCityRecord > & aCities | Array of cities to add the user defined cities to. |
TInt aTimeZoneId | A time zone id identifying a time zone |
IMPORT_C CTzLocalizedTimeZoneRecord * | LocalizationReadFrequentlyUsedZoneL | ( | TInt | aFrequentlyUsedZone | ) |
Retrieves a cached zone from the database. The calling function takes ownership of the returned zone
TInt aFrequentlyUsedZone | - The cached zone to return |
IMPORT_C void | LocalizationWriteAllFrequentlyUsedZonesL | ( | const RPointerArray< CTzLocalizedTimeZoneRecord > & | aTimeZones, |
const RPointerArray< CTzLocalizedCityRecord > & | aCities | |||
) |
const RPointerArray< CTzLocalizedTimeZoneRecord > & aTimeZones | |
const RPointerArray< CTzLocalizedCityRecord > & aCities |
IMPORT_C void | LocalizationWriteCityL | ( | const TDesC & | aCityName, |
TInt | aCityTzId, | |||
TUint8 | aCityGroupId, | |||
TUint | aCityTzResourceId | |||
) |
Adds aCity into the user added cities database table. The city is checked first to prevent two cities with identical names and time zones existing at the same time. Name checking is case sensitive. Cities in different time zones can have the same name.
IMPORT_C void | LocalizationWriteFrequentlyUsedZoneL | ( | const CTzLocalizedTimeZoneRecord & | aTimeZone, |
const CTzLocalizedCityRecord & | aCity, | |||
TInt | aFrequentlyUsedZone | |||
) |
Stores the localized time zone in the database for easy retrieval. The database keeps track of the two most recently used zones, these are updated every time a new zone is set. The zone to be replaced becomes recently used zone 1, and recently used zone 1 becomes recently used zone 2. The old recently used zone 2 is discarded.
const CTzLocalizedTimeZoneRecord & aTimeZone | Time zone names information to store in the given frequently used time zone. |
const CTzLocalizedCityRecord & aCity | City associated with the time zone names to store in the given frequently used time zone. |
TInt aFrequentlyUsedZone | Which frequently used time zone to overwrite in the database. |
IMPORT_C void | NotifyHomeTimeZoneChangedL | ( | const NTzUpdate::TTimeZoneChange & | aChange | ) | const |
Publish notification that the home time zone (as defined in CTzLocalizer) has been changed. This function should only be called from TimeZoneLocalization.
const NTzUpdate::TTimeZoneChange & aChange | Time zone change information. |
IMPORT_C void | Panic | ( | TPanic | aPanic | ) | [static] |
This should not be used externally.
Panics the TzClient or TzServer code.
TPanic aPanic |
void | RegisterTzChangeNotifier | ( | TRequestStatus & | aStatus | ) | const |
TRequestStatus & aStatus |
IMPORT_C void | SetAutoUpdateBehaviorL | ( | TTzAutoDSTUpdateModes | aUpdateEnabled | ) |
Sets the configuration of the UTC Offset auto-update functionality.
TTzAutoDSTUpdateModes aUpdateEnabled | If set to RTz::ETZAutoDSTUpdateOn then the UTC Offset is automatically updated for changes to Daylight Savings Time. If set to RTz::ETZAutoDSTUpdateOff then auto-update is disabled. The RTz::ETZAutoDSTNotificationOnly - Means that the client app needs to confirm that the time should be updated whenever a DST event occurs. |
IMPORT_C TInt | SetHomeTime | ( | const TTime & | aLocalTime | ) | const |
Sets the system time to the given local time. Note that the standard Tz algorithm is used - in the case of an ambiguous time the first occurance of the given local wall-clock time is chosen.
An example of an ambiguous time: 01:30 wall-clock time on 31/10/2004 in the UK could map to either 01:30 BST (00:30 GMT) or 01:30 GMT, as the clocks would go back at 02:00 BST (01:00 GMT))
const TTime & aLocalTime | The time to set in wall-clock time. |
IMPORT_C void | SetTimeZoneL | ( | CTzId & | aZone | ) | const |
This should not be used externally.
CTzId & aZone | The time zone ID. |
IMPORT_C void | SetUnknownZoneTimeL | ( | const TTime & | aUTCTime, |
const TInt | aUTCOffset | |||
) |
Sets the UTC time and the wall-clock offset for a zone not defined in the Timezone Database.
This is useful when the client wants to specify the UTC time and the wall-clock offset explicitly rather than using time zones. This function should be used instead of User::SetUTCOffset() and User::SetUTCTimeAndOffset().
If this function has been called the time zone server will use the value returned by User::UTCOffset() as the offset value when doing time conversions. Calling User::SetUTCOffset() may therefore cause unexpected results.
The fact that the time zone has been set to the unknown time zone is not persisted across time zone server reboots. So it may be necessary to call this function each time the time zone server is started. If persistence across reboots is desired the overload RTz::SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset, TBool aPersistInCenRep) should be used.
IMPORT_C void | SetUnknownZoneTimeL | ( | const TTime & | aUTCTime, |
const TInt | aUTCOffset, | |||
TBool | aPersistInCenRep | |||
) |
Sets the UTC time and the wall-clock offset for a zone not defined in the Timezone Database.
This is useful when the client wants to specify the UTC time and the wall-clock offset explicitly rather than using time zones. This function should be used instead of User::SetUTCOffset() and User::SetUTCTimeAndOffset().
If this function has been called the time zone server will use the value returned by User::UTCOffset() as the offset value when doing time conversions. Calling User::SetUTCOffset() may therefore cause unexpected results.
The fact that the time zone has been set to the unknown time zone is persisted across time zone server reboots only if the aPersistInCenRep argument is set to ETrue. The desired offset however is never persisted (the value returned by User::UTCOffset() is used). So it may be necessary to call this function each time the time zone server is started.
IMPORT_C void | SwiObsBeginL | ( | ) |
Called by the installation observer plugin to signal the start of an (un)install log.
IMPORT_C void | SwiObsEndL | ( | ) |
Called by the installation observer plugin to signal the end of an (un)install log.
IMPORT_C void | SwiObsFileChangedL | ( | TSWIObserverFilterIndex | aType | ) |
Called by the installation observer plugin to signal that the rules database or the resource files have been changed.
TSWIObserverFilterIndex aType | The type of file that has changed (resource or rules database). |
void | UpdateUserTimeZoneL | ( | const CTzId & | aTzId, |
const CTzRules & | aTzUserRules, | |||
const CTzUserNames & | aTzUserNames | |||
) |
const CTzId & aTzId | |
const CTzRules & aTzUserRules | |
const CTzUserNames & aTzUserNames |
IMPORT_C void | __dbgClearCacheL | ( | TBool | aRestartCaching | ) |
TBool aRestartCaching |
IMPORT_C TInt | __dbgRequestAllocatedCellsL | ( | TInt | aHeapSizeInBytes | ) |
TInt aHeapSizeInBytes |
IMPORT_C void | __dbgSetHeapFailL | ( | RAllocator::TAllocFail | aType, |
TInt | aRate | |||
) |
RAllocator::TAllocFail aType | |
TInt aRate |
void | doConvertL | ( | const CTzId & | aZone, |
TTime & | aTime, | |||
TTzTimeReference | aTimerRef | |||
) | const [private] |
const CTzId & aZone | |
TTime & aTime | |
TTzTimeReference aTimerRef |
void | doConvertL | ( | TTime & | aTime, |
TTzTimeReference | aTimerRef | |||
) | const [private] |
TTime & aTime | |
TTzTimeReference aTimerRef |
Time zone server panic codes.
EPanicServerNotFound = 1 |
This panic indicates that the time zone server has not been found. |
EPanicServerDead |
This panic indicates that the server has died. |
EPanicTimeZoneNameIdNotSet |
This panic indicates that the time zone ID is not set. |
EPanicRulesIndexOutofRange |
This panic indicates that an out of range index was accessed. |
EPanicTimeNotCoveredByRules |
This panic indicates that there are no rules present for this time zone. |
EPanicBadTimeZoneRules |
This panic indicates that the time zone rules are unusable. |
EPanicUnsupportedTimeReference |
This panic indicates that an unsupported time reference has been accessed. |
EPanicUnsupportedTimeZoneNoId |
This panic indicates that the time zone ID is not supported. |
EPanicNotificationRequestPending |
This panic indicates that a request for notification is already pending from the client. |
EPanicInvalidArgument |
This panic indicates that an incorrect data has been sent to the server. |
EPanicBadSchema |
This panic indicates that a table in the user-defined time zone database has not conformed to the declared schema. |
The software install observer plugin can distinguish between changes to the resource files or the rules database. This enumeration indicates the filter index that is used for the resource files and rules database filters. This enum should not be used externally.
EFilterTzPrivate = 0 |
The index of the Tz private directory filter. |
EFilterResourceTimezonelocalization |
The index of the resources filter. |
Automatic DST update mode.
ETZAutoDSTUpdateOff = 0 |
No auto update notification when a DST event occurs. |
ETZAutoDSTUpdateOn |
Automatic time update will occur and the client app will be notified. |
ETZAutoDSTNotificationOnly |
Client app needs to confirm that the time should be updated whenever a DST event occurs. |
Time zone server change events.
ETZDatabaseChanged = 1 |
Used for notifying that the timezone database has changed. |
ETZSystemTimeZoneChanged |
Used for notifying that the system timezone has changed. |
ETZDSTRuleChanged |
Used for notifying that the DST rule has changed. |
ETZAutomaticTimeUpdate |
Used for notifying that an automatic time update has taken place. |
ETZLocalizationDataChanged |
Used for notifying that a change in localization resources has taken place. |
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.