home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / ktimezones.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-03-17  |  9.8 KB  |  352 lines
  1. /*
  2.    This file is part of the KDE libraries
  3.    Copyright (c) 2005 S.R.Haque <srhaque@iee.org>.
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License version 2 as published by the Free Software Foundation.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef _KTIMEZONES_H
  21. #define _KTIMEZONES_H
  22.  
  23. #include "kdelibs_export.h"
  24. #include <qdatetime.h>
  25. #include <qnamespace.h>
  26. #include <qmap.h>
  27. #include <qstring.h>
  28. #include <ksharedptr.h>
  29.  
  30. class KTimezoneDetails;
  31. class KTimezoneDetailsPrivate;
  32. class KTimezonePrivate;
  33. class KTimezonesPrivate;
  34.  
  35. /**
  36.  * The KTimezoneSource class contains information source-dependent functions
  37.  * related to a timezone. Create subclasses to implement custom sources of
  38.  * timezone information.
  39.  *
  40.  * For example, to be able to create {@link KTimezone } objects from libical's
  41.  * VTIMEZONE objects:
  42.  *<ul>
  43.  *      <li>Subclass this class with a custom {@link parse() } routine.
  44.  *      <li>Create one or more instances of this class.
  45.  *      <li>Use the instance(s) to create {@link KTimezone } objects.
  46.  *      <li>If required, add the objects to a {@link KTimezones } database.
  47.  *</ul>
  48.  * @since 3.5
  49.  * @author S.R.Haque <srhaque@iee.org>.
  50.  */
  51. class KDECORE_EXPORT KTimezoneSource :
  52.     public KShared
  53. {
  54. public:
  55.     KTimezoneSource(const QString &db);
  56.     virtual ~KTimezoneSource();
  57.  
  58.     /**
  59.      * Location of system timezone information.
  60.      * @return value which can be combined with zone name to retrieve timezone info.
  61.      */
  62.     virtual QString db();
  63.  
  64.     /**
  65.      * Extract timezone detail information. The default implementation consists
  66.      * of a parser for zoneinfo files in tzfile(5).
  67.      * @return true if the parse encountered no errors.
  68.      */
  69.     virtual bool parse(const QString &zone, KTimezoneDetails &dataReceiver) const;
  70.  
  71. private:
  72.     QString m_db;
  73. };
  74.  
  75. /**
  76.  * The KTimezone class contains core functions related to a timezone. Instances
  77.  * are created in the context of a {@link KTimezoneSource } which provides
  78.  * extended functionality via {@link KTimezoneDetails }.
  79.  *
  80.  * @see KTimezoneSource
  81.  * @see KTimezoneDetails
  82.  * @since 3.5
  83.  * @author S.R.Haque <srhaque@iee.org>.
  84.  */
  85. class KDECORE_EXPORT KTimezone
  86. {
  87. public:
  88.     /**
  89.      * A representation for unknown locations; this is a float
  90.      * that does not represent a real latitude or longitude.
  91.      */
  92.     static const float UNKNOWN;
  93.  
  94.     /**
  95.      * A test for a valid latitude. The valid range is +90.0 (North Pole)
  96.      * to -90.0 (South Pole).
  97.      */
  98.     static bool isValidLatitude(float latitude);
  99.  
  100.     /**
  101.      * A test for a valid longitude. The valid range is +180.0 (east of
  102.      * Greenwich) to -180.0 (west of Greenwich).
  103.      */
  104.     static bool isValidLongitude(float longitude);
  105.  
  106.     /**
  107.      * Create a timezone.
  108.      *
  109.      * @param db database of timezones.
  110.      * @param name in system-dependent format.
  111.      * @param countryCode ISO 3166 2-character country code, empty if unknown.
  112.      * @param latitude in degrees, UNKNOWN if not known.
  113.      * @param longitude in degrees, UNKNOWN if not known.
  114.      * @param comment description of the timezone, if any.
  115.      */
  116.     KTimezone(
  117.         KSharedPtr<KTimezoneSource> db, const QString &name,
  118.         const QString &countryCode = QString(), float latitude = UNKNOWN, float longitude = UNKNOWN,
  119.         const QString &comment = QString());
  120.     ~KTimezone();
  121.  
  122.     /**
  123.      * Returns the name of the timezone.
  124.      *
  125.      * @return name in system-dependent format.
  126.      */
  127.     QString name() const;
  128.  
  129.     /**
  130.      * Returns the two-letter country code of the timezone.
  131.      *
  132.      * @return ISO 3166 2-character country code, empty if unknown.
  133.      */
  134.     QString countryCode() const;
  135.  
  136.     /**
  137.      * Returns the latitude of the timezone.
  138.      *
  139.      * @return latitude in degrees, UNKNOWN if not known.
  140.      */
  141.     float latitude() const;
  142.  
  143.     /**
  144.      * Returns the latitude of the timezone.
  145.      *
  146.      * @return latitude in degrees, UNKNOWN if not known.
  147.      */
  148.     float longitude() const;
  149.  
  150.     /**
  151.      * Returns the current offset of this timezone to UTC or the local
  152.      * timezone in seconds.
  153.      *
  154.      * Take care if you cache the results of this routine; that would
  155.      * break if the result were stored across a daylight savings change.
  156.      *
  157.      * @return offset in seconds.
  158.      */
  159.     int offset(Qt::TimeSpec basisSpec = Qt::UTC) const;
  160.  
  161.     /**
  162.      * Returns the offset of the given timezone to UTC at the given
  163.      * date/time (which is interpreted as being UTC).
  164.      *
  165.      * @return offset in seconds.
  166.      */
  167.     int offset(const QDateTime &dateTime) const;
  168.  
  169.     /**
  170.      * Convert a date/time (which is interpreted as being localtime in this
  171.      * timezone) into localtime in the given timezone.
  172.      *
  173.      * @return converted date/time.
  174.      */
  175.     QDateTime convert(const KTimezone *newZone, const QDateTime &dateTime) const;
  176.  
  177.     /**
  178.      * Returns any comment for the timezone.
  179.      *
  180.      * @return comment, may be empty.
  181.      */
  182.     QString comment() const;
  183.  
  184.     /**
  185.      * Extract timezone detail information.
  186.      * @return true if the parse encountered no errors.
  187.      */
  188.     bool parse(KTimezoneDetails &dataReceiver) const;
  189.  
  190. private:
  191.     KTimezone(const KTimezone&);
  192.     KTimezone& operator=(const KTimezone&);
  193.  
  194.     KSharedPtr<KTimezoneSource> m_db;
  195.     QString m_name;
  196.     QString m_countryCode;
  197.     float m_latitude;
  198.     float m_longitude;
  199.     QString m_comment;
  200.     KTimezonePrivate *d;
  201. };
  202.  
  203. /**
  204.  * The KTimezoneDetails class contains extended functions related to a
  205.  * timezone.
  206.  *
  207.  * The parser must be customised by overriding the given virtual callbacks:
  208.  *<ul>
  209.  *    <li>{@link parseEnded() }
  210.  *    <li>{@link parseStarted() }
  211.  *    <li>{@link gotHeader() }
  212.  *    <li>{@link gotTransitionTime() }
  213.  *    <li>{@link gotLocalTimeIndex() }
  214.  *    <li>{@link gotLocalTime() }
  215.  *    <li>{@link gotAbbreviation() }
  216.  *    <li>{@link gotLeapAdjustment() }
  217.  *    <li>{@link gotIsStandard() }
  218.  *    <li>{@link gotIsUTC() }
  219.  *</ul>
  220.  *
  221.  * @see KTimezone
  222.  * @since 3.5
  223.  * @author S.R.Haque <srhaque@iee.org>.
  224.  */
  225. class KDECORE_EXPORT KTimezoneDetails
  226. {
  227. public:
  228.     KTimezoneDetails();
  229.     virtual ~KTimezoneDetails();
  230.  
  231.     /**
  232.      * Always called after all other callbacks.
  233.      */
  234.     virtual void parseEnded();
  235.  
  236.     /**
  237.      * Always called before any other callback.
  238.      */
  239.     virtual void parseStarted();
  240.  
  241.     /**
  242.      * Called when the header is seen.
  243.      */
  244.     virtual void gotHeader(
  245.         unsigned ttIsGmtCnt, unsigned ttIsStdCnt, unsigned leapCnt,
  246.         unsigned timeCnt, unsigned typeCnt, unsigned charCnt);
  247.  
  248.     /**
  249.      * Called when a transition time is seen.
  250.      */
  251.     virtual void gotTransitionTime(int index, unsigned transitionTime);
  252.  
  253.     /**
  254.      * Called when a local time index is seen.
  255.      */
  256.     virtual void gotLocalTimeIndex(int index, unsigned localTimeIndex);
  257.  
  258.     /**
  259.      * Called when a local time is seen.
  260.      */
  261.     virtual void gotLocalTime(int index, int gmtOff, bool isDst, unsigned abbrIndex);
  262.  
  263.     /**
  264.      * Called when a timezone abbreviation is seen. Note that the index here
  265.      * is NOT a simple incrementing integer, rather it matches the sequence
  266.      * of abbrIndex values from {@link gotLocalTime() }.
  267.      */
  268.     virtual void gotAbbreviation(int index, const QString &abbr);
  269.  
  270.     /**
  271.      * Called when a leap second adjustment is seen.
  272.      */
  273.     virtual void gotLeapAdjustment(int index, unsigned leapTime, unsigned leapSeconds);
  274.  
  275.     /**
  276.      * Called when a standard/wall time indicator is seen.
  277.      */
  278.     virtual void gotIsStandard(int index, bool isStandard);
  279.  
  280.     /**
  281.      * Called when a UTC/local time indicator is seen.
  282.      */
  283.     virtual void gotIsUTC(int index, bool isUTC);
  284.  
  285. private:
  286.     KTimezoneDetailsPrivate *d;
  287. };
  288.  
  289. /**
  290.  * The KTimezones class models a timezone database. It supports system
  291.  * timezones, and also has support for private timezone entries.
  292.  *
  293.  * @since 3.5
  294.  * @author S.R.Haque <srhaque@iee.org>.
  295.  */
  296. class KDECORE_EXPORT KTimezones
  297. {
  298. public:
  299.     KTimezones();
  300.     ~KTimezones();
  301.  
  302.     /**
  303.      * Returns the local timezone. The idea of this routine is to provide a
  304.      * robust lookup of the local timezone.
  305.      *
  306.      * The problem is that on Unix systems, there are a variety of mechanisms
  307.      * for setting this information, and no real way of getting it. For example,
  308.      * if you set your timezone to "Europe/London", then the tzname[]
  309.      * maintained by tzset() typically returns { "GMT", "BST" }. The point of
  310.      * this routine is to actually return "Europe/London" (or rather, the
  311.      * corresponding KTimezone).
  312.      *
  313.      * @return local timezone. If necessary, we will use a series of heuristics
  314.      *         which end by returning UTC. We will never return NULL.
  315.      */
  316.     const KTimezone *local();
  317.  
  318.     /**
  319.      * Returns the given timezone.
  320.      *
  321.      * @param name Name of timezone. Empty is equivalent to UTC.
  322.      * @return named timezone, NULL on error.
  323.      */
  324.     const KTimezone *zone(const QString &name);
  325.  
  326.     typedef QMap<QString, KTimezone *> ZoneMap;
  327.  
  328.     /**
  329.      * Return timezone database.
  330.      * @return known timezones.
  331.      */
  332.     const ZoneMap allZones();
  333.  
  334.     /**
  335.      * Add user-defined timezone to database.
  336.      */
  337.     void add(KTimezone *zone);
  338.  
  339. private:
  340.     KTimezones(const KTimezones&);
  341.     KTimezones& operator=(const KTimezones&);
  342.  
  343.     float convertCoordinate(const QString &coordinate);
  344.  
  345.     QString m_zoneinfoDir;
  346.     ZoneMap *m_zones;
  347.     KTimezone *m_UTC;
  348.     KTimezonesPrivate *d;
  349. };
  350.  
  351. #endif
  352.