Within the iCalendar specification, components are a collection of properties that define calendaring and scheduling information. Each iCalendar file contains one or more core iCalendar objects which, in turn, must contain at least one of the following components.
iCalendar components are represented in qCal by descendants of the qCal_Component class.
Component Name: VEVENT
The event component is simply a collection of properties that describe an event within the core iCalendar object. An event is defined as a scheduled amount of time on a calendar. Some events contain an alarm component, which serves as a reminder to the event's attendees that it is coming up. An event can be either a one-time occurrence, or it can recur for several weeks, months, years, even indefinitely. For instance, in a calendar, there could be a scheduled dentist appointment, which would likely be a one-time event. Then there might be your birthday, which will recur every year on a certain day, indefinitely.
A "VEVENT" calendar component is a grouping of component properties, and possibly including "VALARM" calendar components, that represents a scheduled amount of time on a calendar. For example, it can be an activity; such as a one-hour long, department meeting from 8:00 AM to 9:00 AM, tomorrow. Generally, an event will take up time on an individual calendar. Hence, the event will appear as an opaque interval in a search for busy time. Alternately, the event can have its Time Transparency set to "TRANSPARENT" in order to prevent blocking of the event in searches for busy time.
The "VEVENT" is also the calendar component used to specify an anniversary or daily reminder within a calendar. These events have a DATE value type for the "DTSTART" property instead of the default data type of DATE-TIME. If such a "VEVENT" has a "DTEND" property, it MUST be specified as a DATE value also. The anniversary type of "VEVENT" can span more than one date (i.e, "DTEND" property value is set to a calendar date after the "DTSTART" property value).
The "DTSTART" property for a "VEVENT" specifies the inclusive start of the event. For recurring events, it also specifies the very first instance in the recurrence set. The "DTEND" property for a "VEVENT" calendar component specifies the non-inclusive end of the event. For cases where a "VEVENT" calendar component specifies a "DTSTART" property with a DATE data type but no "DTEND" property, the events non-inclusive end is the end of the calendar date specified by the "DTSTART" property. For cases where a "VEVENT" calendar component specifies a "DTSTART" property with a DATE-TIME data type but no "DTEND" property, the event ends on the same calendar date and time of day specified by the "DTSTART" property.
The "VEVENT" calendar component cannot be nested within another calendar component. However, "VEVENT" calendar components can be related to each other or to a "VTODO" or to a "VJOURNAL" calendar component with the "RELATED-TO" property.
Specification http://www.ietf.org/rfc/rfc2445.txt
The event component is represented in qCal by the qCal_Component_Vevent class.
Component Name: VTODO
The to-do component is a collection of properties that represent an intended action. For instance, you might create a to-do component for yourself to remind you to clean up the kitchen, or do your taxes. A todo component can also be assigned to somebody other than you. For instance, you might need an employee to turn in their time-card on a certain date. To-do components can also contain an alarm component, which is a reminder to the assigned person to complete it.
A "VTODO" calendar component is a grouping of component properties and possibly "VALARM" calendar components that represent an action-item or assignment. For example, it can be used to represent an item of work assigned to an individual; such as "turn in travel expense today".
The "VTODO" calendar component cannot be nested within another calendar component. However, "VTODO" calendar components can be related to each other or to a "VTODO" or to a "VJOURNAL" calendar component with the "RELATED-TO" property.
A "VTODO" calendar component without the "DTSTART" and "DUE" (or "DURATION") properties specifies a to-do that will be associated with each successive calendar date, until it is completed.
Specification http://www.ietf.org/rfc/rfc2445.txt
The to-do component is represented in qCal by the qCal_Component_Vtodo class.
Component Name: VJOURNAL
The journal component is a collection of properties that represent a journal entry for a certain date. It is often useful to keep a journal of your work in order to remember what you did on a certain day. Especially when you are involved in very complex work, it is extremely useful to keep a journal.
A "VJOURNAL" calendar component is a grouping of component properties that represent one or more descriptive text notes associated with a particular calendar date. The "DTSTART" property is used to specify the calendar date that the journal entry is associated with. Generally, it will have a DATE value data type, but it can also be used to specify a DATE-TIME value data type. Examples of a journal entry include a daily record of a legislative body or a journal entry of individual telephone contacts for the day or an ordered list of accomplishments for the day. The "VJOURNAL" calendar component can also be used to associate a document with a calendar date.
The "VJOURNAL" calendar component does not take up time on a calendar. Hence, it does not play a role in free or busy time searches - - it is as though it has a time transparency value of TRANSPARENT. It is transparent to any such searches.
The "VJOURNAL" calendar component cannot be nested within another calendar component. However, "VJOURNAL" calendar components can be related to each other or to a "VEVENT" or to a "VTODO" calendar component, with the "RELATED-TO" property.
Specification http://www.ietf.org/rfc/rfc2445.txt
The journal component is represented in qCal by the qCal_Component_Vjournal class.
Component Name: VFREEBUSY
One of the common uses for the iCalendar specification is to inform or request from your coworkers or anybody else, their availability. For instance, you may need to coordinate your schedule with that of your coworker so that you may both be available for a certain event. In order to do this, you can use the free/busy component.
A "VFREEBUSY" calendar component is a grouping of component properties that represents either a request for, a reply to a request for free or busy time information or a published set of busy time information.
When used to request free/busy time information, the "ATTENDEE" property specifies the calendar users whose free/busy time is being requested; the "ORGANIZER" property specifies the calendar user who is requesting the free/busy time; the "DTSTART" and "DTEND" properties specify the window of time for which the free/busy time is being requested; the "UID" and "DTSTAMP" properties are specified to assist in proper sequencing of multiple free/busy time requests.
When used to reply to a request for free/busy time, the "ATTENDEE" property specifies the calendar user responding to the free/busy time request; the "ORGANIZER" property specifies the calendar user that originally requested the free/busy time; the "FREEBUSY" property specifies the free/busy time information (if it exists); and the "UID" and "DTSTAMP" properties are specified to assist in proper sequencing of multiple free/busy time replies.
When used to publish busy time, the "ORGANIZER" property specifies the calendar user associated with the published busy time; the "DTSTART" and "DTEND" properties specify an inclusive time window that surrounds the busy time information; the "FREEBUSY" property specifies the published busy time information; and the "DTSTAMP" property specifies the date/time that iCalendar object was created.
The "VFREEBUSY" calendar component cannot be nested within another calendar component. Multiple "VFREEBUSY" calendar components can be specified within an iCalendar object. This permits the grouping of Free/Busy information into logical collections, such as monthly groups of busy time information.
The "VFREEBUSY" calendar component is intended for use in iCalendar object methods involving requests for free time, requests for busy time, requests for both free and busy, and the associated replies.
Free/Busy information is represented with the "FREEBUSY" property. This property provides a terse representation of time periods. One or more "FREEBUSY" properties can be specified in the "VFREEBUSY" calendar component.
When present in a "VFREEBUSY" calendar component, the "DTSTART" and "DTEND" properties SHOULD be specified prior to any "FREEBUSY" properties. In a free time request, these properties can be used in combination with the "DURATION" property to represent a request for a duration of free time within a specified window of time.
The recurrence properties ("RRULE", "EXRULE", "RDATE", "EXDATE") are not permitted within a "VFREEBUSY" calendar component. Any recurring events are resolved into their individual busy time periods using the "FREEBUSY" property.
Specification http://www.ietf.org/rfc/rfc2445.txt
The free/busy component is represented in qCal by the qCal_Component_Vfreebusy class.
Component Name: VTIMEZONE
When working with dates and times, especially when working with groups of people around the world, you will quickly realize just how important it is that you get timezones right. You cannot coordinate free/busy time between people around the world without calculating the difference between timezones. The iCalendar specification goes into great detail on how to deal with timezones.
A timezone, at its simplest, is an offset (in seconds) from UTC for a given geographic area at a given date and time. There are timezones that have additional factors such as those that observe daylight-savings time and there are those that change over time, for instance, in the RFC excerpt below, there is a table for New York's timezone that shows how its rules have changed over the years.
Any time a timezone is referenced within an iCalendar object, there must be a corresponding timezone component. It is required that you specify all timezones that you intend to use before attempting to create components and properties that reference them. For example, if you create an event component that starts at 4:00pm, Eastern Standard time, you must first create a corresponding Eastern Standard Time timezone component. If you fail to do so, the iCalendar object will be invalid and cannot be rendered.
A time zone is unambiguously defined by the set of time measurement rules determined by the governing body for a given geographic area. These rules describe at a minimum the base offset from UTC for the time zone, often referred to as the Standard Time offset. Many locations adjust their Standard Time forward or backward by one hour, in order to accommodate seasonal changes in number of daylight hours, often referred to as Daylight Saving Time. Some locations adjust their time by a fraction of an hour. Standard Time is also known as Winter Time. Daylight Saving Time is also known as Advanced Time, Summer Time, or Legal Time in certain countries. The following table shows the changes in time zone rules in effect for New York City starting from 1967. Each line represents a description or rule for a particular observance.
Effective Observance Rule
Date (Date/Time) Offset Abbreviation1967-* last Sun in Oct, 02:00 -0500 EST1967-1973 last Sun in Apr, 02:00 -0400 EDT1974-1974 Jan 6, 02:00 -0400 EDT1975-1975 Feb 23, 02:00 -0400 EDT1976-1986 last Sun in Apr, 02:00 -0400 EDT1987-* first Sun in Apr, 02:00 -0400 EDTNote: The specification of a global time zone registry is not addressed by this document and is left for future study. However, implementers may find the Olson time zone database [TZ] a useful reference. It is an informal, public-domain collection of time zone information, which is currently being maintained by volunteer Internet participants, and is used in several operating systems. This database contains current and historical time zone information for a wide variety of locations around the globe; it provides a time zone identifier for every unique time zone rule set in actual use since 1970, with historical data going back to the introduction of standard time.Interoperability between two calendaring and scheduling applications, especially for recurring events, to-dos or journal entries, is dependent on the ability to capture and convey date and time information in an unambiguous format. The specification of current time zone information is integral to this behavior.
If present, the "VTIMEZONE" calendar component defines the set of Standard Time and Daylight Saving Time observances (or rules) for a particular time zone for a given interval of time. The "VTIMEZONE" calendar component cannot be nested within other calendar components. Multiple "VTIMEZONE" calendar components can exist in an iCalendar object. In this situation, each "VTIMEZONE" MUST represent a unique time zone definition. This is necessary for some classes of events, such as airline flights, that start in one time zone and end in another.
The "VTIMEZONE" calendar component MUST be present if the iCalendar object contains an RRULE that generates dates on both sides of a time zone shift (e.g. both in Standard Time and Daylight Saving Time) unless the iCalendar object intends to convey a floating time (See the section "4.1.10.11 Time" for proper interpretation of floating time). It can be present if the iCalendar object does not contain such a RRULE. In addition, if a RRULE is present, there MUST be valid time zone information for all recurrence instances.
The "VTIMEZONE" calendar component MUST include the "TZID" property and at least one definition of a standard or daylight component. The standard or daylight component MUST include the "DTSTART", "TZOFFSETFROM" and "TZOFFSETTO" properties.
An individual "VTIMEZONE" calendar component MUST be specified for each unique "TZID" parameter value specified in the iCalendar object.
Each "VTIMEZONE" calendar component consists of a collection of one or more sub-components that describe the rule for a particular observance (either a Standard Time or a Daylight Saving Time observance). The "STANDARD" sub-component consists of a collection of properties that describe Standard Time. The "DAYLIGHT" sub-component consists of a collection of properties that describe Daylight Saving Time. In general this collection of properties consists of:
For a given time zone, there may be multiple unique definitions of the observances over a period of time. Each observance is described using either a "STANDARD" or "DAYLIGHT" sub-component. The collection of these sub-components is used to describe the time zone for a given period of time. The offset to apply at any given time is found by locating the observance that has the last onset date and time before the time in question, and using the offset value from that observance.
The top-level properties in a "VTIMEZONE" calendar component are:
The mandatory "TZID" property is a text value that uniquely identifies the VTIMZONE calendar component within the scope of an iCalendar object.
The optional "LAST-MODIFIED" property is a UTC value that specifies the date and time that this time zone definition was last updated.
The optional "TZURL" property is url value that points to a published VTIMEZONE definition. TZURL 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.
The collection of properties that are used to define the STANDARD and DAYLIGHT sub-components include:
The mandatory "DTSTART" property gives the effective onset date and local time for the time zone sub-component definition. "DTSTART" in this usage MUST be specified as a local DATE-TIME value.
The mandatory "TZOFFSETFROM" property gives the UTC offset which is in use when the onset of this time zone observance begins. "TZOFFSETFROM" is combined with "DTSTART" to define the effective onset for the time zone sub-component definition. For example, the following represents the time at which the observance of Standard Time took effect in Fall 1967 for New York City:
DTSTART:19671029T020000 TZOFFSETFROM:-0400The mandatory "TZOFFSETTO " property gives the UTC offset for the time zone sub-component (Standard Time or Daylight Saving Time) when this observance is in use.
The optional "TZNAME" property is the customary name for the time zone. It may be specified multiple times, to allow for specifying multiple language variants of the time zone names. This could be used for displaying dates.
If specified, the onset for the observance defined by the time zone sub-component is defined by either the "RRULE" or "RDATE" property. If neither is specified, only one sub-component can be specified in the "VTIMEZONE" calendar component and it is assumed that the single observance specified is always in effect.
The "RRULE" property defines the recurrence rule for the onset of the observance defined by this time zone sub-component. Some specific requirements for the usage of RRULE for this purpose include:
Alternatively, the "RDATE" property can be used to define the onset of the observance by giving the individual onset date and times. "RDATE" in this usage MUST be specified as a local DATE-TIME value in UTC time.
The optional "COMMENT" property is also allowed for descriptive explanatory text.
Specification http://www.ietf.org/rfc/rfc2445.txt
Each timezone component must define at least one of the following sub-components. These sub-components are used to describe the timezone for a given period of time. As I stated above, a timezone's rules can change over the years. These sub-components describe those changes and determine the offset to apply for a given date and time.
Sub-component Name: STANDARD
The standard component is a collection of properties that define the “standard time” rules for a timezone (as opposed to daylight-savings time). There is no limit to the number of these sub-components that can be defined for a timezone. If a timezone's “standard time” offset rules have changed over time, simply create a standard sub-component for each of those changes.
The standard sub-component is represented in qCal by the qCal_Component_Standard class.
Sub-component Name: DAYLIGHT
The daylight component is a collection of properties that define the “daylight-savings time” rules for a timezone (as opposed to standard time). There is no limit to the number of these sub-components that can be defined for a timezone. If a timezone's “daylight-savings time” offset rules have changed over time, simply create a daylight sub-component for each of those changes.
The daylight sub-component is represented in qCal by the qCal_Component_Daylight class.
Component Name: VALARM
The alarm component is a collection of properties that define a reminder for either an event or to-do component. It is actually more of a sub-component because it must be nested within either an event or to-do component to be valid.
An alarm can be configured to go off when the event or to-do starts, ends, or at a specific amount of time before or after it starts or ends. Or it can be configured to go off at a specific time completely unrelated to the start or end of the event or to-do component.
There are four different types of alarms that can be defined.
A "VALARM" calendar component is a grouping of component properties that is a reminder or alarm for an event or a to-do. For example, it may be used to define a reminder for a pending event or an overdue to-do.
The "VALARM" calendar component MUST include the "ACTION" and "TRIGGER" properties. The "ACTION" property further constrains the "VALARM" calendar component in the following ways:
When the action is "AUDIO", the alarm can also include one and only one "ATTACH" property, which MUST point to a sound resource, which is rendered when the alarm is triggered.
When the action is "DISPLAY", the alarm MUST also include a "DESCRIPTION" property, which contains the text to be displayed when the alarm is triggered.
When the action is "EMAIL", the alarm MUST include a "DESCRIPTION" property, which contains the text to be used as the message body, a "SUMMARY" property, which contains the text to be used as the message subject, and one or more "ATTENDEE" properties, which contain the email address of attendees to receive the message. It can also include one or more "ATTACH" properties, which are intended to be sent as message attachments. When the alarm is triggered, the email message is sent.
When the action is "PROCEDURE", the alarm MUST include one and only one "ATTACH" property, which MUST point to a procedure resource, which is invoked when the alarm is triggered.
The "VALARM" calendar component MUST only appear within either a "VEVENT" or "VTODO" calendar component. "VALARM" calendar components cannot be nested. Multiple mutually independent "VALARM" calendar components can be specified for a single "VEVENT" or "VTODO" calendar component.
The "TRIGGER" property specifies when the alarm will be triggered. The "TRIGGER" property specifies a duration prior to the start of an event or a to-do. The "TRIGGER" edge may be explicitly set to be relative to the "START" or "END" of the event or to-do with the "RELATED" parameter of the "TRIGGER" property. The "TRIGGER" property value type can alternatively be set to an absolute calendar date and time of day value.
In an alarm set to trigger on the "START" of an event or to-do, the "DTSTART" property MUST be present in the associated event or to-do. In an alarm in a "VEVENT" calendar component set to trigger on the "END" of the event, either the "DTEND" property MUST be present, or the "DTSTART" and "DURATION" properties MUST both be present. In an alarm in a "VTODO" calendar component set to trigger on the "END" of the to-do, either the "DUE" property MUST be present, or the "DTSTART" and "DURATION" properties MUST both be present.
The alarm can be defined such that it triggers repeatedly. A definition of an alarm with a repeating trigger MUST include both the "DURATION" and "REPEAT" properties. The "DURATION" property specifies the delay period, after which the alarm will repeat. The "REPEAT" property specifies the number of additional repetitions that the alarm will triggered. This repitition count is in addition to the initial triggering of the alarm. Both of these properties MUST be present in order to specify a repeating alarm. If one of these two properties is absent, then the alarm will not repeat beyond the initial trigger.
The "ACTION" property is used within the "VALARM" calendar component to specify the type of action invoked when the alarm is triggered. The "VALARM" properties provide enough information for a specific action to be invoked. It is typically the responsibility of a "Calendar User Agent" (CUA) to deliver the alarm in the specified fashion. An "ACTION" property value of AUDIO specifies an alarm that causes a sound to be played to alert the user; DISPLAY specifies an alarm that causes a text message to be displayed to the user; EMAIL specifies an alarm that causes an electronic email message to be delivered to one or more email addresses; and PROCEDURE specifies an alarm that causes a procedure to be executed. The "ACTION" property MUST specify one and only one of these values.
In an AUDIO alarm, if the optional "ATTACH" property is included, it MUST specify an audio sound resource. The intention is that the sound will be played as the alarm effect. If an "ATTACH" property is specified that does not refer to a sound resource, or if the specified sound resource cannot be rendered (because its format is unsupported, or because it cannot be retrieved), then the CUA or other entity responsible for playing the sound may choose a fallback action, such as playing a built-in default sound, or playing no sound at all.
In a DISPLAY alarm, the intended alarm effect is for the text value of the "DESCRIPTION" property to be displayed to the user.
In an EMAIL alarm, the intended alarm effect is for an email message to be composed and delivered to all the addresses specified by the "ATTENDEE" properties in the "VALARM" calendar component. The "DESCRIPTION" property of the "VALARM" calendar component MUST be used as the body text of the message, and the "SUMMARY" property MUST be used as the subject text. Any "ATTACH" properties in the "VALARM" calendar component SHOULD be sent as attachments to the message.
In a PROCEDURE alarm, the "ATTACH" property in the "VALARM" calendar component MUST specify a procedure or program that is intended to be invoked as the alarm effect. If the procedure or program is in a format that cannot be rendered, then no procedure alarm will be invoked. If the "DESCRIPTION" property is present, its value specifies the argument string to be passed to the procedure or program. "Calendar User Agents" that receive an iCalendar object with this category of alarm, can disable or allow the "Calendar User" to disable, or otherwise ignore this type of alarm. While a very useful alarm capability, the PROCEDURE type of alarm SHOULD be treated by the "Calendar User Agent" as a potential security risk.
Specification http://www.ietf.org/rfc/rfc2445.txt
The alarm component is represented in qCal by the qCal_Component_Valarm class.