This section outlines the main concepts you need to understand to grok iCalendar.
iCalendar data is composed of components. Each component is made up of a number of properties. Properties have values and may also have parameters (which are sort of like modifiers to the way a property works).
RFC2445 is largely concerned with specifying what types of components, properties and parameters may be used in various circumstances.
Take a look at the following example:
BEGIN:VEVENT DTSTART:20010714T170000Z DTEND:20010715T035959Z SUMMARY:Bastille Day Party ATTACH;FMTTYPE=image/jpeg:http://domain.com/images/bastille.jpg END:VEVENT |
The example shows a VEVENT component (sometimes referred to as an EVENT), containing the properties DTSTART, DTEND, SUMMARY, and ATTACH. All the properties except ATTACH are in a simple KEY:VALUE format.
The ATTACH property has a parameter specifying the attachment's format. The syntax for parameters is PROPERTY;PARAM=PARAMVALUE;PARAM=PARAMVALUE:VALUE -- note that you can have multiple parameters separated by semi-colons.
The three main kinds of components are Events, Journals, and Todos.
An event is something like a meeting, which has a start and end time and attendees. It is described using a VEVENT component.
A journal entry is something which is marked with a certain time but doesn't actually take any duration to complete. Typically it might be a note made in a diary saying something like "Fred dropped by to ask about the project". This would let you look back and see what had happened, but wouldn't actually count as "time spent". A journal is described in iCalendar using a VJOURNAL component.
A todo is, unsurprisingly, a task which must be completed by a certain date. It has different properties to an event; for instance, it has a due date rather than a start/end time. A todo is described in iCalendar using a VTODO component.
The ATTENDEE property is a common one, and warrants some explanation. An attendee is someone who's been invited to an event. Don't be confused into thinking they're actually attending -- their attendance status is specified using the PARTSTAT ("participation status") property.
The simple form of the ATTENDEE property is:
ATTENDEE:mailto:foo@example.com |
Here's a more complex example:
ATTENDEE;PARTSTAT=TENTATIVE;ROLE=REQ-PARTICIPANT; DELEGATED-FROM=bar@example.com:mailto:foo@example.com |
The first thing to note is that this property runs over a linebreak. You can do this if you indent the second and subsequent lines with a space.
The parameters shown in the example above include PARTSTAT (participation status), ROLE (this person is required to attend; presumably they're important to the success of the meeting), and DELEGATED-FROM (presumably foo's boss decided to send foo instead of himself).
There are a number of ways of showing time in iCalendar, and they are used in a number of different places.
The simplest way of expressing dates is YYYYMMDD, for instance 20010114 for the 14th of January 2001.
Times can be expressed similarly, as HHMMSS (eg 190000 for 7pm). This is used for local time. However, if you want to fix a time properly, you'll have to put a Z on the end (for "Zulu", the military name for the UTC timezone). For example: a telephone meeting scheduled between people in different timezones should have its time specified in UTC using the HHMMSSZ format, but a reminder to oneself to go to the gym at 7pm every day should be specified in local time so that it would still occur in the early evening even if one travelled across timezones.
To specify a date and time together, simply put the date, then a T, then the time: 20010114T190000Z
Sometimes, instead of a start and end time, one might choose to specify a a duration. It comes to essentially the same thing, but makes more sense in some circumstances. The format for duration is slightly odd: it starts with a P (for Period), then has numbers and letters, with letters representing the units and numbers representing how many of them there are. For instance, H is for hours, so 4H would be four hours. Therefore a duration of 2 hours 30 minutes would be specified as P2H30M.
Syntax for dates, times and durations is described more fully in sections 4.3.4, 4.3.5, 4.3.6 and 4.3.12 of RFC2445.
A typical use of attachments would be to distribute an agenda or minutes for a meeting.
Attachments come in two flavours: URLs and Base64 encoded data. Here are examples of each type:
ATTACH:http://xyz.com/public/quarterly-report.doc ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE <...remainder of "BASE64" encoded binary data...> |
One complex subject is the handling of recurring events, which is documented in section 4.8.5 of RFC2445.
A recurring event has a DTSTART property which specifies its first occurence, then a set of rules which can be parsed to find the "recurrence set", or the list of dates and times on which the event will recur.
Recurrence is specified using the RRULE, RDATE, EXRULE and EXDATE properties.
RRULE describes a rule for finding recurrence, for instance "daily until the 20th September". RDATE specifies a list of specific dates/times. Obviously the former is more useful for regularly recurring events, whereas the second is more suited to those which are repeated on an ad-hoc basis.
EXRULE and EXDATE are similar, but describe exceptions to the recurrence list. For instance, an RRULE which said "daily" and an EXRULE which said "weekly on Tuesdays" would combine to mean "every day except Tuesdays". Similar, an EXDATE property could be used to specify specific dates on which the event would not recur, such as public holidays.
A store is where you keep your calendar data. It can be a local store (i.e. on the same system as your calendar client) or a remote store (for instance on a central server). iCalendar data can be stored in different formats.