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