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 */ 181