1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/tz.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,347 @@
1.4 +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// 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
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __TIMEZONE_H__
1.20 +#define __TIMEZONE_H__
1.21 +
1.22 +#include <e32base.h>
1.23 +#include <s32std.h>
1.24 +#include <tzdefines.h>
1.25 +#include <tzupdate.h>
1.26 +
1.27 +class CTzChangeNotifier;
1.28 +class CTzRules;
1.29 +class CTzRuleHolder;
1.30 +
1.31 +//-------------------------------------------------------------------------
1.32 +/**
1.33 +Encapsulates a time zone identifier.
1.34 +
1.35 +The identifier may be either a name or a number.
1.36 +@publishedAll
1.37 +@released
1.38 +@since 9.1
1.39 +*/
1.40 +class CTzId : public CBase
1.41 + {
1.42 +public:
1.43 +
1.44 + IMPORT_C ~CTzId();
1.45 +
1.46 + /**
1.47 + @internalComponent
1.48 + */
1.49 + IMPORT_C CTzId* CloneL() const;
1.50 +
1.51 + IMPORT_C static CTzId* NewL(TUint aNumericId);
1.52 +
1.53 + IMPORT_C static CTzId* NewL(const TDesC8& aNameIdentity);
1.54 +
1.55 + /**
1.56 + @internalComponent
1.57 + */
1.58 + IMPORT_C static CTzId* NewL(RReadStream& aStream);
1.59 +
1.60 + /**
1.61 + @internalComponent
1.62 + */
1.63 + IMPORT_C void SetId(TUint aNumericId);
1.64 +
1.65 + /**
1.66 + @internalComponent
1.67 + */
1.68 + IMPORT_C void SetIdL(const TDesC8& aNameIdentity);
1.69 +
1.70 + /**
1.71 + @internalComponent
1.72 + */
1.73 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.74 +
1.75 + /**
1.76 + @internalComponent
1.77 + */
1.78 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.79 +
1.80 + IMPORT_C const TDesC8& TimeZoneNameID() const;
1.81 +
1.82 + IMPORT_C TUint TimeZoneNumericID() const;
1.83 +
1.84 + IMPORT_C TBool operator==(const CTzId& aTZId) const;
1.85 +
1.86 + inline TBool operator!=(const CTzId& aTZId) const;
1.87 +
1.88 +public:
1.89 + static CTzId* NewL(TUint aReferenceId, const TDesC8& aZoneIdentity);
1.90 + void SetIdL(TUint aNumRefId, const TDesC8& aZoneIdentity);
1.91 +
1.92 +private:
1.93 + void ConstructL(const TDesC8& aZoneIdentity);
1.94 + CTzId();
1.95 + CTzId(TUint aNumericId);
1.96 +
1.97 +private:
1.98 + HBufC8* iZoneId;
1.99 + TUint32 iReferenceId;
1.100 + };
1.101 +
1.102 +
1.103 +/**
1.104 +The client interface to the time zone server.
1.105 +
1.106 +This class performs two basic functions:
1.107 +1. Converts between UTC time and local time.
1.108 +2. Sets the current local time zone.
1.109 +
1.110 +NOTE: The presence of a time zone server will alter the behaviour of the
1.111 +time zone related function calls User::SetUTCOffset() and
1.112 +User::SetUTCTimeAndOffset(). The time zone server is shutdown when the
1.113 +last session (RTz) is closed. Therefore, to maintain consistent time related behaviour,
1.114 +licensees may want to keep a system level time zone server session open at all times.
1.115 +
1.116 +@see User
1.117 +
1.118 +Exceptional cases occur when a user requests conversion
1.119 +for a non-existent local time or a double local time.
1.120 +
1.121 +Non-existent local times occur when the local time
1.122 +changes from winter to summer for DST.
1.123 +
1.124 +For example, 01:59 local time is non-existent on the day of a change to BST
1.125 +in Europe/London since the time changes directly from 12:59:59 to 2:00.
1.126 +
1.127 +A double local time occurs when the local time changes from
1.128 +summer to winter.
1.129 +
1.130 +For example, if the time changes at 02:00 AM BST to 01:00 AM GMT
1.131 +then local times between 01:00 and 01:59 occur twice.
1.132 +
1.133 +The conversion applies the DST offset if the local time value is double and applies
1.134 +the standard UTC offset if the local time does not exists.
1.135 +
1.136 +This decision makes the conversion process asymmetrical around
1.137 +the discontinuity in the local time when there is a DST change.
1.138 +
1.139 +An example conversion from a double local time to UTC and
1.140 +from UTC to a double local time is:
1.141 +
1.142 + 01:59 AM BST => 00:59 AM UTC
1.143 + 01:59 AM UTC => 01:59 AM GMT
1.144 +
1.145 +An example conversion from a non-existent local time to UTC
1.146 +and from UTC to local time is:
1.147 +
1.148 + 01:59 AM GMT => 01:59 AM UTC
1.149 + 01:59 AM UTC => 02:59 AM BST
1.150 +
1.151 +
1.152 +@publishedAll
1.153 +@released
1.154 +@since 9.1
1.155 +*/
1.156 +class RTz : public RSessionBase
1.157 + {
1.158 +public:
1.159 + /**
1.160 + These enumerators are to describe different modes of the automatic
1.161 + DST event handling.
1.162 +
1.163 + These are used both as arguments for the API SetAutoUpdateBehaviorL,
1.164 + and as notifications for the publish and subscribe.
1.165 + */
1.166 + enum TTzAutoDSTUpdateModes
1.167 + {
1.168 + /** No auto update notification when a DST event occurs. */
1.169 + ETZAutoDSTUpdateOff = 0,
1.170 +
1.171 + /** Automatic time update will occur and the client app will be notified. */
1.172 + ETZAutoDSTUpdateOn,
1.173 +
1.174 + /** Client app needs to confirm that the time should be updated whenever a DST event occurs. */
1.175 + ETZAutoDSTNotificationOnly,
1.176 + };
1.177 +
1.178 + enum TTzChanges
1.179 + {
1.180 + /** Used for notifying that the timezone database has changed.*/
1.181 + ETZDatabaseChanged = 1,
1.182 + /** Used for notifying that the system timezone database has changed.*/
1.183 + ETZSystemTimeZoneChanged,
1.184 + /** Used for notifying that the DST rule has changed. */
1.185 + ETZDSTRuleChanged,
1.186 + /** Used for notifying that an automatic time update has taken place. */
1.187 + ETZAutomaticTimeUpdate
1.188 + };
1.189 +
1.190 + enum TPanic
1.191 + {
1.192 + /** This panic indicates that the time zone server has not been found.*/
1.193 + EPanicServerNotFound = 1,
1.194 + /** This panic indicates that the server has died.*/
1.195 + EPanicServerDead,
1.196 + /** This panic indicates that the time zone ID is not set.*/
1.197 + EPanicTimeZoneNameIdNotSet,
1.198 + /** This panic indicates that an out of range index was accessed.*/
1.199 + EPanicRulesIndexOutofRange,
1.200 + /** This panic indicates that there are no rules present for this time zone.*/
1.201 + EPanicTimeNotCoveredByRules,
1.202 + /** This panic indicates that the time zone rules are unusable.*/
1.203 + EPanicBadTimeZoneRules,
1.204 + /** This panic indicates that an unsupported time reference has been accessed.*/
1.205 + EPanicUnsupportedTimeReference,
1.206 + /** This panic indicates that the time zone ID is not supported.*/
1.207 + EPanicUnsupportedTimeZoneNoId,
1.208 + /** This panic indicates that a request for notification is already pending from the client.*/
1.209 + EPanicNotificationRequestPending,
1.210 + /** This panic indicates that an incorrect data has been sent to the server.*/
1.211 + EPanicInvalidArgument
1.212 + };
1.213 +
1.214 + /**
1.215 + @internalComponent
1.216 + */
1.217 + IMPORT_C static void Panic(TPanic aPanic);
1.218 +
1.219 + /**
1.220 + @internalTechnology
1.221 + */
1.222 + IMPORT_C CTzId* GetTimeZoneIdL() const;
1.223 +
1.224 + /**
1.225 + @internalTechnology
1.226 + */
1.227 + IMPORT_C void SetTimeZoneL(CTzId& aZone) const;
1.228 +
1.229 + IMPORT_C void Close();
1.230 +
1.231 + IMPORT_C TInt Connect();
1.232 +
1.233 + IMPORT_C ~RTz();
1.234 +
1.235 + IMPORT_C RTz();
1.236 +
1.237 + IMPORT_C TInt ConvertToLocalTime(TTime& aTime) const;
1.238 +
1.239 + IMPORT_C TInt ConvertToLocalTime(TTime& aTime, const CTzId& aZone) const;
1.240 +
1.241 + IMPORT_C TInt ConvertToUniversalTime(TTime& aTime) const;
1.242 +
1.243 + IMPORT_C TInt ConvertToUniversalTime(TTime& aTime, const CTzId& aZone) const;
1.244 +
1.245 + IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray<TInt>& aTzNumericIds, RArray<TInt>& aOffsets) const;
1.246 +
1.247 + IMPORT_C TInt AutoUpdateSettingL();
1.248 +
1.249 + IMPORT_C void SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes aUpdateEnabled);
1.250 +
1.251 + // Methods for setting the system time.
1.252 + IMPORT_C TInt SetHomeTime(const TTime& aLocalTime) const;
1.253 +
1.254 + IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone) const;
1.255 +
1.256 + IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone, const TTime& aUTCTime) const;
1.257 +
1.258 + // Get Encoded Rules for Current Local Time Zone
1.259 + IMPORT_C CTzRules* GetTimeZoneRulesL(const TTime& aStartTime, const TTime& aEndTime, TTzTimeReference aTimeRef) const;
1.260 +
1.261 + IMPORT_C CTzRules* GetTimeZoneRulesL(const CTzId& aZone, const TTime& aStartTime, const TTime& aEndTime, TTzTimeReference aTimeRef) const;
1.262 +
1.263 + void RegisterTzChangeNotifier(TRequestStatus& aStatus) const;
1.264 + TInt CancelRequestForNotice() const;
1.265 + TVersion Version() const;
1.266 +
1.267 + IMPORT_C void NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange& aChange) const;
1.268 +
1.269 + IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset);
1.270 +
1.271 + IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset, TBool aPersistInCenRep);
1.272 +
1.273 + IMPORT_C void __dbgClearCacheL(TBool aRestartCaching);
1.274 +
1.275 + TBool StartCachingL();
1.276 + TUint16 CurrentCachedTzId();
1.277 +
1.278 +private:
1.279 + static TInt StartServer();
1.280 + TInt DoConnect();
1.281 + void doConvertL(const CTzId& aZone, TTime& aTime,
1.282 + TTzTimeReference aTimerRef) const;
1.283 + void doConvertL(TTime& aTime,
1.284 + TTzTimeReference aTimerRef) const;
1.285 +private:
1.286 + CTzRuleHolder* iRulesHolder;
1.287 + };
1.288 +
1.289 +/**
1.290 +Encapsulates a TTime and a TTzTimeReference.
1.291 +Use, for example, for iCalendar's DTSTART.
1.292 +
1.293 +@publishedAll
1.294 +@released
1.295 +*/
1.296 +class TTimeWithReference
1.297 + {
1.298 +public:
1.299 + static inline TTimeWithReference Max();
1.300 + inline TTimeWithReference();
1.301 + inline TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference);
1.302 + inline TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference);
1.303 + inline bool operator==(const TTimeWithReference& aTime) const;
1.304 + inline bool operator!=(const TTimeWithReference& aTime) const;
1.305 +
1.306 + TTime iTime;
1.307 + TTzTimeReference iTimeReference;
1.308 + };
1.309 +
1.310 +/** Inequality operator.
1.311 +
1.312 +@param aTZId The time zone ID to compare with this one.
1.313 +@return True if the two IDs are different. False if they are the same.
1.314 +*/
1.315 +inline TBool CTzId::operator!=(const CTzId& aTZId) const
1.316 + {
1.317 + return (!operator==(aTZId));
1.318 + }
1.319 +
1.320 +//////////////////////////////////
1.321 +// TTimeWithReference
1.322 +//////////////////////////////////
1.323 +inline TTimeWithReference TTimeWithReference::Max()
1.324 + {
1.325 + return TTimeWithReference(
1.326 + TDateTime(9999,EDecember,30,23,59,59,0),
1.327 + ETzUtcTimeReference);
1.328 + }
1.329 +
1.330 +inline TTimeWithReference::TTimeWithReference()
1.331 + : iTime(0), iTimeReference(ETzUtcTimeReference)
1.332 + {
1.333 + }
1.334 +inline TTimeWithReference::TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference)
1.335 + : iTime(aTime), iTimeReference(aTimeReference)
1.336 + {
1.337 + }
1.338 +inline TTimeWithReference::TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference)
1.339 + : iTime(aTime), iTimeReference(aTimeReference)
1.340 + {
1.341 + }
1.342 +inline bool TTimeWithReference::operator==(const TTimeWithReference& aTime) const
1.343 + {
1.344 + return(aTime.iTime == iTime && aTime.iTimeReference == iTimeReference);
1.345 + }
1.346 +inline bool TTimeWithReference::operator!=(const TTimeWithReference& aTime) const
1.347 + {
1.348 + return(!(*this == aTime));
1.349 + }
1.350 +#endif