Libical API Documentation  3.0
Data Structures | Macros | Typedefs | Functions | Variables
icaltimezone.c File Reference

implementation of timezone handling routines More...

Data Structures

struct  _icaltimezonechange
 

Macros

#define BUILTIN_TZID_PREFIX   "/freeassociation.sourceforge.net/"
 
#define BUILTIN_TZID_PREFIX_LEN   256
 
#define ICALTIMEZONE_EXTRA_COVERAGE   5
 
#define ICALTIMEZONE_MAX_YEAR   2037
 
#define ZONEINFO_DIRECTORY   PACKAGE_DATA_DIR "/zoneinfo"
 
#define ZONES_TAB_FILENAME   "zones.tab"
 

Typedefs

typedef struct _icaltimezonechange icaltimezonechange
 

Functions

static int fetch_lat_long_from_string (const char *str, int *latitude_degrees, int *latitude_minutes, int *latitude_seconds, int *longitude_degrees, int *longitude_minutes, int *longitude_seconds, char *location)
 
static void format_utc_offset (int utc_offset, char *buffer, size_t buffer_size)
 
void free_zone_directory (void)
 
static int get_offset (icaltimezone *zone)
 
static const char * get_zone_directory (void)
 
static void icaltimezone_adjust_change (icaltimezonechange *tt, int days, int hours, int minutes, int seconds)
 
void icaltimezone_array_append_from_vtimezone (icalarray *timezones, icalcomponent *child)
 
void icaltimezone_array_free (icalarray *timezones)
 
icalarrayicaltimezone_array_new (void)
 
static void icaltimezone_builtin_lock (void)
 
static void icaltimezone_builtin_unlock (void)
 
static void icaltimezone_changes_lock (void)
 
static void icaltimezone_changes_unlock (void)
 
static int icaltimezone_compare_change_fn (const void *elem1, const void *elem2)
 
void icaltimezone_convert_time (struct icaltimetype *tt, icaltimezone *from_zone, icaltimezone *to_zone)
 
icaltimezoneicaltimezone_copy (icaltimezone *originalzone)
 
int icaltimezone_dump_changes (icaltimezone *zone, int max_year, FILE *fp)
 
static void icaltimezone_ensure_coverage (icaltimezone *zone, int end_year)
 
static void icaltimezone_expand_changes (icaltimezone *zone, int end_year)
 
void icaltimezone_expand_vtimezone (icalcomponent *comp, int end_year, icalarray *changes)
 
static size_t icaltimezone_find_nearby_change (icaltimezone *zone, icaltimezonechange *change)
 
void icaltimezone_free (icaltimezone *zone, int free_struct)
 
void icaltimezone_free_builtin_timezones (void)
 
icaltimezoneicaltimezone_get_builtin_timezone (const char *location)
 
icaltimezoneicaltimezone_get_builtin_timezone_from_offset (int offset, const char *tzname)
 
icaltimezoneicaltimezone_get_builtin_timezone_from_tzid (const char *tzid)
 
icalarrayicaltimezone_get_builtin_timezones (void)
 
int icaltimezone_get_builtin_tzdata (void)
 
icalcomponenticaltimezone_get_component (icaltimezone *zone)
 
const char * icaltimezone_get_display_name (icaltimezone *zone)
 
double icaltimezone_get_latitude (icaltimezone *zone)
 
const char * icaltimezone_get_location (icaltimezone *zone)
 
char * icaltimezone_get_location_from_vtimezone (icalcomponent *component)
 
double icaltimezone_get_longitude (icaltimezone *zone)
 
const char * icaltimezone_get_tzid (icaltimezone *zone)
 
const char * icaltimezone_get_tznames (icaltimezone *zone)
 
char * icaltimezone_get_tznames_from_vtimezone (icalcomponent *component)
 
int icaltimezone_get_utc_offset (icaltimezone *zone, struct icaltimetype *tt, int *is_daylight)
 
int icaltimezone_get_utc_offset_of_utc_time (icaltimezone *zone, struct icaltimetype *tt, int *is_daylight)
 
icaltimezoneicaltimezone_get_utc_timezone (void)
 
static int icaltimezone_get_vtimezone_properties (icaltimezone *zone, icalcomponent *component)
 
static void icaltimezone_init (icaltimezone *zone)
 
static void icaltimezone_init_builtin_timezones (void)
 
static void icaltimezone_load_builtin_timezone (icaltimezone *zone)
 
static char * icaltimezone_load_get_line_fn (char *s, size_t size, void *data)
 
icaltimezoneicaltimezone_new (void)
 
static void icaltimezone_parse_zone_tab (void)
 
void icaltimezone_release_zone_tab (void)
 
static void icaltimezone_reset (icaltimezone *zone)
 
void icaltimezone_set_builtin_tzdata (int set)
 
int icaltimezone_set_component (icaltimezone *zone, icalcomponent *comp)
 
void icaltimezone_set_tzid_prefix (const char *new_prefix)
 
const char * icaltimezone_tzid_prefix (void)
 
static int parse_coord (char *coord, int len, int *degrees, int *minutes, int *seconds)
 
void set_zone_directory (const char *path)
 
static struct icaltimetype tm_to_icaltimetype (struct tm *tm)
 

Variables

static icalarraybuiltin_timezones = NULL
 
static char ical_tzid_prefix [256]
 
static int use_builtin_tzdata = 0
 
static icaltimezone utc_timezone = { 0, 0, 0, 0, 0, 0, 0, 0, 0 }
 
static char * zone_files_directory = NULL
 

Detailed Description

implementation of timezone handling routines

Macro Definition Documentation

◆ BUILTIN_TZID_PREFIX_LEN

#define BUILTIN_TZID_PREFIX_LEN   256

The prefix we use to uniquely identify TZIDs. It must begin and end with forward slashes.

◆ ICALTIMEZONE_EXTRA_COVERAGE

#define ICALTIMEZONE_EXTRA_COVERAGE   5

This is the number of years of extra coverage we do when expanding the timezone changes.

◆ ICALTIMEZONE_MAX_YEAR

#define ICALTIMEZONE_MAX_YEAR   2037

This is the maximum year we will expand to, since 32-bit time_t values only go up to the start of 2038.

◆ ZONEINFO_DIRECTORY

#define ZONEINFO_DIRECTORY   PACKAGE_DATA_DIR "/zoneinfo"

This is the toplevel directory where the timezone data is installed in.

◆ ZONES_TAB_FILENAME

#define ZONES_TAB_FILENAME   "zones.tab"

This is the filename of the file containing the city names and coordinates of all the builtin timezones.

Function Documentation

◆ format_utc_offset()

static void format_utc_offset ( int  utc_offset,
char *  buffer,
size_t  buffer_size 
)
static

This formats a UTC offset as "+HHMM" or "+HHMMSS". buffer should have space for 8 characters.

◆ free_zone_directory()

void free_zone_directory ( void  )

Free memory dedicated to the zonefile directory

◆ icaltimezone_adjust_change()

static void icaltimezone_adjust_change ( icaltimezonechange tt,
int  days,
int  hours,
int  minutes,
int  seconds 
)
static

Adds (or subtracts) a time from a icaltimezonechange. NOTE: This function is exactly the same as icaltime_adjust() except for the type of the first parameter.

◆ icaltimezone_compare_change_fn()

static int icaltimezone_compare_change_fn ( const void *  elem1,
const void *  elem2 
)
static

A function to compare 2 icaltimezonechange elements, used for qsort().

◆ icaltimezone_convert_time()

void icaltimezone_convert_time ( struct icaltimetype tt,
icaltimezone from_zone,
icaltimezone to_zone 
)
Converting times between timezones.

◆ icaltimezone_dump_changes()

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

This 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_find_nearby_change()

static size_t icaltimezone_find_nearby_change ( icaltimezone zone,
icaltimezonechange change 
)
static

Returns the index of a timezone change which is close to the time given in change.

◆ icaltimezone_free()

void icaltimezone_free ( icaltimezone zone,
int  free_struct 
)

Frees all memory used for the icaltimezone.

◆ icaltimezone_free_builtin_timezones()

void icaltimezone_free_builtin_timezones ( void  )

Release builtin timezone memory

◆ icaltimezone_get_builtin_timezone()

icaltimezone* icaltimezone_get_builtin_timezone ( const char *  location)

Returns a single builtin timezone, given its Olson city name.

◆ icaltimezone_get_builtin_timezone_from_offset()

icaltimezone* icaltimezone_get_builtin_timezone_from_offset ( int  offset,
const char *  tzname 
)

Returns a single builtin timezone, given its offset from UTC

◆ icaltimezone_get_builtin_timezone_from_tzid()

icaltimezone* icaltimezone_get_builtin_timezone_from_tzid ( const char *  tzid)

Returns a single builtin timezone, given its TZID.

◆ 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_component()

icalcomponent* icaltimezone_get_component ( icaltimezone zone)

Returns the VTIMEZONE component of a timezone.

◆ icaltimezone_get_latitude()

double icaltimezone_get_latitude ( icaltimezone zone)

Returns the latitude of a builtin timezone.

◆ icaltimezone_get_location()

const char* icaltimezone_get_location ( icaltimezone zone)

Returns the city name of a timezone.

◆ icaltimezone_get_location_from_vtimezone()

char* icaltimezone_get_location_from_vtimezone ( icalcomponent component)

Gets the LOCATION or X-LIC-LOCATION property from a VTIMEZONE.

◆ icaltimezone_get_longitude()

double icaltimezone_get_longitude ( icaltimezone zone)

Returns the longitude of a builtin 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 
)
Getting offsets from UTC. 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_get_utc_timezone()

icaltimezone* icaltimezone_get_utc_timezone ( void  )

Returns the special UTC timezone.

◆ icaltimezone_get_vtimezone_properties()

static int icaltimezone_get_vtimezone_properties ( icaltimezone zone,
icalcomponent component 
)
static

Gets the TZID, LOCATION/X-LIC-LOCATION, and TZNAME properties from the VTIMEZONE component and places them in the icaltimezone. It returns 1 on success, or 0 if the TZID can't be found.

Gets the TZID, LOCATION/X-LIC-LOCATION and TZNAME properties of the VTIMEZONE component and stores them in the icaltimezone. It returns 1 on success, or 0 if the TZID can't be found. Note that it expects the zone to be initialized or reset - it doesn't free any old values.

◆ icaltimezone_init()

static void icaltimezone_init ( icaltimezone zone)
static

Initializes an icaltimezone.

◆ icaltimezone_init_builtin_timezones()

static void icaltimezone_init_builtin_timezones ( void  )
static

This initializes the builtin timezone data, i.e. the builtin_timezones array and the special UTC timezone. It should be called before any code that uses the timezone functions.

◆ icaltimezone_load_builtin_timezone()

static void icaltimezone_load_builtin_timezone ( icaltimezone zone)
static

Loads the builtin VTIMEZONE data for the given timezone.

◆ icaltimezone_load_get_line_fn()

static char * icaltimezone_load_get_line_fn ( char *  s,
size_t  size,
void *  data 
)
static

Callback used from icalparser_parse()

◆ icaltimezone_new()

icaltimezone* icaltimezone_new ( void  )

Creates a new icaltimezone.

◆ icaltimezone_parse_zone_tab()

static void icaltimezone_parse_zone_tab ( void  )
static

This parses the zones.tab file containing the names and locations of the builtin timezones. It creates the builtin_timezones array which is an icalarray of icaltimezone structs. It only fills in the location, latitude and longtude fields; the rest are left blank. The VTIMEZONE component is loaded later if it is needed. The timezones in the zones.tab file are sorted by their name, which is useful for binary searches.

◆ icaltimezone_reset()

static void icaltimezone_reset ( icaltimezone zone)
static

Resets the icaltimezone to the initial state, freeing most of the fields.

◆ icaltimezone_set_component()

int icaltimezone_set_component ( icaltimezone zone,
icalcomponent comp 
)

Sets the VTIMEZONE component of an icaltimezone, initializing the tzid, location & tzname fields. It 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)

Set the directory to look for the zonefiles

Variable Documentation

◆ builtin_timezones

icalarray* builtin_timezones = NULL
static

An array of icaltimezones for the builtin timezones.

◆ utc_timezone

icaltimezone utc_timezone = { 0, 0, 0, 0, 0, 0, 0, 0, 0 }
static

This is the special UTC timezone, which isn't in builtin_timezones.