The rrules parameter takes a semicolon-separated list of quoted recurrence rule strings. Each string represents a recurrence rule of the event. Each string must be enclosed in quotes. Many parameters are possible for recurrence rules. (See RFC 2445 for a complete description of the syntax.)
Three parameters used by Calendar Server for specifying recurrence are freq, count and until:
The freq parameter in a rule defines the periodicity of the event, and has the following possible values:
DAILY |
The event recurs daily. |
WEEKLY |
The event recurs weekly. |
MONTHLY |
The event recurs monthly. |
YEARLY |
The event recurs yearly. |
The count parameter in a rule defines how many times the meeting repeats. If you do not specify the count, the default is the maximum number of recurrences allowed. The default maximum is 60. To change the maximum number, set the server configuration preference calstore.recurrence.bound.
The until parameter in a rule specifies using an end date as opposed to using the count to limit the number of instances created. Instances are created up to the end date or until 60 instances are created, whichever occurs first.
In the event that neither the count nor the until parameter are specified, the default is 60 instances.
Using the storeevents.wcap command to create an event with only exdates or rdates values, without specifying an rrules results in no events being created. The same behavior can be observed with the storetodos.wcap command.
The following example shows an rrules parameter that specifies the event is to occur daily for 10 instances (COUNT=10;FREQ=DAILY):
rrules="count%3D10%3Bfreq%3Ddaily" |
The following example URL passes the example rrules parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rrules="count%3D10%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
The rdates parameter takes a semicolon-separated list of date-time specifications where each date-time gives a recurrence date of the event.
For example, the following rdates parameter specifies a recurring event with two recurrence dates (3/31/02 11:22:33 and 5/31/02 11:22:33):
rdates=20020331T112233;20020531T112233 |
The following example URL passes the rdates parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rdates=20020331T112233;20020531T112233 &dtend=20020301T112233 &summary=uuuu |
If you want to the change the recurrence rule after a certain date, you must set rchange to 1.
The exrules parameter takes a semicolon-separated list of quoted recurrence rule strings where each rule is an excluded recurrence of the event.
For example, the following exrules parameter specifies a recurring event that does not recur at the times specified by the two rules:
exrules="count%3D10%3Bfreq%3Ddaily";"freq%3Dweekly%3Bcount%3D4" |
The first rule is for the event not to occur daily for 10 instances. The second rule is for the event not to occur weekly for 4 instances (COUNT=10;FREQ=DAILY and FREQ=WEEEKLY;COUNT=4).
The following example URL passes the example exrules parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &exrules="count%3D10%3Bfreq%3Ddaily"; "freq%3Dweekly%3Bcount%3D4" &rrules="count%3D100%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
The exdates parameter takes a semicolon-separated list of date-time specifications. Each date-time represents an excluded date of the event.
For example, the following exdates parameter specifies a recurring event that does not occur on the two specified dates (3/31/02 11:22:33 and 5/31/02 11:22:33):
exdates=20020331T112233;20020531T112233 |
The following example URL passes the example exdates parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &exdates=20020331T112233;20020531T112233 &rrules="count%3D200%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
This parameter specifies a unique recurrence date of an event or todo. Use rid in conjunction with the mod parameter to specify a range of events and todos to be modified.
For example:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rid=20020331T112233 &dtend=20020301T112233 &summary=uuuu&mod=1 |
For a non-recurring event or todo, the rid is 0.
When modifying recurring components, this parameter specifies whether to apply the changes to one or more instances of the event or todo. The following settings are mapped, but currently only the values 1 and 4 are honored. If 2 or 3 are specified, in certain cases they are mapped to 4.
Value |
Option |
1 |
This instance only. |
2 |
This and all future instances. |
3 |
This and all prior instances. |
4 |
This and all instances. |
When creating or modifying a recurring component, if changing rrules is allowed (rchange is set to 1), the system assumes a setting of 4, which causes the entire series of events or todos to be deleted and rewritten. If 2 or 3 are specified when trying to change rules or start times, they are mapped to 4. If 2 or 3 is specified for changing a summary or description, the setting are honored, but no exceptions are created for errors.
The rchange parameter specifies whether recurrences are expanded in Command: storeevents, and Command: storetodos. Normally, events and todos calendar components are not expanded, so the parameter defaults to 0, which implies the series is recreated.
However, you might not want to expand recurrences when you are modifying multiple events. For example, suppose a meeting recurs every Friday starting Jan. 1, 2002. Use the following URL to change the summary of each event after Feb. 1, 2002 to changed-event.
The following example sets the rchange parameter to 0, to make the modification without adding additional events:
http://webcalendarserver/storeevents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=abcxyz &dtstart=20020201T112233Z &rrules="byday%3Dfr%3Bfreq%3Dweekly" &summary=changed-event &rid=20020201T112233Z &mod=2 &rchange=0 |
Note that when you are modifying a recurrence series, do not pass in rrules unless you are trying to recreate the series with a new rule.
When creating a recurring series according to the rrule, this integer specifies whether to include the dtstart date if the date does not follow the rrules. For example, if on a Monday, you were creating a recurring series of meetings that were to be held every Wednesday, the dtstart would be Monday, but that does not fit the set of dates (all Wednesdays) generated using the rrules. Therefore the server must decide whether to include the dtstart date or not based on the value of excludedtstart.
A value of 0 indicates the dtstart date is included in the recurring series and a value of 1 indicates the dtstart date is not included in the recurring series. The default is 0.