--- a/epoc32/include/mw/tz.h Wed Mar 31 12:27:01 2010 +0100
+++ b/epoc32/include/mw/tz.h Wed Mar 31 12:33:34 2010 +0100
@@ -1,9 +1,9 @@
// Copyright (c) 1997-2009 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 "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
-// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
@@ -16,125 +16,126 @@
#ifndef __TIMEZONE_H__
#define __TIMEZONE_H__
+
#include <e32base.h>
#include <s32std.h>
+#include <s32strm.h>
#include <tzdefines.h>
+#include <tzid.h>
#include <tzupdate.h>
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+#include <tzlocalizedcityrecord.h> //This should be be included as it is internalTechnology.
+#include <tzlocalizedtimezonerecord.h> // Same as above and probably should not be exported to the epoc include
+#endif
-class CTzChangeNotifier;
+
+// Forward class references.
class CTzRules;
class CTzRuleHolder;
-
-//-------------------------------------------------------------------------
-/**
-Encapsulates a time zone identifier.
+class CTzLocalizedCityRecord;
+#ifdef SYMBIAN_ENABLE_SPLIT_HEADERS // This can be forward declared i.e. it should not be included as it is internal.
+class CTzLocalizedTimeZoneRecord;
+#endif
-The identifier may be either a name or a number.
-@publishedAll
-@released
-@since 9.1
-*/
-class CTzId : public CBase
- {
-public:
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+/**
+The CTzUserNames class is used to encapsulate the names for a user-defined
+time zone.
+
+When creating an instance of this class the client can specify the following
+names:
- IMPORT_C ~CTzId();
-
- /**
- @internalComponent
- */
- IMPORT_C CTzId* CloneL() const;
-
- IMPORT_C static CTzId* NewL(TUint aNumericId);
-
- IMPORT_C static CTzId* NewL(const TDesC8& aNameIdentity);
-
- /**
- @internalComponent
- */
- IMPORT_C static CTzId* NewL(RReadStream& aStream);
+- Long standard time name, for example "Mountain Standard Time"
+- Short standard time name, for example "MST"
+- Long daylight saving time name, for example "Mountain Daylight Time"
+- Short daylight saving time name, for example "MDT"
+- City name, for example "Shiprock"
+- Region name, for example "America"
+
+The client can also read these names.
+
+@publishedPartner
+@released
+*/
+class CTzUserNames : public CBase
+ {
+public:
+ IMPORT_C static CTzUserNames* NewL(const TDesC& aStandardName,
+ const TDesC& aShortStandardName, const TDesC& aDaylightSaveName,
+ const TDesC& aShortDaylightSaveName, const TDesC& aCityName,
+ const TDesC& aRegionName);
+ IMPORT_C static CTzUserNames* NewLC(const TDesC& aStandardName,
+ const TDesC& aShortStandardName, const TDesC& aDayLightSaveName,
+ const TDesC& aShortDaylightSaveName, const TDesC& aCityName,
+ const TDesC& aRegionName);
+ IMPORT_C ~CTzUserNames();
- /**
- @internalComponent
- */
- IMPORT_C void SetId(TUint aNumericId);
-
- /**
- @internalComponent
- */
- IMPORT_C void SetIdL(const TDesC8& aNameIdentity);
-
- /**
- @internalComponent
- */
- IMPORT_C void InternalizeL(RReadStream& aStream);
+ IMPORT_C const TDesC& StandardName() const;
+ IMPORT_C const TDesC& ShortStandardName() const;
+ IMPORT_C const TDesC& DaylightSaveName() const;
+ IMPORT_C const TDesC& ShortDaylightSaveName() const;
+ IMPORT_C const TDesC& CityName() const;
+ IMPORT_C const TDesC& RegionName() const;
- /**
- @internalComponent
- */
+ IMPORT_C static CTzUserNames* NewL(RReadStream& aStream);
IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
-
- IMPORT_C const TDesC8& TimeZoneNameID() const;
-
- IMPORT_C TUint TimeZoneNumericID() const;
-
- IMPORT_C TBool operator==(const CTzId& aTZId) const;
-
- inline TBool operator!=(const CTzId& aTZId) const;
-
-public:
- static CTzId* NewL(TUint aReferenceId, const TDesC8& aZoneIdentity);
- void SetIdL(TUint aNumRefId, const TDesC8& aZoneIdentity);
+ IMPORT_C void InternalizeL(RReadStream& aStream);
+ IMPORT_C TInt SizeOfObject() const;
private:
- void ConstructL(const TDesC8& aZoneIdentity);
- CTzId();
- CTzId(TUint aNumericId);
-
+ CTzUserNames();
+ void ConstructL(const TDesC& aStandardName, const TDesC& aShortStandardName,
+ const TDesC& aDayLightSaveName, const TDesC& aShortDayLightSaveName,
+ const TDesC& aCityName, const TDesC& aRegionName);
+
private:
- HBufC8* iZoneId;
- TUint32 iReferenceId;
- };
-
-
+ HBufC* iStandardName;
+ HBufC* iShortStandardName;
+ HBufC* iDaylightName;
+ HBufC* iShortDaylightName;
+ HBufC* iCityName;
+ HBufC* iRegionName;
+ };
+#else
+class CTzUserNames;
+#endif //SYMBIAN_ENABLE_SPLIT_HEADERS
/**
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.
-
-@see User
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+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:
+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
@@ -145,7 +146,6 @@
01:59 AM GMT => 01:59 AM UTC
01:59 AM UTC => 02:59 AM BST
-
@publishedAll
@released
@since 9.1
@@ -154,36 +154,43 @@
{
public:
/**
- These enumerators are to describe different modes of the automatic
- DST event handling.
-
- These are used both as arguments for the API SetAutoUpdateBehaviorL,
- and as notifications for the publish and subscribe.
+ Automatic DST update mode.
*/
enum TTzAutoDSTUpdateModes
{
/** No auto update notification when a DST event occurs. */
ETZAutoDSTUpdateOff = 0,
- /** Automatic time update will occur and the client app will be notified. */
+ /** Automatic time update will occur and the client app will be
+ notified. */
ETZAutoDSTUpdateOn,
- /** Client app needs to confirm that the time should be updated whenever a DST event occurs. */
+ /** Client app needs to confirm that the time should be updated whenever
+ a DST event occurs. */
ETZAutoDSTNotificationOnly,
};
+ /**
+ Time zone server change events.
+ */
enum TTzChanges
{
/** Used for notifying that the timezone database has changed.*/
ETZDatabaseChanged = 1,
- /** Used for notifying that the system timezone database has changed.*/
+ /** Used for notifying that the system timezone has changed.*/
ETZSystemTimeZoneChanged,
/** Used for notifying that the DST rule has changed. */
ETZDSTRuleChanged,
/** Used for notifying that an automatic time update has taken place. */
- ETZAutomaticTimeUpdate
+ ETZAutomaticTimeUpdate,
+ /** Used for notifying that a change in localization resources has taken
+ place. */
+ ETZLocalizationDataChanged
};
+ /**
+ Time zone server panic codes.
+ */
enum TPanic
{
/** This panic indicates that the time zone server has not been found.*/
@@ -194,84 +201,142 @@
EPanicTimeZoneNameIdNotSet,
/** This panic indicates that an out of range index was accessed.*/
EPanicRulesIndexOutofRange,
- /** This panic indicates that there are no rules present for this time zone.*/
+ /** This panic indicates that there are no rules present for this time
+ zone.*/
EPanicTimeNotCoveredByRules,
/** This panic indicates that the time zone rules are unusable.*/
EPanicBadTimeZoneRules,
- /** This panic indicates that an unsupported time reference has been accessed.*/
+ /** This panic indicates that an unsupported time reference has been
+ accessed.*/
EPanicUnsupportedTimeReference,
/** This panic indicates that the time zone ID is not supported.*/
EPanicUnsupportedTimeZoneNoId,
- /** This panic indicates that a request for notification is already pending from the client.*/
+ /** This panic indicates that a request for notification is already
+ pending from the client.*/
EPanicNotificationRequestPending,
- /** This panic indicates that an incorrect data has been sent to the server.*/
- EPanicInvalidArgument
+ /** This panic indicates that an incorrect data has been sent to the
+ server.*/
+ EPanicInvalidArgument,
+ /** This panic indicates that a table in the user-defined time zone
+ database has not conformed to the declared schema. */
+ EPanicBadSchema
};
+ /**
+ 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.
+ */
+ enum TSWIObserverFilterIndex
+ {
+ /** The index of the Tz private directory filter. */
+ EFilterTzPrivate=0,
+ /** The index of the resources filter. */
+ EFilterResourceTimezonelocalization
+ };
+
+public:
/**
- @internalComponent
+ This should not be used externally.
*/
IMPORT_C static void Panic(TPanic aPanic);
/**
- @internalTechnology
+ This should not be used externally.
*/
IMPORT_C CTzId* GetTimeZoneIdL() const;
/**
- @internalTechnology
+ This should not be used externally.
*/
IMPORT_C void SetTimeZoneL(CTzId& aZone) const;
IMPORT_C void Close();
-
IMPORT_C TInt Connect();
IMPORT_C ~RTz();
-
IMPORT_C RTz();
IMPORT_C TInt ConvertToLocalTime(TTime& aTime) const;
-
IMPORT_C TInt ConvertToLocalTime(TTime& aTime, const CTzId& aZone) const;
-
IMPORT_C TInt ConvertToUniversalTime(TTime& aTime) const;
-
IMPORT_C TInt ConvertToUniversalTime(TTime& aTime, const CTzId& aZone) const;
- IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray<TInt>& aTzNumericIds, RArray<TInt>& aOffsets) const;
+ IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray<TInt>& aTzNumericIds,
+ RArray<TInt>& aOffsets) const;
IMPORT_C TInt AutoUpdateSettingL();
-
IMPORT_C void SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes aUpdateEnabled);
// Methods for setting the system time.
IMPORT_C TInt SetHomeTime(const TTime& aLocalTime) const;
IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone) const;
-
IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone, const TTime& aUTCTime) const;
// Get Encoded Rules for Current Local Time Zone
- IMPORT_C CTzRules* GetTimeZoneRulesL(const TTime& aStartTime, const TTime& aEndTime, TTzTimeReference aTimeRef) const;
-
- IMPORT_C CTzRules* GetTimeZoneRulesL(const CTzId& aZone, const TTime& aStartTime, const TTime& aEndTime, TTzTimeReference aTimeRef) const;
+ IMPORT_C CTzRules* GetTimeZoneRulesL(const TTime& aStartTime,
+ const TTime& aEndTime, TTzTimeReference aTimeRef) const;
+ IMPORT_C CTzRules* GetTimeZoneRulesL(const CTzId& aZone,
+ const TTime& aStartTime, const TTime& aEndTime,
+ TTzTimeReference aTimeRef) const;
void RegisterTzChangeNotifier(TRequestStatus& aStatus) const;
TInt CancelRequestForNotice() const;
TVersion Version() const;
- IMPORT_C void NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange& aChange) const;
+ IMPORT_C void NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange&
+ aChange) const;
- IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset);
+ IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime,
+ const TInt aUTCOffset);
+ IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime,
+ const TInt aUTCOffset, TBool aPersistInCenRep);
- IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset, TBool aPersistInCenRep);
+ IMPORT_C void LocalizationReadCitiesL(RPointerArray<CTzLocalizedCityRecord>&
+ aCities);
+ IMPORT_C void LocalizationReadCitiesL(RPointerArray<CTzLocalizedCityRecord>&
+ aCities, TInt aTimeZoneId);
+ IMPORT_C void LocalizationReadCitiesInGroupL(RPointerArray<CTzLocalizedCityRecord>&
+ aCities, TUint8 aGroupId);
+ IMPORT_C CTzLocalizedTimeZoneRecord* LocalizationReadFrequentlyUsedZoneL(
+ TInt aFrequentlyUsedZone);
+ IMPORT_C CTzLocalizedCityRecord* LocalizationReadCachedTimeZoneCityL(
+ TInt aFrequentlyUsedZone);
+ IMPORT_C void LocalizationCloseDbL();
+ IMPORT_C void LocalizationOpenDbL();
+ IMPORT_C void LocalizationWriteCityL(const TDesC& aCityName, TInt aCityTzId,
+ TUint8 aCityGroupId, TUint aCityTzResourceId);
+ IMPORT_C void LocalizationDeleteCityL(const TDesC& aCityName,
+ TInt aCityTzId);
+ IMPORT_C void LocalizationWriteFrequentlyUsedZoneL(const CTzLocalizedTimeZoneRecord&
+ aTimeZone, const CTzLocalizedCityRecord& aCity,
+ TInt aFrequentlyUsedZone);
+ IMPORT_C void LocalizationWriteAllFrequentlyUsedZonesL(const RPointerArray<CTzLocalizedTimeZoneRecord>& aTimeZones,
+ const RPointerArray<CTzLocalizedCityRecord>& aCities);
+
+ // Debug only methods.
+ IMPORT_C void SwiObsBeginL();
+ IMPORT_C void SwiObsFileChangedL(TSWIObserverFilterIndex aType);
+ IMPORT_C void SwiObsEndL();
+ // Debug only methods.
IMPORT_C void __dbgClearCacheL(TBool aRestartCaching);
+ IMPORT_C TInt __dbgRequestAllocatedCellsL(TInt aHeapSizeInBytes);
+ IMPORT_C void __dbgSetHeapFailL(RAllocator::TAllocFail aType, TInt aRate);
+ IMPORT_C void __dbgResetHeapL();
TBool StartCachingL();
TUint16 CurrentCachedTzId();
+ // User-defined time zone access.
+ CTzId* CreateUserTimeZoneL(const CTzRules& aTzUserRules, const CTzUserNames& aTzUserNames);
+ CTzUserNames* GetUserTimeZoneNamesL(const CTzId& aTzId) const;
+ void UpdateUserTimeZoneL(const CTzId& aTzId, const CTzRules& aTzUserRules, const CTzUserNames& aTzUserNames);
+ void DeleteUserTimeZoneL(const CTzId& aTzId);
+ void GetUserTimeZoneIdsL(RPointerArray<CTzId>& aTzIds) const;
+
private:
static TInt StartServer();
TInt DoConnect();
@@ -279,13 +344,16 @@
TTzTimeReference aTimerRef) const;
void doConvertL(TTime& aTime,
TTzTimeReference aTimerRef) const;
+
+
+
private:
CTzRuleHolder* iRulesHolder;
};
+
/**
Encapsulates a TTime and a TTzTimeReference.
-Use, for example, for iCalendar's DTSTART.
@publishedAll
@released
@@ -294,9 +362,11 @@
{
public:
static inline TTimeWithReference Max();
+
inline TTimeWithReference();
inline TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference);
inline TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference);
+
inline bool operator==(const TTimeWithReference& aTime) const;
inline bool operator!=(const TTimeWithReference& aTime) const;
@@ -304,19 +374,7 @@
TTzTimeReference iTimeReference;
};
-/** Inequality operator.
-@param aTZId The time zone ID to compare with this one.
-@return True if the two IDs are different. False if they are the same.
-*/
-inline TBool CTzId::operator!=(const CTzId& aTZId) const
- {
- return (!operator==(aTZId));
- }
-
-//////////////////////////////////
-// TTimeWithReference
-//////////////////////////////////
inline TTimeWithReference TTimeWithReference::Max()
{
return TTimeWithReference(
@@ -324,24 +382,75 @@
ETzUtcTimeReference);
}
+
inline TTimeWithReference::TTimeWithReference()
- : iTime(0), iTimeReference(ETzUtcTimeReference)
+ : iTime(0), iTimeReference(ETzUtcTimeReference)
{
}
+
+
inline TTimeWithReference::TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference)
- : iTime(aTime), iTimeReference(aTimeReference)
+ : iTime(aTime), iTimeReference(aTimeReference)
{
}
+
+
inline TTimeWithReference::TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference)
- : iTime(aTime), iTimeReference(aTimeReference)
+ : iTime(aTime), iTimeReference(aTimeReference)
{
}
+
+
inline bool TTimeWithReference::operator==(const TTimeWithReference& aTime) const
{
return(aTime.iTime == iTime && aTime.iTimeReference == iTimeReference);
}
+
+
inline bool TTimeWithReference::operator!=(const TTimeWithReference& aTime) const
{
return(!(*this == aTime));
}
+
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+/**
+The CTzUserData class allows the client to create, read, update or delete
+user-defined time zones.
+
+A user-defined time zone is comprised of time zone rules (encapsulated in a
+CTzRules object) and time zone names (encapsulated in a CTzUserNames object).
+
+A time zone identifier (encapsulated in a CTzId object) is used to uniquely
+identify a user-defined time zone.
+
+The CTzUserData class also allows the time zone identifiers for all existing
+user-defined time zones to be determined.
+
+@publishedPartner
+@released
+*/
+class CTzUserData : public CBase
+ {
+public:
+ IMPORT_C static CTzUserData* NewL(RTz& aTzServer);
+ IMPORT_C ~CTzUserData();
+
+ IMPORT_C CTzId* CreateL(const CTzRules& aTzUserRules, const CTzUserNames&
+ aTzUserNames);
+ IMPORT_C CTzRules* ReadRulesL(const CTzId& aTzId) const;
+ IMPORT_C CTzUserNames* ReadNamesL(const CTzId& aTzId) const;
+ IMPORT_C void UpdateL(const CTzId& aTzId, const CTzRules& aTzUserRules,
+ const CTzUserNames& aTzUserNames);
+ IMPORT_C void DeleteL(const CTzId& aTzId);
+ IMPORT_C void GetTzIdsL(RPointerArray<CTzId>& aTzIds) const;
+
+private:
+ CTzUserData(RTz& aTzServer);
+
+private:
+ RTz& iTzServer;
+ };
+
+#endif // SYMBIAN_ENABLE_SPLIT_HEADERS
+
#endif