CalTimezone Type

Specifies a time zone on a calendar collection.

Remarks

The CalDAV CalTimezone type is used to specify the time zone the server should rely on to resolve "date" values and "date with local time" values (i.e., floating time) to "date with UTC time" values. The server will require this information to determine if a calendar component scheduled with "date" values or "date with local time" values overlaps a time range specified in a GetCalendarReport. In the absence of this property, the server may rely on a time zone of its choosing.

Fields

DSTName
String

The customary name for the daylight-savings time zone. This could be used for displaying dates, and there is no restriction to the format. For instance, Eastern Daylight Time may be represented as "EDT", "Eastern Daylight Time (US & Canada)", or any other arbitrary representation.

The following example shows the CalTimezone set to Eastern time.

  CalDAV.Timezone.TimezoneId      = "US-Eastern";
  CalDAV.Timezone.URL             = "http://zones.example.com/tz/America-New_York.ics"

  CalDAV.Timezone.StdName         = "Eastern Standard Time (US & Canada)";
  CalDAV.Timezone.StdStart        = "20071104T020000";
  CalDAV.Timezone.StdOffsetFrom   = "-400";
  CalDAV.Timezone.StdOffsetTo     = "-500";
  CalDAV.Timezone.StdRule         = "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11";

  CalDAV.TimeZone.DSTName         = "Eastern Daylight Time (US & Canada)";
  CalDAV.TimeZone.DSTStart        = "20070311T020000";  
  CalDAV.TimeZone.DSTOffsetFrom   = "-500";
  CalDAV.TimeZone.DSTOffsetTo     = "-400";
  CalDAV.TimeZone.DSTRule         = "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3";

DSTOffsetFrom
String

The UTC offset that is in use when the onset of this time zone observance begins. DSTOffsetFrom is combined with DSTStart to define the effective onset for the daylight-time time zone definition.

DSTStart, DSTOffsetFrom, and DSTOffsetTo are all required to specify the daylight-savings time zone.

The following example shows the CalTimezone set to Eastern time.

  CalDAV.Timezone.TimezoneId      = "US-Eastern";
  CalDAV.Timezone.URL             = "http://zones.example.com/tz/America-New_York.ics"

  CalDAV.Timezone.StdName         = "Eastern Standard Time (US & Canada)";
  CalDAV.Timezone.StdStart        = "20071104T020000";
  CalDAV.Timezone.StdOffsetFrom   = "-400";
  CalDAV.Timezone.StdOffsetTo     = "-500";
  CalDAV.Timezone.StdRule         = "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11";

  CalDAV.TimeZone.DSTName         = "Eastern Daylight Time (US & Canada)";
  CalDAV.TimeZone.DSTStart        = "20070311T020000";  
  CalDAV.TimeZone.DSTOffsetFrom   = "-500";
  CalDAV.TimeZone.DSTOffsetTo     = "-400";
  CalDAV.TimeZone.DSTRule         = "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3";

DSTOffsetTo
String

The UTC offset for daylight savings time, when this observance is in use.

DSTStart, DSTOffsetFrom, and DSTOffsetTo are all required to specify the daylight-savings time zone.

The following example shows the CalTimezone set to Eastern time.

  CalDAV.Timezone.TimezoneId      = "US-Eastern";
  CalDAV.Timezone.URL             = "http://zones.example.com/tz/America-New_York.ics"

  CalDAV.Timezone.StdName         = "Eastern Standard Time (US & Canada)";
  CalDAV.Timezone.StdStart        = "20071104T020000";
  CalDAV.Timezone.StdOffsetFrom   = "-400";
  CalDAV.Timezone.StdOffsetTo     = "-500";
  CalDAV.Timezone.StdRule         = "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11";

  CalDAV.TimeZone.DSTName         = "Eastern Daylight Time (US & Canada)";
  CalDAV.TimeZone.DSTStart        = "20070311T020000";  
  CalDAV.TimeZone.DSTOffsetFrom   = "-500";
  CalDAV.TimeZone.DSTOffsetTo     = "-400";
  CalDAV.TimeZone.DSTRule         = "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3";

DSTRule
String

This field defines the recurrence rule for the onset of this daylight savings time observance. Some specific requirements for the usage of DSTRule for this purpose include:


FREQ	Frequency of the time zone onset. (Almost always "YEARLY")
BYMONTH	The month of the time zone onset.
BYDAY	The day of the time zone onset. Formatted as a number and a two-character day. "BYDAY=3SU" means the 3rd Sunday of the month. "BYDAY=-1SU" is the last Sunday of the month.
UNTIL	If the observance is known to have an effective end date, the "UNTIL" recurrence rule parameter MUST be used to specify the last valid onset of this observance (i.e., the UNTIL DATE-TIME will be equal to the last instance generated by the recurrence pattern). It MUST be specified in UTC time.

Note that the DSTStart and DSTOffsetFrom fields must be used when generating the onset DATE-TIME values (instances) from the DSTRule

For instance, in the USA Eastern Daylight time before 2007 started on the first Sunday of April. In 2007 Daylight time was changed to begin on the 2nd Sunday in March. Therefore, the UNTIL option should indicate the LAST time this rule will be observed. (2am on April 2nd, 2006). Such a time zone declaration would look like this:

	CalDAV.time zone.DSTName = "EDT"
	CalDAV.time zone.DSTStart = "19870405T020000"
	CalDAV.time zone.DSTOffsetFrom = "-500"
	CalDAV.time zone.DSTOffsetTo = "-400"
	CalDAV.time zone.DSTRule = "FREQ=YEARLY;BYMONTH=4;BYDAY=1SU;UNTIL=20060402T070000Z"

DSTStart
String

The effective onset date and local time for the daylight-time time zone definition. The date and time MUST be specified as a date with a local time value in the format "YYYYMMDDThhmmss", where "T" indicates the break between date and time.

DSTStart, DSTOffsetFrom, and DSTOffsetTo are all required to specify the daylight-savings time zone.

The following example shows the CalTimezone set to Eastern time.

  CalDAV.Timezone.TimezoneId      = "US-Eastern";
  CalDAV.Timezone.URL             = "http://zones.example.com/tz/America-New_York.ics"

  CalDAV.Timezone.StdName         = "Eastern Standard Time (US & Canada)";
  CalDAV.Timezone.StdStart        = "20071104T020000";
  CalDAV.Timezone.StdOffsetFrom   = "-400";
  CalDAV.Timezone.StdOffsetTo     = "-500";
  CalDAV.Timezone.StdRule         = "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11";

  CalDAV.TimeZone.DSTName         = "Eastern Daylight Time (US & Canada)";
  CalDAV.TimeZone.DSTStart        = "20070311T020000";  
  CalDAV.TimeZone.DSTOffsetFrom   = "-500";
  CalDAV.TimeZone.DSTOffsetTo     = "-400";
  CalDAV.TimeZone.DSTRule         = "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3";

LastModified
String

This optional field is a UTC value that specifies the date and time that this time zone definition was last updated.

StdName
String

The customary name for the standard time zone. This could be used for displaying dates, and there is no restriction to the format. For instance, Eastern Standard Time may be represented as "EST", "Eastern Standard Time (US & Canada)", or any other arbitrary representation.

The following example shows the CalTimezone set to Eastern time.

  CalDAV.Timezone.TimezoneId      = "US-Eastern";
  CalDAV.Timezone.URL             = "http://zones.example.com/tz/America-New_York.ics"

  CalDAV.Timezone.StdName         = "Eastern Standard Time (US & Canada)";
  CalDAV.Timezone.StdStart        = "20071104T020000";
  CalDAV.Timezone.StdOffsetFrom   = "-400";
  CalDAV.Timezone.StdOffsetTo     = "-500";
  CalDAV.Timezone.StdRule         = "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11";

  CalDAV.TimeZone.DSTName         = "Eastern Daylight Time (US & Canada)";
  CalDAV.TimeZone.DSTStart        = "20070311T020000";  
  CalDAV.TimeZone.DSTOffsetFrom   = "-500";
  CalDAV.TimeZone.DSTOffsetTo     = "-400";
  CalDAV.TimeZone.DSTRule         = "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3";

StdOffsetFrom
String

The UTC offset that is in use when the onset of this time zone observance begins. StdOffsetFrom is combined with StdStart to define the effective onset for the standard-time time zone definition.

StdStart, StdOffsetFrom, and StdOffsetTo are all required to specify the standard-time time zone.

The following example shows the CalTimezone set to Eastern time.

  CalDAV.Timezone.TimezoneId      = "US-Eastern";
  CalDAV.Timezone.URL             = "http://zones.example.com/tz/America-New_York.ics"

  CalDAV.Timezone.StdName         = "Eastern Standard Time (US & Canada)";
  CalDAV.Timezone.StdStart        = "20071104T020000";
  CalDAV.Timezone.StdOffsetFrom   = "-400";
  CalDAV.Timezone.StdOffsetTo     = "-500";
  CalDAV.Timezone.StdRule         = "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11";

  CalDAV.TimeZone.DSTName         = "Eastern Daylight Time (US & Canada)";
  CalDAV.TimeZone.DSTStart        = "20070311T020000";  
  CalDAV.TimeZone.DSTOffsetFrom   = "-500";
  CalDAV.TimeZone.DSTOffsetTo     = "-400";
  CalDAV.TimeZone.DSTRule         = "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3";

StdOffsetTo
String

The UTC offset for standard time, when this observance is in use.

StdStart, StdOffsetFrom, and StdOffsetTo are all required to specify the standard-time time zone.

The following example shows the CalTimezone set to Eastern time.

  CalDAV.Timezone.TimezoneId      = "US-Eastern";
  CalDAV.Timezone.URL             = "http://zones.example.com/tz/America-New_York.ics"

  CalDAV.Timezone.StdName         = "Eastern Standard Time (US & Canada)";
  CalDAV.Timezone.StdStart        = "20071104T020000";
  CalDAV.Timezone.StdOffsetFrom   = "-400";
  CalDAV.Timezone.StdOffsetTo     = "-500";
  CalDAV.Timezone.StdRule         = "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11";

  CalDAV.TimeZone.DSTName         = "Eastern Daylight Time (US & Canada)";
  CalDAV.TimeZone.DSTStart        = "20070311T020000";  
  CalDAV.TimeZone.DSTOffsetFrom   = "-500";
  CalDAV.TimeZone.DSTOffsetTo     = "-400";
  CalDAV.TimeZone.DSTRule         = "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3";

StdRule
String

This field defines the recurrence rule for the onset of this standard time observance. Some specific requirements for the usage of DSTRule for this purpose include:


FREQ	Frequency of the time zone onset. (Almost always "YEARLY")
BYMONTH	The month of the time zone onset.
BYDAY	The day of the time zone onset. Formatted as a number and a two-character day. "BYDAY=3SU" means the 3rd Sunday of the month. "BYDAY=-1SU" is the last Sunday of the month.
UNTIL	If the observance is known to have an effective end date, the "UNTIL" recurrence rule parameter MUST be used to specify the last valid onset of this observance (i.e., the UNTIL DATE-TIME will be equal to the last instance generated by the recurrence pattern). It MUST be specified in UTC time.

Note that the StdStart and StdOffsetFrom fields must be used when generating the onset DATE-TIME values (instances) from the StdRule

For instance, in the USA Eastern Standard time before 2007 started on the last Sunday of October. In 2007 Standard time was changed to begin on the 1st Sunday in November. Therefore, the UNTIL option should indicate the LAST time this rule will be observed. (2am on October 29th, 2006). Such a time zone declaration would look like this:

	CalDAV.time zone.StdName = "EST"
	CalDAV.time zone.StdStart = "19671029T020000"
	CalDAV.time zone.StdOffsetFrom = "-400"
	CalDAV.time zone.StdOffsetTo = "-500"
	CalDAV.time zone.StdRule = "FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU;UNTIL=20061029T060000Z"

StdStart
String

The effective onset date and local time for the standard-time time zone definition. The date and time MUST be specified as a date with a local time value. in the format "YYYYMMDDThhmmss", where "T" indicates the break between date and time.

StdStart, StdOffsetFrom, and StdOffsetTo are all required to specify the standard-time time zone.

The following example shows the CalTimezone set to Eastern time.

  CalDAV.Timezone.TimezoneId      = "US-Eastern";
  CalDAV.Timezone.URL             = "http://zones.example.com/tz/America-New_York.ics"

  CalDAV.Timezone.StdName         = "Eastern Standard Time (US & Canada)";
  CalDAV.Timezone.StdStart        = "20071104T020000";
  CalDAV.Timezone.StdOffsetFrom   = "-400";
  CalDAV.Timezone.StdOffsetTo     = "-500";
  CalDAV.Timezone.StdRule         = "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11";

  CalDAV.TimeZone.DSTName         = "Eastern Daylight Time (US & Canada)";
  CalDAV.TimeZone.DSTStart        = "20070311T020000";  
  CalDAV.TimeZone.DSTOffsetFrom   = "-500";
  CalDAV.TimeZone.DSTOffsetTo     = "-400";
  CalDAV.TimeZone.DSTRule         = "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3";

TimezoneId
String

This field specifies a text value that uniquely identifies this CalTimezone calendar component.

Note: This document does not define a naming convention for time zone identifiers. Implementers may want to use the naming conventions defined in existing time zone specifications such as the public-domain TZ database [TZDB].

This field is required. If it is not present, no time zone information will be generated inside the MakeCalendar request.

URL
String

Optionally points to a published time zone definition. If set, this field should refer to a resource that is accessible by anyone who might need to interpret the object. This should not normally be a "file" URL or other URL that is not widely accessible.

Constructors

public CalTimezone();