RecurrenceExceptionRule Property
Defines a rule or repeating pattern for an exception to the recurrence set.
Syntax
caldav.getRecurrenceExceptionRule([callback]) caldav.setRecurrenceExceptionRule( recurrenceExceptionRule, [callback])
Default Value
""
Callback
The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).
The callback for the getRecurrenceExceptionRule([callback]) method is defined as:
function(err, data){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'data' is the value returned by the method.
The callback for the setRecurrenceExceptionRule([callback]) method is defined as:
function(err){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'err' has 2 properties which hold detailed information:
err.code err.message
Remarks
Defines a rule or repeating pattern for an exception to the recurrence set.
If the RecurrenceExceptionDates and RecurrenceExceptionRule are specified, they are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial StartDate property along with the RecurrenceRule, RecurrenceDates, RecurrenceExceptionRule, and RecurrenceExceptionDates properties contained within the recurring event. The StartDate property defines the first instance in the recurrence set. The starting date SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a start date that doesn't match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified RecurrenceRule and RecurrenceDates properties, and then excluding any start DATE-TIME values specified by the RecurrenceExceptionRule or RecurrenceExceptionDates properties. This implies that DATE-TIME values specified by the RecurrenceExceptionRule and RecurrenceExceptionDates properties take precedence over those specified by inclusion properties (i.e., RecurrenceDates and RecurrenceRule). When duplicate instances are generated by the recurrence RecurrenceRule and RecurrenceDates properties, only one recurrence is considered. Duplicate instances are ignored.
This value type is a structured value consisting of a list of one or more recurrence grammar parts. Each rule part is defined by a NAME=VALUE pair. The rule parts are separated from each other by the SEMICOLON character. The rule parts are not ordered in any particular sequence. Individual rule parts MUST only be specified once.
The table below shows the supported rules and their usage.
| FREQ | The FREQ rule part identifies the type of recurrence rule. This rule part MUST be specified in the recurrence rule. Valid values include SECONDLY, to specify repeating events based on an interval of a second or more; MINUTELY, to specify repeating events based on an interval of a minute or more; HOURLY, to specify repeating events based on an interval of an hour or more; DAILY, to specify repeating events based on an interval of a day or more; WEEKLY, to specify repeating events based on an interval of a week or more; MONTHLY, to specify repeating events based on an interval of a month or more; and YEARLY, to specify repeating events based on an interval of a year or more. |
| UNTIL | The UNTIL rule part defines a DATE (YYYYMMDD) or DATE-TIME (YYYYMMDDThhmmss) value that bounds the recurrence rule in an inclusive manner. If the value specified by UNTIL is synchronized with the specified recurrence, this DATE or DATE-TIME becomes the last instance of the recurrence. The value of the UNTIL rule part MUST have the same value type as the StartDate property. Furthermore, if the StartDate is specified as a date with local time, then the UNTIL rule part MUST also be specified as a date with local time. If the StartDate property is specified as a date with UTC time or a date with local time and time zone reference, then the UNTIL rule part MUST be specified as a date with UTC time. If not present, and the COUNT rule part is also not present, the "RecurrenceRule" is considered to repeat forever. |
| COUNT | The COUNT rule part defines the number of occurrences at which to range-bound the recurrence. The StartDate property value always counts as the first occurrence. |
| INTERVAL | Positive integer representing at which intervals the recurrence rule repeats. The default value is "1", meaning every second for a SECONDLY rule, every minute for a MINUTELY rule, every hour for an HOURLY rule, etc. For example, within a DAILY rule, a value of "8" means every eight days. |
| BYSECOND | The BYSECOND rule part specifies a COMMA-separated list of seconds within a minute. Valid values are 0 to 60. |
| BYMINUTE | The BYMINUTE rule part specifies a COMMA-separated list of minutes within an hour. Valid values are 0 to 59. |
| BYHOUR | The BYHOUR rule part specifies a COMMA-separated list of hours of the day. Valid values are 0 to 23. |
| BYDAY | The BYDAY rule part specifies a COMMA-separated list of days of the week; SU indicates Sunday; MO indicates Monday; TU indicates Tuesday; WE indicates Wednesday; TH indicates Thursday; FR indicates Friday; and SA indicates Saturday. Each BYDAY value can also be preceded by a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of a specific day within the MONTHLY or YEARLY RecurrenceRule. |
| BYMONTHDAY | The BYMONTHDAY rule part specifies a COMMA-separated list of days of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 represents the tenth to the last day of the month. The BYMONTHDAY rule part MUST NOT be specified when the FREQ rule part is set to WEEKLY. |
| BYYEARDAY | The BYYEARDAY rule part specifies a COMMA-separated list of days of the year. Valid values are 1 to 366 or -366 to -1. For example, -1 represents the last day of the year (December 31st) and -306 represents the 306th to the last day of the year (March 1st). The BYYEARDAY rule part MUST NOT be specified when the FREQ rule part is set to DAILY, WEEKLY, or MONTHLY. |
| BYWEEKNO | The BYWEEKNO rule part specifies a COMMA-separated list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. This corresponds to weeks according to week numbering as defined in ISO.8601.2004. A week is defined as a seven day period, starting on the day of the week defined to be the week start (see WKST). Week number one of the calendar year is the first week that contains at least four (4) days in that calendar year. This rule part MUST NOT be used when the FREQ rule part is set to anything other than YEARLY. For example, 3 represents the third week of the year. |
| BYMONTH | The BYMONTH rule part specifies a COMMA-separated list of months of the year. Valid values are 1 to 12. |
| WKST | Specifies the day on which the workweek starts. Valid values are MO, TU, WE, TH, FR, SA, and SU. This is significant when a WEEKLY RecurrenceRule has an interval greater than 1, and a BYDAY rule part is specified. This is also significant when in a YEARLY RecurrenceRule when a BYWEEKNO rule part is specified. The default value is MO. |
| BYSETPOS | The BYSETPOS rule part specifies a COMMA-separated list of values that corresponds to the nth occurrence within the set of recurrence instances specified by the rule. BYSETPOS operates on a set of recurrence instances in one interval of the recurrence rule. For example, in a WEEKLY rule, the interval would be one week A set of recurrence instances starts at the beginning of the interval defined by the FREQ rule part. Valid values are 1 to 366 or -366 to -1. It MUST only be used in conjunction with another BYxxx rule part. For example "the last work day of the month" could be represented as: FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1. Each BYSETPOS value can include a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of the specific occurrence within the set of occurrences specified by the rule. |
Information not contained in the RecurrenceRule necessary to determine the various recurrence instance start time and dates are derived from the StartDate property. For example, "FREQ=YEARLY;BYMONTH=1" doesn't specify a specific day within the month or a time. This information would be the same as what is specified for the StartDate property.
BYxxx rule parts modify the recurrence in some manner. BYxxx rule parts for a period of time that is the same or greater than the frequency generally reduce or limit the number of occurrences of the recurrence generated. For example, "FREQ=DAILY;BYMONTH=1" reduces the number of recurrence instances from all days (if BYMONTH rule part is not present) to all days in January. BYxxx rule parts for a period of time less than the frequency generally increase or expand the number of occurrences of the recurrence. For example, "FREQ=YEARLY;BYMONTH=1,2" increases the number of days within the yearly recurrence set from 1 (if BYMONTH rule part is not present) to 2.
If multiple BYxxx rule parts are specified, then after evaluating the specified FREQ and INTERVAL rule parts, the BYxxx rule parts are applied to the current set of evaluated occurrences in the following order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYHOUR, BYMINUTE, BYSECOND and BYSETPOS; then COUNT and UNTIL are evaluated.
This property is filled after retrieving a calendar event, and is also used to create an event to put on the server. However, when requesting a report the contents of this property will only be valid inside the CalDAV EventDetails event.
Data Type
String