Sometimes you want to describe an event that occurs more than once. An example of this is your significant other's birthday. Instead of entering the same event for every year so you won't forget to buy that present, you want to be able to to enter all of these events at once.
iCalendar makes this possible by letting you specify the set of times you want the event to occur on. You can give a list of times for the event to occur, or you can describe that list by creating a rule for it. An example rule could be FREQ=WEEKLY;BYDAY=FR. This is iCalendar syntax for “every friday”.
BEGIN:VEVENT UID:sadoigup3486asodghpqwe4986ydfoighsdp9d8ry64wjgh DTSTART:20000108T163000 DTSTAMP:20000402T124947Z SUMMARY:End of week drinks RRULE:FREQ=WEEKLY;BYDAY=FREXRULE:FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1
END:VEVENT
Example 1. Recurring event
The event in Example 1 demonstrates
how you can use the rule sytax to make an event occur every friday,
with the exception of every last friday of the month. It uses an
RRULE property ()
to say that the event should occur every friday, and the adds an
EXRULE property ()
to exclude every last friday of the month from the set.
If there was a single friday that this event shouldn't occur at, you could add a EXDATE property to explicitly exclude it. For example, to exclude April 6, 2001, you would add a line that says EXDATE:20010406T163000. There is also a corresponding RDATE property, which includes a single occurence.
To calculate the set of occurences, you take the DTSTART, the times you get from expanding the RRULErules, and the times in the RDATE property. From this set you remove any dates/times you get from the EXRULE and EXDATE properties. The DTSTART is always the first occurence, unless it is explicitly excluded by an EXDATE property.
To create a recurrence rule, you begin by specifying the basic recurrence frequency. So, for your birthday, you'd pick yearly (FREQ=YEARLY). For a work meeting, you might pick weekly, or maybe daily if you don't have a nice job. The possible choices are YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY and SECONDLY.
Note
When creating a recurrence rule, always remember that anything not explicitly specified by the rule is taken from the DTSTART property.
If you're really lucky, and only have a work meeting every other week, you can use the INTERVAL specifier. Then you'd have a rule like this: FREQ=WEEKLY;INTERVAL=2.
After this, you can add one or more BYxxx specifiers to either expand or further limit the set of occurences you have so far. If you don't have just one meeting every other week, but a day full of them, you could use BYHOUR. So for example FREQ=WEEKLY;INTERVAL=2;BYHOUR=8,10,13,15 if you had meetings at eight and ten AM, and one and three PM. Or, these hectic meeting days only happen at the end of each semester: FREQ=WEEKLY;INTERVAL=2;BYHOUR=8,10,13,15;BYMONTH=6,12.
The possible BYxxx specifiers are BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYHOUR, BYMINUTE, BYSECOND and BYSETPOS. If more than one is specified, they are evaluated in this order. Generally, a set expands if its period of time is smaller than the frequency, and is limited otherwise.
If you know exactly how many times an event will occur, you can specify this with the COUNT specifier. So, if you have your school year split up in quarters of ten weeks, of which seven are proper lecture weeks, you could have a rule for your classes like this: FREQ=WEEKLY;COUNT=7. Remember, all the missing information is taken from the DTSTART property, so the day and the time are specified there. No need to repeat that information here.
A last way to modify the rule you have so far is with the UNTIL specifier. Say, there's some ongoing puzzle competition, where you have to submit your entry on every 20th of the month. And the competion ends in December. You can codify this in a rule like this: FREQ=MONTHLY;BYMONTHDAY=20;UNTIL=20031231Z. The UNTIL specifier must be a UTC DATE or DATE-TIME value. You can't have both UNTIL and COUNT specifiers in the same recurrence rule.
The rest of this document will show how to create recurring events, and what to do with them in your applications.