Time Zone Components

Time zone components store information about time zones that are used in event/to-do components. All time zones components can be accessed via ICalendar2.TimeZones list. This list contains items that implement ITimeZone interface providing all time zone historical information.

Time Zones Database

There are two types of time zone databases – IANA (Olson) time zones database and Microsoft (Windows or System) time zones database. Some CalDAV clients use IANA time zone IDs (TZID) others use Microsoft TZID. For example iOS and OS X are using IANA TZID while eM Client is using Microsoft TZID.

The IT Hit Collab library contains a database of all IANA time zones and can generate both IANA and Microsoft time zones. It can also return time zone description with all historical info based on either IANA TZID or Microsoft TZID. To get a time zone description based on TZID use the TimeZoneDatabase.GetTimeZone() static method.

Sometimes you may also need to list all time zones, for example when creating a client-side UI. To get a list of all IANA time zones call TimeZoneDatabase.GetIanaTimeZones() method. To get a list of Microsoft time zones use the TimeZoneInfo.GetSystemTimeZones .NET Framework method.

Auto-Generating Time Zones Components

When creating a calendar object the IT Hit Collab library can automatically generate all time zone data for you based on TZIDs specified in your events and to-dos. All you need to do is to specify IANA or Microsoft TZID when creating event/to-do properties. The time zones components will be generated automatically when serializing a calendar object based on the TZIDs found in your object:

LicenseValidator.SetLicense("<?xml ...");
ICalendar2 cal = CalendarFactory.CreateCalendar2();
IEvent evt = cal.Events.CreateComponent();

// SUMMARY property
ICalText summaryProp = cal.CreateProperty<ICalText>();
summaryProp.Text = "Meeting";
evt.Summary = summaryProp;

// DTSTART property
ICalDate startProp = cal.CreateProperty<ICalDate>();
startProp.Value = new Date(newDateTime(2017, 4, 20, 9, 40, 0));
startProp.TimeZoneId = "Africa/Johannesburg";
evt.Start = startProp;

cal.Events.Add(evt);

cal.AutoGenerateTimeZones = true;

vFormatter formatter = new vFormatter();
string strCal = formatter.Serialize(cal);
Console.Write(strCal);

Output:

BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VTIMEZONE
TZID:Africa/Johannesburg
BEGIN:DAYLIGHT
DTSTART:19420920T020000
TZOFFSETFROM:+020000
TZOFFSETTO:+030000
RRULE:FREQ=YEARLY;BYMONTH=9;BYDAY=3SU;UNTIL=19430919T000000Z
TZNAME:Africa/Johannesburg
END:DAYLIGHT
BEGIN:DAYLIGHT
DTSTART:19430321T020000
TZOFFSETFROM:+020000
TZOFFSETTO:+020000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=3SU;UNTIL=19440319T000000Z
TZNAME:Africa/Johannesburg
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
SUMMARY:Meeting
DTSTART;TZID=Africa/Johannesburg:20170420T034000
END:VEVENT
END:VCALENDAR

To disable automatic time zones generation set ICalendar2.AutoGenerateTimeZones to false. If you would like to generate time-zones components at any time before serialization call ICalendar2.GenerateTimeZones() method. This will populate time zones components based on TZIDs found in the calendar object.

Converting Time Zones

In some cases you may need to convert IANA time zone to Microsoft time zone or vise versa. Note that IANA time zone can be mapped to a single Microsoft time zone. But a single Microsoft time zone corresponds to multiple IANA time zones.

To convert IANA to Microsoft time zone use the TimeZoneDatabase.IanaToSystem() static method. 

To convert Microsoft time zone to IANA use the TimeZoneDatabase.SystemToIana() static method. This method returns a list of Microsoft time zones that corresponds to a provided IANA time zone.