iCalendar components are basically just a collection of pre-defined or custom properties. When creating an iCalendar component, there are typically several required properties and many optional properties that you can define in order to configure the way the component will behave when read by a calendar user agent such as Microsoft Outlook or Mozilla Sunbird.
Component properties in qCal are represented by descendents of the qCal_Property class.
The following properties specify descriptive information about iCalendar components.
Property Name: ATTACH
Value Type: URI (can be changed to binary)
Components: ”VEVENT”, ”VTODO”, ”VJOURNAL” or ”VALARM”
qCal Class: qCal_Property_Attach
The attach property allows for a document object to be associated with a component. The default value type is “URI”, which allows you to specify a URI that points to the document you wish to associate with the component. If you wish to embed the document directly within the iCalendar object, you may change the value type to “binary” and encode the document object using the base64 algorithm.
The property provides the capability to associate a document object with a calendar component.
This property can be specified multiple times within an iCalendar object.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: CATEGORIES
Value Type: Text
Components: ”VEVENT”, ”VTODO” or ”VJOURNAL”
qCal Class: qCal_Property_Categories
The categories property makes it possible to assign a list of categories to a component which makes it easier to search for the component later, list each component by category, etc.
This property defines the categories for a calendar component.
This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the "VEVENT", "VTODO" or "VJOURNAL" calendar components, more than one category can be specified as a list of categories separated by the COMMA character (US-ASCII decimal 44).
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: CLASS
Value Type: Text
Components: ”VEVENT”, ”VTODO” or ”VJOURNAL”
qCal Class: qCal_Property_Class
The classification property defines who or what should have access to a component. It is vague by design, because it is intended to work within a larger security/access control system. Rather than define literally who and what can access a component, you define the access classification (public, private, etc.), and then define who or what can access public components, who or what can access private components, etc.
Unfortunately, due to the nature of many exchange processes using the iCalendar specification, it is often impossible to enforce the access classifications designated by this property, but it can still serve as a method of capturing the intent of the calendar owner.
This property defines the access classification for a calendar component.
An access classification is only one component of the general security system within a calendar application. It provides a method of capturing the scope of the access the calendar owner intends for information within an individual calendar entry. The access classification of an individual iCalendar component is useful when measured along with the other security components of a calendar system (e.g., calendar user authentication, authorization, access rights, access role, etc.). Hence, the semantics of the individual access classifications cannot be completely defined by this memo alone. Additionally, due to the "blind" nature of most exchange processes using this memo, these access classifications cannot serve as an enforcement statement for a system receiving an iCalendar object. Rather, they provide a method for capturing the intention of the calendar owner for the access to the calendar component.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: COMMENT
Value Type: Text
Components: ”VEVENT”, ”VTODO”, ”VJOURNAL”, ”VTIMEZONE” or ”VFREEBUSY”
qCal Class: qCal_Property_Comment
Sometimes it is useful to be able to associate information with a component that has no intended purpose other than being a comment. In those cases, you can use the comment property. You can think of it much like PHP comments. They are there to describe the code, but have no other purpose and are not processed by anything. It's the same thing with the comment property.
This property specifies non-processing information intended to provide a comment to the calendar user.
The property can be specified multiple times.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: DESCRIPTION
Value Type: Text
Components: ”VEVENT”, ”VTODO”, ”VJOURNAL”, or ”VALARM”
qCal Class: qCal_Property_Description
The description property takes on different purposes depending on the component, but usually it is intended to provide a lengthy description of the component. See the specification description below for information about its purpose for each component type.
This property provides a more complete description of the calendar component, than that provided by the "SUMMARY" property.
This property is used in the "VEVENT" and "VTODO" to capture lengthy textual decriptions associated with the activity.
This property is used in the "VJOURNAL" calendar component to capture one more textual journal entries.
This property is used in the "VALARM" calendar component to capture the display text for a DISPLAY category of alarm, to capture the body text for an EMAIL category of alarm and to capture the argument string for a PROCEDURE category of alarm.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: GEO
Value Type: Float
Components: ”VEVENT” or ”VTODO”
qCal Class: qCal_Property_Geo
An event or to-do component can be assigned a geographic position by specifying this property. The property must specify latitude and longitude as real numbers (float values). Both latitude and longitude allow up to six decimal places, which results in accuracy to within a meter of the location you intend to reference.
See the specification description below for a detailed description of valid values and nuances for this property.
This property specifies information related to the global position for the activity specified by a calendar component.
The property value specifies latitude and longitude, in that order (i.e., "LAT LON" ordering). The longitude represents the location east or west of the prime meridian as a positive or negative real number, respectively. The longitude and latitude values MAY be specified up to six decimal places, which will allow for accuracy to within one meter of geographical position. Receiving applications MUST accept values of this precision and MAY truncate values of greater precision.
Values for latitude and longitude shall be expressed as decimal fractions of degrees. Whole degrees of latitude shall be represented by a two-digit decimal number ranging from 0 through 90. Whole degrees of longitude shall be represented by a decimal number ranging from 0 through 180. When a decimal fraction of a degree is specified, it shall be separated from the whole number of degrees by a decimal point.
Latitudes north of the equator shall be specified by a plus sign (+), or by the absence of a minus sign (-), preceding the digits designating degrees. Latitudes south of the Equator shall be designated by a minus sign (-) preceding the digits designating degrees. A point on the Equator shall be assigned to the Northern Hemisphere.
Longitudes east of the prime meridian shall be specified by a plus sign (+), or by the absence of a minus sign (-), preceding the digits designating degrees. Longitudes west of the meridian shall be designated by minus sign (-) preceding the digits designating degrees. A point on the prime meridian shall be assigned to the Eastern Hemisphere. A point on the 180th meridian shall be assigned to the Western Hemisphere. One exception to this last convention is permitted. For the special condition of describing a band of latitude around the earth, the East Bounding Coordinate data element shall be assigned the value +180 (180) degrees.
Any spatial address with a latitude of +90 (90) or -90 degrees will specify the position at the North or South Pole, respectively. The component for longitude may have any legal value.
With the exception of the special condition described above, this form is specified in Department of Commerce, 1986, Representation of geographic point locations for information interchange (Federal Information Processing Standard 70-1): Washington, Department of Commerce, National Institute of Standards and Technology.
The simple formula for converting degrees-minutes-seconds into decimal degrees is:
decimal = degrees + minutes/60 + seconds/3600.Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: LOCATION
Value Type: Text
Components: ”VEVENT” or ”VTODO”
qCal Class: qCal_Property_Location
This property designates the name of the place intended for the activity defined by either a to-do or event component. It is related to the GEO property specified above in that it specifies the location of the component. The difference is that this property only names the location, while the GEO property tells you the precise geographic position of the location.
The property defines the intended venue for the activity defined by a calendar component.
Specific venues such as conference or meeting rooms may be explicitly specified using this property. An alternate representation may be specified that is a URI that points to directory information with more structured specification of the location. For example, the alternate representation may specify either an LDAP URI pointing to an LDAP server entry or a CID URI pointing to a MIME body part containing a vCard [RFC 2426] for the location.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: PERCENT-COMPLETE
Value Type: Integer
Components: ”VTODO”
qCal Class: qCal_Property_PercentComplete
This property is used to convey how much of a to-do item has been completed on a scale from 0 to 100.
This property is used by an assignee or delegatee of a to-do to convey the percent completion of a to-do to the Organizer.
The property value is a positive integer between zero and one hundred. A value of "0" indicates the to-do has not yet been started. A value of "100" indicates that the to-do has been completed. Integer values in between indicate the percent partially complete.
When a to-do is assigned to multiple individuals, the property value indicates the percent complete for that portion of the to-do assigned to the assignee or delegatee. For example, if a to-do is assigned to both individuals "A" and "B". A reply from "A" with a percent complete of "70" indicates that "A" has completed 70% of the to-do assigned to them. A reply from "B" with a percent complete of "50" indicates "B" has completed 50% of the to-do assigned to them.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: PRIORITY
Value Type: Integer
Components: ”VEVENT” or ”VTODO”
qCal Class: qCal_Property_Priority
This property specifies the relative priority of either an event or to-do component. For an event component, this property is useful to prioritize events that occur at the same time. For to-do items, this property is useful for prioritizing items within a list.
The property value can be zero for an undefined priority, one for the highest possible priority and nine for the lowest possible priority.
The property defines the relative priority for a calendar component.
The priority is specified as an integer in the range zero to nine. A value of zero (US-ASCII decimal 48) specifies an undefined priority. A value of one (US-ASCII decimal 49) is the highest priority. A value of two (US-ASCII decimal 50) is the second highest priority. Subsequent numbers specify a decreasing ordinal priority. A value of nine (US-ASCII decimal 58) is the lowest priority.
A CUA with a three-level priority scheme of "HIGH", "MEDIUM" and "LOW" is mapped into this property such that a property value in the range of one (US-ASCII decimal 49) to four (US-ASCII decimal 52) specifies "HIGH" priority. A value of five (US-ASCII decimal 53) is the normal or "MEDIUM" priority. A value in the range of six (US- ASCII decimal 54) to nine (US-ASCII decimal 58) is "LOW" priority.
A CUA with a priority schema of "A1", "A2", "A3", "B1", "B2", ..., "C3" is mapped into this property such that a property value of one (US-ASCII decimal 49) specifies "A1", a property value of two (US- ASCII decimal 50) specifies "A2", a property value of three (US-ASCII decimal 51) specifies "A3", and so forth up to a property value of 9 (US-ASCII decimal 58) specifies "C3".
Other integer values are reserved for future use.
Within a "VEVENT" calendar component, this property specifies a priority for the event. This property may be useful when more than one event is scheduled for a given time period.
Within a "VTODO" calendar component, this property specified a priority for the to-do. This property is useful in prioritizing multiple action items for a given time period.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: RESOURCES
Value Type: Text
Components: ”VEVENT” or ”VTODO”
qCal Class: qCal_Property_Resources
This property defines a list of resources that may be needed for an event or to-do item. For instance, if the event is a birthday party, the list of resources might be “cake, ice cream, birthday hats, steamers”.
This property defines the equipment or resources anticipated for an activity specified by a calendar entity.
The property value is an arbitrary text. More than one resource can be specified as a list of resources separated by the COMMA character (US-ASCII decimal 44).
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: STATUS
Value Type: Text
Components: ”VEVENT”, ”VTODO” or ”VJOURNAL”
qCal Class: qCal_Property_Status
This property defines the status of the component. For each component type, there is a list of valid status values.
For events, valid status values are “tentative”, “confirmed” or “cancelled”.
For to-dos, valid status values are “needs-action”, “completed”, “in-process” or “cancelled”.
For journals, valid status values are “draft”, “final”, “cancelled” or “removed”.
This property defines the overall status or confirmation for the calendar component.
In a group scheduled calendar component, the property is used by the "Organizer" to provide a confirmation of the event to the "Attendees". For example in a "VEVENT" calendar component, the "Organizer" can indicate that a meeting is tentative, confirmed or cancelled. In a "VTODO" calendar component, the "Organizer" can indicate that an action item needs action, is completed, is in process or being worked on, or has been cancelled. In a "VJOURNAL" calendar component, the "Organizer" can indicate that a journal entry is draft, final or has been cancelled or removed.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: SUMMARY
Value Type: Text
Components: ”VEVENT”, ”VTODO”, ”VJOURNAL” or ”VALARM”
qCal Class: qCal_Property_Summary
For events, to-dos, and journals, this property defines a short, one-line summary of the component.
For alarms, this property is used for the subject of the e-mail if using the e-mail alarm type.
This property defines a short summary or subject for the calendar component.
This property is used in the "VEVENT", "VTODO" and "VJOURNAL" calendar components to capture a short, one line summary about the activity or journal entry.
This property is used in the "VALARM" calendar component to capture the subject of an EMAIL category of alarm.
Specification http://www.ietf.org/rfc/rfc2445.txt
The following properties define date and time related component properties.
Property Name: COMPLETED
Value Type: Date-time
Components: ”VTODO”
qCal Class: qCal_Property_Completed
This property defines the date and time that a to-do item was completed in UTC format.
This property defines the date and time that a to-do was actually completed.
The date and time MUST be in a UTC format.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: DTEND
Value Type: Date-time (can be changed to Date)
Components: ”VEVENT” or ”VFREEBUSY”
qCal Class: qCal_Property_Dtend
This property defines the date and time that an event or free/busy component ends. There is a corresponding “DTSTART” property that must come before it in either component.
The value type can be changed to “date” if you want to specify a date and not a time that it ends.
This property specifies the date and time that a calendar component ends.
Within the "VEVENT" calendar component, this property defines the date and time by which the event ends. The value MUST be later in time than the value of the "DTSTART" property.
Within the "VFREEBUSY" calendar component, this property defines the end date and time for the free or busy time information. The time MUST be specified in the UTC time format. The value MUST be later in time than the value of the "DTSTART" property.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: DTDUE
Value Type: Date-time (can be changed to Date)
Components: ”VTODO”
qCal Class: qCal_Property_Dtdue
This property defines the date and time that a to-do component is due. If the to-do component has a “DTSTART” value, this property must come after it.
The value type can be changed to “date” if you want to specify a date and not a time that it is due.
This property defines the date and time that a to-do is expected to be completed.
The value MUST be a date/time equal to or after the DTSTART value, if specified.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: DTSTART
Value Type: Date-time (can be changed to Date)
Components: ”VEVENT”, ”VTODO”, ”VFREEBUSY” or ”VTIMEZONE”
qCal Class: qCal_Property_Dtstart
This property defines when a calendar component begins. This property behaves differently depending on the component it is set for.
For event components, this property specifies what date and time the event starts.
For free/busy time components, this property defines when the free/busy time the starts.
For timezone components, this property defines when a daylight or standard sub-component starts. It must not be changed to the date value type and must be specified as UTC.
The value type can be changed to “date” if you want to specify a date and not a time that the component starts.
This property specifies when the calendar component begins
Within the "VEVENT" calendar component, this property defines the start date and time for the event. The property is REQUIRED in "VEVENT" calendar components. Events can have a start date/time but no end date/time. In that case, the event does not take up any time.
Within the "VFREEBUSY" calendar component, this property defines the start date and time for the free or busy time information. The time MUST be specified in UTC time.
Within the "VTIMEZONE" calendar component, this property defines the effective start date and time for a time zone specification. This property is REQUIRED within each STANDARD and DAYLIGHT part included in "VTIMEZONE" calendar components and MUST be specified as a local DATE-TIME without the "TZID" property parameter.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: DURATION
Value Type: Period (must be in UTC format)
Components: ”VFREEBUSY”
qCal Class: qCal_Property_Freebusy
This property is used to specify time that a particular calendar users is free and when he is busy. It must be specified as a period of time, meaning a start date and time and an end date/time. This can be achieved by either providing an explicit start date and time and an end date and time or by providing a start date and time and a duration. Either way, the start date and time must be specified using UTC format.
This property can have multiple values.
The property defines one or more free or busy time intervals.
These time periods can be specified as either a start and end date-time or a start date-time and duration. The date and time MUST be a UTC time format.
"FREEBUSY" properties within the "VFREEBUSY" calendar component SHOULD be sorted in ascending order, based on start time and then end time, with the earliest periods first.
The "FREEBUSY" property can specify more than one value, separated by the COMMA character (US-ASCII decimal 44). In such cases, the "FREEBUSY" property values SHOULD all be of the same "FBTYPE" property parameter type (e.g., all values of a particular "FBTYPE" listed together in a single property).
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: TRANSP
Value Type: Text
Components: ”VEVENT”
qCal Class: qCal_Property_Transp
In many calendar user agents such as Outlook or Mozilla Sunbird, it is necessary to determine the dates and times where a calendar user is busy or available. During searches for this information, the program will look at free/busy time components and properties, and it will look at events to determine whether a user is busy or available at a specific date and time. If this property is set as “transparent”, the search will show that the user is not busy during the event. If it is set to “opaque”, the search will show that the user is busy during the event.
This property defines whether an event is transparent or not to busy time searches.
Time Transparency is the characteristic of an event that determines whether it appears to consume time on a calendar. Events that consume actual time for the individual or resource associated with the calendar SHOULD be recorded as OPAQUE, allowing them to be detected by free-busy time searches. Other events, which do not take up the individual's (or resource's) time SHOULD be recorded as TRANSPARENT, making them invisible to free-busy time searches.
Specification http://www.ietf.org/rfc/rfc2445.txt
The following properties define timezone related component properties.
Before attempting to understand the properties below, it is important that you understand that a timezone component is constructed from a collection of sub-components (either “STANDARD” for Standard Time or “DAYLIGHT” for Daylight Savings Time), each of which define what is called a timezone “observance”. An “observance” is a set of rules for how to apply a timezone offset for a given period of time. The reason one might need more than one “observance” is that timezone offset rules can change over time and a timezone component needs to be able to calculate the offset to apply for any given date.
Timezones are one of the most difficult things in the iCalendar specification to wrap your head around, so don't feel too bad if you don't grasp these properties right away. If, after reading this section a few times, you still don't quite get it, feel free to contact me directly and I will do my best to help you.
Property Name: TZID
Value Type: Text
Components: ”VTIMEZONE”
qCal Class: qCal_Property_Tzid
This property is used to uniquely identify a timezone component within the scope of an iCalendar object. That way, when you specify that particular timezone anywhere else in the iCalendar object, all you have to do is reference the timezone's unique ID. For instance, let's say you need to specify a date-time property in Eastern Standard Time. In order to do that, you will need to create a timezone component with a TZID of something like “US/Eastern”. You can then specify that your date-time property's timezone ID is “US/Eastern” and it will use the timezone component you created to apply the correct time offset.
This property specifies the text value that uniquely identifies the "VTIMEZONE" calendar component.
This is the label by which a time zone calendar component is referenced by any iCalendar properties whose data type is either DATE-TIME or TIME and not intended to specify a UTC or a "floating" time. The presence of the SOLIDUS character (US-ASCII decimal 47) as a prefix, indicates that this TZID represents an unique ID in a globally defined time zone registry (when such registry is defined).
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 Olson database [TZ]. The specification of globally unique time zone identifiers is not addressed by this document and is left for future study.Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: TZNAME
Value Type: Text
Components: ”VTIMEZONE”
qCal Class: qCal_Property_Tzname
This property is used to define a timezone's name. This differs from the “TZID” property in that it is not used to identify a timezone and doesn't necessarily have to be unique. This is simply the name for which you might call the timezone if you were to speak of it to somebody. For instance, “Pacific Standard Time” would be the time zone name for where I live.
This property specifies the customary designation for a time zone description.
This property may be specified in multiple languages; in order to provide for different language requirements.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: TZOFFSETFROM
Value Type: UTC-Offset
Components: ”VTIMEZONE”
qCal Class: qCal_Property_Tzoffsetfrom
Better description coming soon.
This property specifies the offset which is in use prior to this time observance. It is used to calculate the absolute time at which the transition to a given observance takes place. This property MUST only be specified in a "VTIMEZONE" calendar component. A "VTIMEZONE" calendar component MUST include this property. The property value is a signed numeric indicating the number of hours and possibly minutes from UTC. Positive numbers represent time zones east of the prime meridian, or ahead of UTC. Negative numbers represent time zones west of the prime meridian, or behind UTC.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: TZOFFSETTO
Value Type: UTC-Offset
Components: ”VTIMEZONE”
qCal Class: qCal_Property_Tzoffsetto
Better description coming soon.
This property specifies the offset which is in use in this time zone observance. It is used to calculate the absolute time for the new observance. The property value is a signed numeric indicating the number of hours and possibly minutes from UTC. Positive numbers represent time zones east of the prime meridian, or ahead of UTC. Negative numbers represent time zones west of the prime meridian, or behind UTC.
Specification http://www.ietf.org/rfc/rfc2445.txt
Property Name: TZURL
Value Type: URI
Components: ”VTIMEZONE”
qCal Class: qCal_Property_Tzoffsetto
This property defines a URI pointing to a network location (either on the internet or on an intranet) which is used to retrieve the most up-to-date possible version of a timezone component.
The TZURL provides a means for a VTIMEZONE component to point to a network location that can be used to retrieve an up-to- date version of itself. This provides a hook to handle changes government bodies impose upon time zone definitions. Retrieval of this resource results in an iCalendar object containing a single VTIMEZONE component and a METHOD property set to PUBLISH.
Specification http://www.ietf.org/rfc/rfc2445.txt
The following properties specify relationship information throughout an iCalendar object.
The following properties specify recurrence information within calendar components.
The following properties specify alarm information within calendar components.
The following properties specify information related to changes within calendar components.
The following properties specify various miscellaneous information about calendar components.