icaltimezone.h File Reference

Timezone handling routines. More...

Go to the source code of this file.

Functions
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 (const icaltimezone *originalzone)
bool	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.
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.
void	icaltimezone_free_builtin_timezones (void)
	Releases builtin timezone memory.
void	icaltimezone_free_zone_directory (void)
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.
bool	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.
double	icaltimezone_get_latitude (const icaltimezone *zone)
	Returns the latitude of a builtin timezone.
const char *	icaltimezone_get_location (const 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 (const icaltimezone *zone)
	Returns the longitude of a builtin timezone.
const char *	icaltimezone_get_system_zone_directory (void)
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.
int	icaltimezone_get_utc_offset (icaltimezone *zone, const struct icaltimetype *tt, int *is_daylight)
	Calculates the UTC offset of a given local time in the given timezone.
int	icaltimezone_get_utc_offset_of_utc_time (icaltimezone *zone, const struct icaltimetype *tt, int *is_daylight)
	Calculates the UTC offset of a given UTC time in the given timezone.
icaltimezone *	icaltimezone_get_utc_timezone (void)
	Returns the UTC timezone.
const char *	icaltimezone_get_zone_directory (void)
icaltimezone *	icaltimezone_new (void)
	Creates a new icaltimezone.
void	icaltimezone_set_builtin_tzdata (bool set)
bool	icaltimezone_set_component (icaltimezone *zone, icalcomponent *comp)
	Sets the VTIMEZONE component of an icaltimezone, initializing the tzid, location & tzname fields.
void	icaltimezone_set_system_zone_directory (const char *zonepath)
void	icaltimezone_set_tzid_prefix (const char *new_prefix)
void	icaltimezone_set_zone_directory (const char *path)
void	icaltimezone_truncate_vtimezone (icalcomponent *vtz, icaltimetype start, icaltimetype end, bool ms_compatible)
const char *	icaltimezone_tzid_prefix (void)

Detailed Description

Timezone handling routines.

Function Documentation

icaltimezone_convert_time()

void icaltimezone_convert_time	(	struct icaltimetype *	tt,
		icaltimezone *	from_zone,
		icaltimezone *	to_zone )

Rotate a time from one timezone to another.

Parameters

tt	is a the icaltimetype to rotate. If tt represents a date (ie. there is no associated time) then no conversion is performed.
from_zone	is the timezone to rotate from. Any timezone specified inside the icaltimetype is ignored. If from_zone is NULL then no conversion is performed.
to_zone	is the timezone to rotate to. If to_zone is NULL then the time is rotated to UTC.

icaltimezone_dump_changes()

bool 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_free_zone_directory()

void icaltimezone_free_zone_directory

(

void

)

Frees the memory dedicated to the zonefile directory

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

(

const icaltimezone *

zone

)

Returns the city name of a timezone.

icaltimezone_get_system_zone_directory()

const char * icaltimezone_get_system_zone_directory

(

void

)

Returns the fullpath to the system zoneinfo directory (where zone.tab lives). The returned value points to static memory inside the library and should not try to be freed.

If the TZDIR variable appears in the environment, it will be searched first for zone.tab. If zone.tab is not located in TZDIR (or if TZDIR is not in the environment), then a list of well-known paths where the system zone.tab typically is installed is searched.

Since

4.0 previously known as icaltzutil_get_zone_directory

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,
		const 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 (true) 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,
		const 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 (true) if the time is in daylight-savings time.

icaltimezone_get_zone_directory()

const char * icaltimezone_get_zone_directory

(

void

)

Gets the directory to look for the zonefiles, either system or builtin

icaltimezone_set_component()

bool icaltimezone_set_component	(	icaltimezone *	zone,
		icalcomponent *	comp )

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

Returns

true on success or false on failure, i.e. no TZID was found.

icaltimezone_set_system_zone_directory()

void icaltimezone_set_system_zone_directory

(

const char *

zonepath

)

Sets the fullpath to the system zoneinfo directory (zone.tab must reside in there).

Parameters

zonepath

const character string containing the fullpath to the zoneinfo directory.

The internal zoneinfo path can be cleared if zonepath is empty or NULL.

Since

4.0 previously known as icaltzutil_set_zone_directory

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. The string must be less than 256 chars long.

No error or sanity checking is performed in this function; the caller is entirely responsible for using a proper tzid string.

Do not change or de-allocate the string buffer after calling this.

Parameters

new_prefix

a string (properly formatted and less then 256 characters long) representing the tzid for the system tzdata. If not specified, the library default "/freeassociation.sourceforge.net/" is used.

icaltimezone_set_zone_directory()

void icaltimezone_set_zone_directory

(

const char *

path

)

Sets the directory to look for the zonefiles, either system or builting

icaltimezone_tzid_prefix()

const char * icaltimezone_tzid_prefix

(

void

)

Returns the current setting of the tzid prefix.