Libical API Documentation 3.0

Macros | Typedefs | Functions
icaltimezone.h File Reference

Timezone handling routines. More...

Go to the source code of this file.

## Typedefs
typedef struct _icaltimezone | icaltimezone
| An opaque struct representing a timezone. We declare this here to avoid a circular dependancy.

## Functions
void | free_zone_directory (void)
void | icaltimezone_array_append_from_vtimezone (icalarray *timezones, icalcomponent *child)
void | icaltimezone_array_free (icalarray *timezones)
icalarray * | icaltimezone_array_new (void)
void | icaltimezone_convert_time (struct icaltimetype *tt, icaltimezone *from_zone, icaltimezone *to_zone)
icaltimezone * | icaltimezone_copy (icaltimezone *originalzone)
int | icaltimezone_dump_changes (icaltimezone *zone, int max_year, FILE *fp)
| Outputs a list of timezone changes for the given timezone to the given file, up to the maximum year given. More...
void | icaltimezone_expand_vtimezone (icalcomponent *comp, int end_year, icalarray *changes)
void | icaltimezone_free (icaltimezone *zone, int free_struct)
| Frees all memory used for the icaltimezone. More...
void | icaltimezone_free_builtin_timezones (void)
| Releases builtin timezone memory.
icaltimezone * | icaltimezone_get_builtin_timezone (const char *location)
| Returns a single builtin timezone, given its Olson city name.
icaltimezone * | icaltimezone_get_builtin_timezone_from_offset (int offset, const char *tzname)
| Returns a single builtin timezone, given its offset from UTC.
icaltimezone * | icaltimezone_get_builtin_timezone_from_tzid (const char *tzid)
| Returns a single builtin timezone, given its TZID.
icalarray * | icaltimezone_get_builtin_timezones (void)
| Returns an icalarray of icaltimezone structs, one for each builtin timezone. More...
int | icaltimezone_get_builtin_tzdata (void)
icalcomponent * | icaltimezone_get_component (icaltimezone *zone)
| Returns the VTIMEZONE component of a timezone.
const char * | icaltimezone_get_display_name (icaltimezone *zone)
| Returns the timezone name to display to the user. More...
double | icaltimezone_get_latitude (icaltimezone *zone)
| Returns the latitude of a builtin timezone.
const char * | icaltimezone_get_location (icaltimezone *zone)
char * | icaltimezone_get_location_from_vtimezone (icalcomponent *component)
| Gets the LOCATION or X-LIC-LOCATION property from a VTIMEZONE.
double | icaltimezone_get_longitude (icaltimezone *zone)
| Returns the longitude of a builtin timezone.
const char * | icaltimezone_get_tzid (icaltimezone *zone)
const char * | icaltimezone_get_tznames (icaltimezone *zone)
char * | icaltimezone_get_tznames_from_vtimezone (icalcomponent *component)
| Gets the TZNAMEs used for the last STANDARD & DAYLIGHT components in a VTIMEZONE. More...
int | icaltimezone_get_utc_offset (icaltimezone *zone, struct icaltimetype *tt, int *is_daylight)
| Calculates the UTC offset of a given local time in the given timezone. More...
int | icaltimezone_get_utc_offset_of_utc_time (icaltimezone *zone, struct icaltimetype *tt, int *is_daylight)
| Calculates the UTC offset of a given UTC time in the given timezone. More...
icaltimezone * | icaltimezone_get_utc_timezone (void)
| Returns the UTC timezone.
icaltimezone * | icaltimezone_new (void)
| Creates a new icaltimezone.
void | icaltimezone_release_zone_tab (void)
void | icaltimezone_set_builtin_tzdata (int set)
int | icaltimezone_set_component (icaltimezone *zone, icalcomponent *comp)
| Sets the VTIMEZONE component of an icaltimezone, initializing the tzid, location & tzname fields. More...
void | icaltimezone_set_tzid_prefix (const char *new_prefix)
void | icaltimezone_truncate_vtimezone (icalcomponent *vtz, icaltimetype start, icaltimetype end, int ms_compatible)
const char * | icaltimezone_tzid_prefix (void)
void | set_zone_directory (const char *path)

## Detailed Description

Timezone handling routines.

## Function Documentation

## ◆ free_zone_directory()

void free_zone_directory | ( | void |  | ) |

Frees the memory dedicated to the zonefile directory

## ◆ icaltimezone_dump_changes()

int icaltimezone_dump_changes | ( | icaltimezone * | zone,
|  | int | max_year,
|  | FILE * | fp
| ) |  |

Outputs a list of timezone changes for the given timezone to the given file, up to the maximum year given.

We compare this output with the output from 'vzic –dump-changes' to make sure that we are consistent. (vzic is the Olson timezone database to VTIMEZONE converter.)

The output format is:

     Zone-Name [tab] Date [tab] Time [tab] UTC-Offset

The Date and Time fields specify the time change in UTC.

The UTC Offset is for local (wall-clock) time. It is the amount of time to add to UTC to get local time.

## ◆ icaltimezone_free()

void icaltimezone_free | ( | icaltimezone * | zone,
|  | int | free_struct
| ) |  |

Frees all memory used for the icaltimezone.

Parameters

  zone | The icaltimezone to be freed
  free_struct | Whether to free the icaltimezone struct as well

## ◆ icaltimezone_get_builtin_timezones()

icalarray * icaltimezone_get_builtin_timezones | ( | void |  | ) |

Returns an icalarray of icaltimezone structs, one for each builtin timezone.

This will load and parse the zones.tab file to get the timezone names and their coordinates. It will not load the VTIMEZONE data for any timezones.

## ◆ icaltimezone_get_display_name()

const char * icaltimezone_get_display_name | ( | icaltimezone * | zone | ) |

Returns the timezone name to display to the user.

We prefer to use the Olson city name, but fall back on the TZNAME, or finally the TZID. We don't want to use "" as it may be wrongly interpreted as a floating time. Do not free the returned string.

## ◆ icaltimezone_get_location()

const char * icaltimezone_get_location | ( | icaltimezone * | zone | ) |

Returns the city name of a timezone.

## ◆ icaltimezone_get_tzid()

const char * icaltimezone_get_tzid | ( | icaltimezone * | zone | ) |

Returns the TZID of a timezone.

## ◆ icaltimezone_get_tznames()

const char * icaltimezone_get_tznames | ( | icaltimezone * | zone | ) |

Returns the TZNAME properties used in the latest STANDARD and DAYLIGHT components. If they are the same it will return just one, e.g. "LMT". If they are different it will format them like "EST/EDT". Note that this may also return NULL.

## ◆ icaltimezone_get_tznames_from_vtimezone()

char * icaltimezone_get_tznames_from_vtimezone | ( | icalcomponent * | component | ) |

Gets the TZNAMEs used for the last STANDARD & DAYLIGHT components in a VTIMEZONE.

If both STANDARD and DAYLIGHT components use the same TZNAME, it returns that. If they use different TZNAMEs, it formats them like "EST/EDT". The returned string should be freed by the caller.

## ◆ icaltimezone_get_utc_offset()

int icaltimezone_get_utc_offset | ( | icaltimezone * | zone,
|  | struct icaltimetype * | tt,
|  | int * | is_daylight
| ) |  |

Calculates the UTC offset of a given local time in the given timezone.

It is the number of seconds to add to UTC to get local time. The is_daylight flag is set to 1 if the time is in daylight-savings time.

## ◆ icaltimezone_get_utc_offset_of_utc_time()

int icaltimezone_get_utc_offset_of_utc_time | ( | icaltimezone * | zone,
|  | struct icaltimetype * | tt,
|  | int * | is_daylight
| ) |  |

Calculates the UTC offset of a given UTC time in the given timezone.

It is the number of seconds to add to UTC to get local time. The `is_daylight` flag is set to 1 if the time is in daylight-savings time.

## ◆ icaltimezone_set_component()

int icaltimezone_set_component | ( | icaltimezone * | zone,
|  | icalcomponent * | comp
| ) |  |

Sets the VTIMEZONE component of an icaltimezone, initializing the tzid, location & tzname fields.

Returns
  1 on success or 0 on failure, i.e. no TZID was found.

## ◆ icaltimezone_set_tzid_prefix()

void icaltimezone_set_tzid_prefix | ( | const char * | new_prefix | ) |

Sets the prefix to be used for tzid's generated from system tzdata. Must be globally unique (such as a domain name owned by the developer of the calling application), and begin and end with forward slashes. Do not change or de-allocate the string buffer after calling this.

## ◆ set_zone_directory()

void set_zone_directory | ( | const char * | path | ) |

Sets the directory to look for the zonefiles