/* This file is part of the KDE libraries Copyright (c) 2005 S.R.Haque . This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License version 2 as published by the Free Software Foundation. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef _KTIMEZONES_H #define _KTIMEZONES_H #include "kdelibs_export.h" #include #include #include #include #include class KTimezoneDetails; class KTimezoneDetailsPrivate; class KTimezonePrivate; class KTimezonesPrivate; /** * The KTimezoneSource class contains information source-dependent functions * related to a timezone. Create subclasses to implement custom sources of * timezone information. * * For example, to be able to create {@link KTimezone } objects from libical's * VTIMEZONE objects: *
    *
  • Subclass this class with a custom {@link parse() } routine. *
  • Create one or more instances of this class. *
  • Use the instance(s) to create {@link KTimezone } objects. *
  • If required, add the objects to a {@link KTimezones } database. *
* @since 3.5 * @author S.R.Haque . */ class TDECORE_EXPORT KTimezoneSource : public KShared { public: KTimezoneSource(const TQString &db); virtual ~KTimezoneSource(); /** * Location of system timezone information. * @return value which can be combined with zone name to retrieve timezone info. */ virtual TQString db(); /** * Extract timezone detail information. The default implementation consists * of a parser for zoneinfo files in tzfile(5). * @return true if the parse encountered no errors. */ virtual bool parse(const TQString &zone, KTimezoneDetails &dataReceiver) const; private: TQString m_db; }; /** * The KTimezone class contains core functions related to a timezone. Instances * are created in the context of a {@link KTimezoneSource } which provides * extended functionality via {@link KTimezoneDetails }. * * @see KTimezoneSource * @see KTimezoneDetails * @since 3.5 * @author S.R.Haque . */ class TDECORE_EXPORT KTimezone { public: /** * A representation for unknown locations; this is a float * that does not represent a real latitude or longitude. */ static const float UNKNOWN; /** * A test for a valid latitude. The valid range is +90.0 (North Pole) * to -90.0 (South Pole). */ static bool isValidLatitude(float latitude); /** * A test for a valid longitude. The valid range is +180.0 (east of * Greenwich) to -180.0 (west of Greenwich). */ static bool isValidLongitude(float longitude); /** * Create a timezone. * * @param db database of timezones. * @param name in system-dependent format. * @param countryCode ISO 3166 2-character country code, empty if unknown. * @param latitude in degrees, UNKNOWN if not known. * @param longitude in degrees, UNKNOWN if not known. * @param comment description of the timezone, if any. */ KTimezone( KSharedPtr db, const TQString &name, const TQString &countryCode = TQString(), float latitude = UNKNOWN, float longitude = UNKNOWN, const TQString &comment = TQString()); ~KTimezone(); /** * Returns the name of the timezone. * * @return name in system-dependent format. */ TQString name() const; /** * Returns the two-letter country code of the timezone. * * @return ISO 3166 2-character country code, empty if unknown. */ TQString countryCode() const; /** * Returns the latitude of the timezone. * * @return latitude in degrees, UNKNOWN if not known. */ float latitude() const; /** * Returns the latitude of the timezone. * * @return latitude in degrees, UNKNOWN if not known. */ float longitude() const; /** * Returns the current offset of this timezone to UTC or the local * timezone in seconds. * * Take care if you cache the results of this routine; that would * break if the result were stored across a daylight savings change. * * @return offset in seconds. */ int offset(Qt::TimeSpec basisSpec = Qt::UTC) const; /** * Returns the offset of the given timezone to UTC at the given * date/time (which is interpreted as being UTC). * * @return offset in seconds. */ int offset(const TQDateTime &dateTime) const; /** * Convert a date/time (which is interpreted as being localtime in this * timezone) into localtime in the given timezone. * * @return converted date/time. */ TQDateTime convert(const KTimezone *newZone, const TQDateTime &dateTime) const; /** * Returns any comment for the timezone. * * @return comment, may be empty. */ TQString comment() const; /** * Extract timezone detail information. * @return true if the parse encountered no errors. */ bool parse(KTimezoneDetails &dataReceiver) const; private: KTimezone(const KTimezone&); KTimezone& operator=(const KTimezone&); KSharedPtr m_db; TQString m_name; TQString m_countryCode; float m_latitude; float m_longitude; TQString m_comment; KTimezonePrivate *d; }; /** * The KTimezoneDetails class contains extended functions related to a * timezone. * * The parser must be customised by overriding the given virtual callbacks: *
    *
  • {@link parseEnded() } *
  • {@link parseStarted() } *
  • {@link gotHeader() } *
  • {@link gotTransitionTime() } *
  • {@link gotLocalTimeIndex() } *
  • {@link gotLocalTime() } *
  • {@link gotAbbreviation() } *
  • {@link gotLeapAdjustment() } *
  • {@link gotIsStandard() } *
  • {@link gotIsUTC() } *
* * @see KTimezone * @since 3.5 * @author S.R.Haque . */ class TDECORE_EXPORT KTimezoneDetails { public: KTimezoneDetails(); virtual ~KTimezoneDetails(); /** * Always called after all other callbacks. */ virtual void parseEnded(); /** * Always called before any other callback. */ virtual void parseStarted(); /** * Called when the header is seen. */ virtual void gotHeader( unsigned ttIsGmtCnt, unsigned ttIsStdCnt, unsigned leapCnt, unsigned timeCnt, unsigned typeCnt, unsigned charCnt); /** * Called when a transition time is seen. */ virtual void gotTransitionTime(int index, unsigned transitionTime); /** * Called when a local time index is seen. */ virtual void gotLocalTimeIndex(int index, unsigned localTimeIndex); /** * Called when a local time is seen. */ virtual void gotLocalTime(int index, int gmtOff, bool isDst, unsigned abbrIndex); /** * Called when a timezone abbreviation is seen. Note that the index here * is NOT a simple incrementing integer, rather it matches the sequence * of abbrIndex values from {@link gotLocalTime() }. */ virtual void gotAbbreviation(int index, const TQString &abbr); /** * Called when a leap second adjustment is seen. */ virtual void gotLeapAdjustment(int index, unsigned leapTime, unsigned leapSeconds); /** * Called when a standard/wall time indicator is seen. */ virtual void gotIsStandard(int index, bool isStandard); /** * Called when a UTC/local time indicator is seen. */ virtual void gotIsUTC(int index, bool isUTC); private: KTimezoneDetailsPrivate *d; }; /** * The KTimezones class models a timezone database. It supports system * timezones, and also has support for private timezone entries. * * @since 3.5 * @author S.R.Haque . */ class TDECORE_EXPORT KTimezones { public: KTimezones(); ~KTimezones(); /** * Returns the local timezone. The idea of this routine is to provide a * robust lookup of the local timezone. * * The problem is that on Unix systems, there are a variety of mechanisms * for setting this information, and no real way of getting it. For example, * if you set your timezone to "Europe/London", then the tzname[] * maintained by tzset() typically returns { "GMT", "BST" }. The point of * this routine is to actually return "Europe/London" (or rather, the * corresponding KTimezone). * * @return local timezone. If necessary, we will use a series of heuristics * which end by returning UTC. We will never return NULL. */ const KTimezone *local(); /** * Returns the given timezone. * * @param name Name of timezone. Empty is equivalent to UTC. * @return named timezone, NULL on error. */ const KTimezone *zone(const TQString &name); typedef TQMap ZoneMap; /** * Return timezone database. * @return known timezones. */ const ZoneMap allZones(); /** * Add user-defined timezone to database. */ void add(KTimezone *zone); private: KTimezones(const KTimezones&); KTimezones& operator=(const KTimezones&); float convertCoordinate(const TQString &coordinate); TQString m_zoneinfoDir; ZoneMap *m_zones; KTimezone *m_UTC; KTimezonesPrivate *d; }; #endif