src/libical/icaltimezone.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 4 -*- */
   2 /*======================================================================
   3  FILE: icaltimezone.h
   4  CREATOR: Damon Chaplin 15 March 2001
   5
   6
   7  $Id: icaltimezone.h,v 1.14 2008-01-15 23:17:42 dothebart Exp $
   8  $Locker:  $
   9
  10  (C) COPYRIGHT 2001, Damon Chaplin
  11
  12  This program is free software; you can redistribute it and/or modify
  13  it under the terms of either:
  14
  15     The LGPL as published by the Free Software Foundation, version
  16     2.1, available at: http://www.fsf.org/copyleft/lesser.html
  17
  18   Or:
  19
  20     The Mozilla Public License Version 1.0. You may obtain a copy of
  21     the License at http://www.mozilla.org/MPL/
  22
  23
  24 ======================================================================*/
  25 /**
  26  * @file icaltimezone.h
  27  * @brief timezone handling routines
  28  */
  29
  30 #ifndef ICALTIMEZONE_H
  31 #define ICALTIMEZONE_H
  32
  33 #include <stdio.h> /* For FILE* */
  34 #include "icaltime.h"
  35 #include "icalarray.h"
  36 #include "icalcomponent.h"
  37
  38
  39 #ifndef ICALTIMEZONE_DEFINED
  40 #define ICALTIMEZONE_DEFINED
  41 /** @brief An opaque struct representing a timezone.
  42  * We declare this here to avoid a circular dependancy.
  43  */
  44 typedef struct _icaltimezone            icaltimezone;
  45 #endif
  46
  47 /**
  48  * @par Creating/Destroying individual icaltimezones.
  49  */
  50
  51 /** Creates a new icaltimezone. */
  52 icaltimezone *icaltimezone_new                  (void);
  53 icaltimezone *icaltimezone_copy                 (icaltimezone *originalzone);
  54
  55 /** Frees all memory used for the icaltimezone. Set free_struct to free the
  56    icaltimezone struct as well. */
  57 void icaltimezone_free                          (icaltimezone *zone,
  58                                                  int free_struct);
  59
  60 /** Sets the prefix to be used for tzid's generated from system tzdata.
  61     Must be globally unique (such as a domain name owned by the developer
  62     of the calling application), and begin and end with forward slashes.
  63     Do not change or de-allocate the string buffer after calling this.
  64  */
  65 void icaltimezone_set_tzid_prefix(const char *new_prefix);
  66
  67 /**
  68  * @par Accessing timezones.
  69  */
  70
  71 /** Free any builtin timezone information **/
  72 void icaltimezone_free_builtin_timezones(void);
  73
  74 /** Returns the array of builtin icaltimezones. */
  75 icalarray* icaltimezone_get_builtin_timezones   (void);
  76
  77 /** Returns a single builtin timezone, given its Olson city name. */
  78 icaltimezone* icaltimezone_get_builtin_timezone (const char *location);
  79
  80 /** Returns a single builtin timezone, given its offset. */
  81 icaltimezone* icaltimezone_get_builtin_timezone_from_offset     (int offset, const char *tzname);
  82
  83 /** Returns a single builtin timezone, given its TZID. */
  84 icaltimezone* icaltimezone_get_builtin_timezone_from_tzid (const char *tzid);
  85
  86 /** Returns the UTC timezone. */
  87 icaltimezone* icaltimezone_get_utc_timezone     (void);
  88
  89 /** Returns the TZID of a timezone. */
  90 const char*     icaltimezone_get_tzid                   (icaltimezone *zone);
  91
  92 /** Returns the city name of a timezone. */
  93 const char*     icaltimezone_get_location               (icaltimezone *zone);
  94
  95 /** Returns the TZNAME properties used in the latest STANDARD and DAYLIGHT
  96    components. If they are the same it will return just one, e.g. "LMT".
  97    If they are different it will format them like "EST/EDT". Note that this
  98    may also return NULL. */
  99 const char*     icaltimezone_get_tznames                (icaltimezone *zone);
 100
 101 /** Returns the latitude of a builtin timezone. */
 102 double  icaltimezone_get_latitude               (icaltimezone *zone);
 103
 104 /** Returns the longitude of a builtin timezone. */
 105 double  icaltimezone_get_longitude              (icaltimezone *zone);
 106
 107 /** Returns the VTIMEZONE component of a timezone. */
 108 icalcomponent*  icaltimezone_get_component      (icaltimezone *zone);
 109
 110 /** Sets the VTIMEZONE component of an icaltimezone, initializing the tzid,
 111    location & tzname fields. It returns 1 on success or 0 on failure, i.e.
 112    no TZID was found. */
 113 int     icaltimezone_set_component              (icaltimezone *zone,
 114                                                  icalcomponent  *comp);
 115
 116 const char* icaltimezone_get_display_name       (icaltimezone   *zone);
 117
 118 /**
 119  * @par Converting times between timezones.
 120  */
 121
 122 void    icaltimezone_convert_time               (struct icaltimetype *tt,
 123                                                  icaltimezone *from_zone,
 124                                                  icaltimezone *to_zone);
 125
 126
 127 /**
 128  * @par Getting offsets from UTC.
 129  */
 130
 131 /** Calculates the UTC offset of a given local time in the given
 132    timezone.  It is the number of seconds to add to UTC to get local
 133    time.  The is_daylight flag is set to 1 if the time is in
 134    daylight-savings time. */
 135 int icaltimezone_get_utc_offset (icaltimezone *zone,
 136                                  struct icaltimetype *tt,
 137                                  int            *is_daylight);
 138
 139 /** Calculates the UTC offset of a given UTC time in the given
 140    timezone.  It is the number of seconds to add to UTC to get local
 141    time.  The is_daylight flag is set to 1 if the time is in
 142    daylight-savings time. */
 143 int     icaltimezone_get_utc_offset_of_utc_time (icaltimezone *zone,
 144                                                  struct icaltimetype *tt,
 145                                                  int            *is_daylight);
 146
 147
 148
 149 /*
 150  * Handling arrays of timezones. Mainly for internal use.
 151  */
 152 icalarray*  icaltimezone_array_new              (void);
 153
 154 void        icaltimezone_array_append_from_vtimezone (icalarray     *timezones,
 155                                                       icalcomponent *child);
 156 void        icaltimezone_array_free             (icalarray      *timezones);
 157
 158
 159 /*
 160  * @par Handling the default location the timezone files
 161  */
 162
 163 /** Set the directory to look for the zonefiles */
 164 void set_zone_directory(char *path);
 165
 166 /** Free memory dedicated to the zonefile directory */
 167 void free_zone_directory(void);
 168 void icaltimezone_release_zone_tab(void);
 169
 170 /*
 171  * @par Debugging Output.
 172  */
 173
 174 /** Dumps information about changes in the timezone up to and including
 175    max_year. */
 176 int     icaltimezone_dump_changes               (icaltimezone *zone,
 177                                                  int             max_year,
 178                                                  FILE           *fp);
 179
 180 #endif /* ICALTIMEZONE_H */