diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/mw/tz.h --- 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 #include +#include #include +#include #include +#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS +#include //This should be be included as it is internalTechnology. +#include // 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& aTzNumericIds, RArray& aOffsets) const; + IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray& aTzNumericIds, + RArray& 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& + aCities); + IMPORT_C void LocalizationReadCitiesL(RPointerArray& + aCities, TInt aTimeZoneId); + IMPORT_C void LocalizationReadCitiesInGroupL(RPointerArray& + 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& aTimeZones, + const RPointerArray& 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& 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& aTzIds) const; + +private: + CTzUserData(RTz& aTzServer); + +private: + RTz& iTzServer; + }; + +#endif // SYMBIAN_ENABLE_SPLIT_HEADERS + #endif