diff options
Diffstat (limited to 'vendor/sabre/dav/docs/caldav-notifications.txt')
-rw-r--r-- | vendor/sabre/dav/docs/caldav-notifications.txt | 1568 |
1 files changed, 1568 insertions, 0 deletions
diff --git a/vendor/sabre/dav/docs/caldav-notifications.txt b/vendor/sabre/dav/docs/caldav-notifications.txt new file mode 100644 index 000000000..75c2e5e07 --- /dev/null +++ b/vendor/sabre/dav/docs/caldav-notifications.txt @@ -0,0 +1,1568 @@ + + + +Calendar Server Extension C. Daboo + Apple Inc. + March 19, 2012 + + + CalDAV: Calendar User Notifications + +Abstract + + This specification defines an extension to CalDAV that allows the + server to provide notifications to calendar users. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo [Page 1] + + CalDAV User Notifications March 2012 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 4. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 3 + 4.1. Additional Principal Properties . . . . . . . . . . . . . 4 + 4.1.1. CS:notification-URL Property . . . . . . . . . . . . . 5 + 4.2. Properties on Notification Resources . . . . . . . . . . . 5 + 4.2.1. CS:notificationtype Property . . . . . . . . . . . . . 5 + 4.3. XML Element Definitions . . . . . . . . . . . . . . . . . 6 + 4.3.1. CS:notifications . . . . . . . . . . . . . . . . . . . 6 + 4.3.2. CS:notification . . . . . . . . . . . . . . . . . . . 6 + 4.3.3. CS:dtstamp . . . . . . . . . . . . . . . . . . . . . . 7 + 5. Notification Definitions . . . . . . . . . . . . . . . . . . . 7 + 5.1. System Status Notification . . . . . . . . . . . . . . . . 7 + 5.1.1. CS:systemstatus Element Definition . . . . . . . . . . 8 + 5.2. Quota Notification . . . . . . . . . . . . . . . . . . . . 8 + 5.2.1. CS:quotastatus Element Definition . . . . . . . . . . 9 + 5.3. Resource Changes Notification . . . . . . . . . . . . . . 10 + 5.3.1. CS:resource-change Element Definition . . . . . . . . 11 + 5.3.2. CS:calendar-changes Element Definition . . . . . . . . 15 + 5.3.2.1. Handling Recurrences in CS:calendar-changes . . . 17 + 5.3.3. CS:deleted-details Element Definition . . . . . . . . 18 + 5.3.4. CS:notify-changes Property . . . . . . . . . . . . . . 20 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 + 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 21 + Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21 + A.1. Resource Created . . . . . . . . . . . . . . . . . . . . . 21 + A.2. Resource Updated - Property Change . . . . . . . . . . . . 22 + A.3. Resource Updated - Parameter Change . . . . . . . . . . . 23 + A.4. Resource Updated - Multiple Instances Change . . . . . . . 23 + A.5. Resource Updated - Multiple User Change . . . . . . . . . 24 + A.6. Resource Deleted . . . . . . . . . . . . . . . . . . . . . 25 + A.7. Collection Created . . . . . . . . . . . . . . . . . . . . 26 + A.8. Collection Updated . . . . . . . . . . . . . . . . . . . . 26 + A.9. Collection Deleted . . . . . . . . . . . . . . . . . . . . 27 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 27 + + + + + + + + + +Daboo [Page 2] + + CalDAV User Notifications March 2012 + + +1. Introduction + + CalDAV [RFC4791] provides a way for calendar users to store calendar + data and exchange this data via scheduling operations. Based on the + WebDAV [RFC4918] protocol, it also includes the ability to manage + access to calendar data via the WebDAV ACL [RFC3744] extension. + + It is often useful for servers to communicate arbitrary information + to calendar users, e.g., system status, message of the day, quota + warnings, changes to shared resources made by others etc. This + specification defines a generic "notification" mechanism that allows + a server to do that. Whilst primarily aimed at CalDAV [RFC4791], + this mechanism has been designed to be adaptable to WebDAV [RFC4918]. + + +2. Open Issues + + 1. Define specific child elements for system status notification, + e.g. "server-maintenance-period", "server-read-only-period", + "client-upgrade-required". + + +3. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + When XML element types in the namespaces "DAV:" and + "urn:ietf:params:xml:ns:caldav" are referenced in this document + outside of the context of an XML fragment, the string "DAV:" and + "CALDAV:" will be prefixed to the element type names respectively. + + The namespace "http://calendarserver.org/ns/" is used for XML + elements defined in this specification. When XML element types in + that namespace are referenced in this document outside of the context + of an XML fragment, the string "CS:" will be prefixed to the element + type names. + + +4. Notifications + + When this feature is available, a CS:notification-URL (Section 4.1.1) + property appears on principal resources for those principals who are + able to receive notifications. That property specifies a single DAV: + href element whose content refers to a WebDAV collection resource. + Notification "messages" are deposited into this collection and can be + retrieved by clients and acted on accordingly. + + + +Daboo [Page 3] + + CalDAV User Notifications March 2012 + + + The notification collection referenced by the CS:notification-URL + (Section 4.1.1) property MUST have a DAV:resourcetype property with + DAV:collection and CS:notifications (Section 4.3.1) child elements. + + Notification "messages" are XML documents stored as resources in the + notification collection. Each XML document contains a CS: + notification (Section 4.3.2) element as its root. The root element + contains a CS:dtstamp element, and one additional element which + represents the type of notification being conveyed in the message. + That child element will typically contain additional content that + describes the notification. + + Each notification resource has a CS:notificationtype (Section 4.2.1) + property which contains as its single child element an empty element + that matches the child element of the notification resource XML + document root. Any attributes on the child element in the XML + document are also present in the property child element. + + Notifications are automatically generated by the server (perhaps in + response to a action) with an appropriate resource stored in the + notifications collection of the user to whom the notification is + targeted. Clients SHOULD monitor the notification collection looking + for new notification resources. When doing so, clients SHOULD look + at the CS:notificationtype (Section 4.2.1) property to ensure that + the notification is of a type that the client can handle. Once a + client has handled the notification in whatever way is appropriate it + SHOULD delete the notification resource. Clients SHOULD remove + notifications being displayed to a user when the notification + resource is removed from the notification collection, to enable the + user to dismiss a notification on one device and have it + automatically removed from others. Clients MUST ignore all + notifications for types they do not recognize. Servers MAY delete + notification resources on their own if they determine that the + notifications are no longer relevant or valid. Servers MAY coalesce + notifications as appropriate. + + Servers MUST prevent clients from adding resources in the + notification collection. + +4.1. Additional Principal Properties + + This section defines new properties for WebDAV principal resources as + defined in RFC3744 [RFC3744]. These properties are likely to be + protected but the server MAY allow them to be written by appropriate + users. + + + + + + +Daboo [Page 4] + + CalDAV User Notifications March 2012 + + +4.1.1. CS:notification-URL Property + + Name: notification-URL + + Namespace: http://calendarserver.org/ns/ + + Purpose: Identify the URL of the notification collection owned by + the associated principal resource. + + Protected: This property SHOULD be protected. + + PROPFIND behavior: This property SHOULD NOT be returned by a + PROPFIND allprop request (as defined in Section 14.2 of + [RFC4918]). + + COPY/MOVE behavior: This property value SHOULD be preserved in COPY + and MOVE operations. + + Description: This property is needed for a client to determine where + the notification collection of the current user is located so that + processing of notification messages can occur. If not present, + then the associated calendar user is not enabled for notification + messages on the server. + + Definition: + + <!ELEMENT notification-URL (DAV:href)> + +4.2. Properties on Notification Resources + + The following new WebDAV properties are defined for notification + resources. + +4.2.1. CS:notificationtype Property + + Name: notificationtype + + Namespace: http://calendarserver.org/ns/ + + Purpose: Identify the type of notification of the corresponding + resource. + + Protected: This property MUST be protected. + + PROPFIND behavior: This property SHOULD NOT be returned by a + PROPFIND allprop request (as defined in Section 14.2 of + [RFC4918]). + + + + +Daboo [Page 5] + + CalDAV User Notifications March 2012 + + + COPY/MOVE behavior: This property value MUST be preserved in COPY + and MOVE operations. + + Description: This property allows a client, via a PROPFIND Depth:1 + request, to quickly find notification messages that the client can + handle in a notification collection. The single child element is + the notification resource root element's child defining the + notification itself. This element MUST be empty, though any + attributes on the element in the notification resource MUST be + present in the property element. + + Definition: + + <!ELEMENT notificationtype ANY> + <!-- Child elements are empty but will have appropriate attributes. + Any valid notification message child element can appear.--> + +4.3. XML Element Definitions + +4.3.1. CS:notifications + + Name: notifications + + Namespace: http://calendarserver.org/ns/ + + Purpose: Indicates a notification collection. + + Description: This XML element is used in a DAV:resourcetype element + to indicate that the corresponding resource is a notification + collection. + + Definition: + + <!ELEMENT notifications EMPTY> + +4.3.2. CS:notification + + Name: notification + + Namespace: http://calendarserver.org/ns/ + + Purpose: Notification message root element. + + Description: The root element used in notification resources. + + + + + + + +Daboo [Page 6] + + CalDAV User Notifications March 2012 + + + Definition: + + <!ELEMENT notification (dtstamp, XXX) > + <!-- Any notification type element can appear after + CS:dtstamp --> + +4.3.3. CS:dtstamp + + Name: dtstamp + + Namespace: http://calendarserver.org/ns/ + + Purpose: Date-time stamp. + + Description: Contains the date-time stamp corresponding to the + creation of a notification message, using the format defined in + [RFC3339], or the "compact" format without "-" and ":" characters + between date and time elements, respectively. + + Definition: + + <!ELEMENT dtstamp (#PCDATA)> + <!-- Value is a date-time in UTZ as per [RFC3339] with + "compact" format allowed.--> + + +5. Notification Definitions + + This section defines a set of common notification types. + +5.1. System Status Notification + + The system status notification is used to convey a URI and/or textual + description to the user. The assumption is that the URI points to a + webpage where current system status is described in detail, with the + provided description being a summary of that. A "type" attribute on + the element is used to indicate the importance of the current status + notification, and has the values "low", "medium" and "high", + representing the increasing level of importance of the message + respectively. + + Servers might have knowledge of specific calendar user language + preferences, in which case it MAY localise the CS:description value + as appropriate based on the calendar user accessing the notification, + but if it does, it SHOULD include an xml:lang attribute on the CS: + description element to indicate what language is being used. + + + + + +Daboo [Page 7] + + CalDAV User Notifications March 2012 + + +5.1.1. CS:systemstatus Element Definition + + Name: systemstatus + + Namespace: http://calendarserver.org/ns/ + + Purpose: Indicates a system status notification. + + Description: This XML element is used in a CS:notification element + to describe a system status notification. + + Definition: + + <!ELEMENT systemstatus (DAV:href?, CS:description?)> + <!ATTLIST systemstatus type (low | medium | high) "low"> + + <!ELEMENT description CDATA> + + <!-- One of DAV:href of CS:description MUST be present --> + + Example: This is an example of the body of a notification resource + for an emergency system outage: + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:12:53-05:00</CS:dtstamp> + <CS:systemstatus type="high"> + <D:href>http://example.com/emergency_shutdown.html</D:href> + <CS:description xml:lang='en_US' + >Emergency shutdown now</CS:description> + </CS:systemstatus> + </CS:notification> + + Example: This is an example of the WebDAV property on the example + notification resource above: + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notificationtype xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:systemstatus type="high" /> + </CS:notificationtype> + +5.2. Quota Notification + + The quota notification is used to convey information about the status + of one or more quotas for the user. The notification contains + elements for different types of quota being reported to the user. In + + + +Daboo [Page 8] + + CalDAV User Notifications March 2012 + + + some cases these may be warnings (e.g., a user getting to 80% of + their quota limit), or in other cases errors (e.g., a user exceeding + their quota). + +5.2.1. CS:quotastatus Element Definition + + Name: quotastatus + + Namespace: http://calendarserver.org/ns/ + + Purpose: Indicates a quota status notification. + + Description: This XML element is used in a CS:notification element + to describe a quota status notification. The CS:quota-percent- + used element contains an integer greater than or equal to zero. + If the value is greater than or equal to 100, then the user's + quota has been reached or exceeded. The DAV:href element contains + a URI for a webpage where the user can go to get further + information about their quota status or take corrective action. + + Definition: + + <!ELEMENT quota-status (quota+)> + + <!ELEMENT quota (quota-type, quota-percent-used?, + quota-count?, DAV:href?)> + <!ATTLIST quota type (warning | exceeded) "exceeded"> + + <!ELEMENT quota-type ANY> + <!-- Child elements are application specific --> + + <!ELEMENT quota-percent-used CDATA> + <!-- Integer value greater than or equal to zero --> + + <!ELEMENT quota-count CDATA> + <!-- Integer value greater than or equal to zero --> + + Example: This is an example of the body of a notification resource + for a quota warning: + + + + + + + + + + + + +Daboo [Page 9] + + CalDAV User Notifications March 2012 + + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:12:53-05:00</CS:dtstamp> + <CS:quota-status> + <CS:quota type="warning"> + <CS:quota-type><CS:attachments /></CS:quota-type> + <CS:quota-percent-used>80</CS:quota-percent-used> + <D:href>https://example.com/your-account.html</D:href> + </CS:quota> + </CS:quota-status> + </CS:notification> + + Example: This is an example of the body of a notification resource + for a quota that has been exceeded, and a count-based limit that + is shown as a warning: + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:12:53-05:00</CS:dtstamp> + <CS:quota-status> + <CS:quota type="exceeded"> + <CS:quota-type><CS:attachments /></CS:quota-type> + <CS:quota-percent-used>102</CS:quota-percent-used> + <D:href>https://example.com/fix-account.html</D:href> + </CS:quota> + <CS:quota type="warning"> + <CS:quota-type><CS:events /></CS:quota-type> + <CS:quota-percent-used>82</CS:quota-percent-used> + <CS:quota-count>4980</CS:quota-count> + <D:href>https://example.com/buy-more-space.html</D:href> + </CS:quota> + </CS:quota-status> + </CS:notification> + +5.3. Resource Changes Notification + + The resource change notification is used to inform the user of new, + updated or deleted resources caused by changes made by someone else + (note: servers MUST NOT generate notifications to users for changes + they themselves make, though the possibility of an automated process + acting on behalf of a user needs to be considered). This + notification can be used by clients to show changes that a user can + acknowledge in their own time. When the notification is present, it + can be displayed on all devices a user is accessing their data from. + When the user acknowledges and dismisses the notification on one + device, other devices SHOULD also remove the notification when they + + + +Daboo [Page 10] + + CalDAV User Notifications March 2012 + + + next synchronize the notification collection. + + A new WebDAV property CS:notify-changes (Section 5.3.4) is defined + for calendar collections. This allows users to enable or disable the + sending of resource change notifications for the calendar and its + child resources. Servers MUST allow users to set this property on a + per-user basis on any calendars accessible to them. Servers MUST + honor the chosen setting to enable or disable change notifications. + + Servers can send notifications for calendar object resources, and + ones for calendar collections. Servers SHOULD coalesce notifications + that refer to the same resource into a single notification resource, + containing multiple CS:created, CS:updated or CS:deleted elements all + with the same DAV:href child element value. Servers MAY coalesce + changes to multiple resources into a change notification for the + parent collection of those resources and use a CS:collection-changes + element to indicate the number of individual resources that changed. + +5.3.1. CS:resource-change Element Definition + + Name: resource-change + + Namespace: http://calendarserver.org/ns/ + + Purpose: Indicates that resources have been created, updated or + deleted. + + Description: This XML element is used in a CS:notification element + to describe a resource change notification. It can describe a + change directly to a calendar object resource or to a calendar + collection. + + When used for a calendar object resource change, it can contain + one of the CS:created, or CS:deleted elements, or multiple CS: + updated elements, which indicate a created, deleted or updated + resource, respectively. The DAV:href element within those + elements, contains the URI of the changed resource, optional + information about who changed the resource and when that change + was made (the CS:changed-by element), and information specific to + the nature of the change. Servers SHOULD coalesce resource change + notifications for the same resource into a single notification + resource where possible. The CS:updated element optionally + contains CS:content and/or DAV:prop elements to indicate a change + to the body of the resource or resource WebDAV properties, + respectively. The DAV:prop element MAY contain a list of property + elements to indicate which properties changed. The CS:updated + element can also contain zero or more CS:calendar-changes elements + to list details of the changes. If no CS:calendar-changes element + + + +Daboo [Page 11] + + CalDAV User Notifications March 2012 + + + is present, the specific details are not provided, and clients + will need to assume that some set of changes occurred, but the + server is unwilling to disclose the full details. The CS:deleted + element can also contain zero or more CS:deleted-details elements + to list details of the deleted resource. + + When used for a calendar collection change, it can contain a CS: + collection-changes element. The DAV:href element within that + element, contains the URI of the changed calendar collection. The + DAV:prop element indicates a change to WebDAV properties on the + calendar collection resource. The CS:child-created, CS:child- + updated, and CS:child-deleted elements each contain a positive + integer value indicating how many child resources were added, + updated or deleted in the collection, respectively. + + Definition: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo [Page 12] + + CalDAV User Notifications March 2012 + + + <!ELEMENT resource-change (created | updated+ | deleted | + collection-changes)> + <!ELEMENT created (DAV:href, changed-by?, ANY)> + <!ELEMENT updated (DAV:href, changed-by?, content?, + DAV:prop?, calendar-changes*)> + <!ELEMENT content EMPTY> + <!ELEMENT deleted (DAV:href, changed-by?, deleted-details)> + + <!ELEMENT changed-by (common-name | (first-name, last-name), + dtstamp?, DAV:href)> + <!ELEMENT common-name CDATA> + <!ELEMENT first-name CDATA> + <!ELEMENT last-name CDATA> + <!-- CS:changed-by indicates who made the change that caused the + notification. CS:first-name and CS:last-name are the first + and last names of the corresponding user. or the + CS:common-name is the overall display name. CS:dtstamp is the + time in UTC when the change was made. The DAV:href element + is the principal URI or email address of the user who made + the change. --> + + <!ELEMENT collection-changes (DAV:href, changed-by*, DAV:prop?, + child-created?, child-updated?, + child-deleted?> + <!-- When coalescing changes from multiple users, the changed-by + element can appear more than once. --> + + <!ELEMENT child-created CDATA> + <!ELEMENT child-updated CDATA> + <!ELEMENT child-deleted CDATA> + <!-- Each of the three elements above MUST contain a positive, + non-zero integer value indicate the total number of changes + being reported for the collection. --> + + Example: This is an example of the body of a notification resource + for changes where one resource has been created: + + + + + + + + + + + + + + + +Daboo [Page 13] + + CalDAV User Notifications March 2012 + + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:created> + <D:href>http://example.com/cyrus/calendar/new.ics</D:href> + <CS:changed-by> + <CS:common-name>Cyrus Daboo</CS:common-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + </CS:created> + </CS:resource-change> + </CS:notification> + + Example: This is an example of the body of a notification resource + for changes where a resource has been updated twice. One of the + updated resources elements contains additional information + indicating which recurrence instances in the iCalendar data were + changed: + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:updated> + <D:href>http://example.com/cyrus/calendar/event.ics</D:href> + <CS:changed-by> + <CS:first-name>Oliver</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>mailto:oliver@example.com</D:href> + </CS:changed-by> + </CS:updated> + <CS:updated> + <D:href>http://example.com/cyrus/calendar/event.ics</D:href> + <CS:changed-by> + <CS:first-name>Eleanor</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>mailto:eleanor@example.com</D:href> + </CS:changed-by> + </CS:updated> + </CS:resource-change> + </CS:notification> + + + + + + + +Daboo [Page 14] + + CalDAV User Notifications March 2012 + + + Example: This is an example of the body of a notification resource + for changes where one resource has been deleted: + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:deleted> + <D:href>http://example.com/cyrus/calendar/old.ics</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + </CS:deleted> + </CS:resource-change> + </CS:notification> + + Example: This example is the same as the previous three, except that + all the individual resource changes have been coalesced into a + single notification about changes to the parent calendar + collection: + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:collection-changes> + <D:href>http://example.com/cyrus/calendar/</D:href> + <CS:child-created>1</CS:child-created> + <CS:child-updated>2</CS:child-updated> + <CS:child-deleted>1</CS:child-deleted> + </CS:collection-changes> + </CS:resource-change> + </CS:notification> + +5.3.2. CS:calendar-changes Element Definition + + Name: calendar-changes + + Namespace: http://calendarserver.org/ns/ + + Purpose: Indicates which portions of an calendar object resource + have changed, or provides details of deleted calendar object + resources. + + + + +Daboo [Page 15] + + CalDAV User Notifications March 2012 + + + Description: This XML element is used in a CS:updated element to + describe how a calendar object resource changed, or in a CS: + deleted element to provide details of a deleted resource. It can + identify the master instance, or individual recurrence instances, + and for each indicate which iCalendar properties and parameters + changed during the update for which the notification was + generated. For details of handling recurrences please see + Section 5.3.2.1. + + Definition: + + <!ELEMENT calendar-changes (recurrence+) > + + <!ELEMENT recurrence + ((master | recurrenceid), added?, removed?, changes?)> + <!-- Which instances were affected by the change, + and details on the per-instance changes --> + + <!ELEMENT master EMPTY> + <!-- The "master" instance was affected --> + + <!ELEMENT recurrenceid CDATA> + <!-- RECURRENCE-ID value in iCalendar form (in UTC if a + non-floating DATE-TIME value) for the affected instance --> + + <!ELEMENT added EMPTY> + <!-- The component was added --> + + <!ELEMENT removed EMPTY> + <!-- The component was removed --> + + <!ELEMENT changes changed-property*> + <!-- Detailed changes in the iCalendar data --> + + <!ELEMENT changed-property changed-parameter*> + <!ATTLIST changed-property name PCDATA> + <!-- An iCalendar property changed --> + + <!ELEMENT changed-parameter EMPTY> + <!ATTLIST changed-parameter name PCDATA> + <!-- An iCalendar property parameter changed --> + + Example: This example indicates that a non-recurring component, or + the master component in a recurring component, was changed and + that the change was to the "SUMMARY" iCalendar property. + + + + + + +Daboo [Page 16] + + CalDAV User Notifications March 2012 + + + <CS:calendar-changes xmlns:CS="http://calendarserver.org/ns/"> + <CS:recurrence> + <CS:master/> + <CS:changes> + <CS:changed-property name="SUMMARY"/> + </CS:changes> + </CS:recurrence> + </CS:calendar-changes> + + Example: This example indicates that an instance of a recurring + component was changed and that the change was to the "DTSTART" + iCalendar property. + + <CS:calendar-changes xmlns:CS="http://calendarserver.org/ns/"> + <CS:recurrence> + <CS:recurrenceid>20111215T160000Z</CS:recurrenceid> + <CS:changes> + <CS:changed-property name="DTSTART"/> + </CS:changes> + </CS:recurrence> + </CS:calendar-changes> + +5.3.2.1. Handling Recurrences in CS:calendar-changes + + Changes to recurring components can be complex. This section + describes the possible set of changes that could occur, and what the + CS:calendar-changes element will contain as a result. + + Master exists, unchanged override added In this case, a CS: + recurrence element will be present, containing a CS:recurrence-id + element with a value equal to the RECURRENCE-ID property value (in + UTC) of the added component. A CS:added element will be present. + There will not be any CS:removed or CS:changes elements. + + Master exists, changed override added In this case, a CS:recurrence + element will be present, containing a CS:recurrence-id element + with a value equal to the RECURRENCE-ID property value (in UTC) of + the added component. Both CS:added and CS:changes elements will + be present. There will not be a CS:removed element. + + Master exists, override changed In this case, a CS:recurrence + element will be present, containing a CS:recurrence-id element + with a value equal to the RECURRENCE-ID property value (in UTC) of + the added component. A CS:changes element will be present. There + will not be any CS:added or CS:removed elements. + + + + + + +Daboo [Page 17] + + CalDAV User Notifications March 2012 + + + Master exists, override removed In this case, a CS:recurrence + element will be present, containing a CS:recurrence-id element + with a value equal to the RECURRENCE-ID property value (in UTC) of + the added component. A CS:removed element will be present. There + will not be a CS:added element. A CS:changes element will only be + present if the removed component differs from the "derived" master + instance. + + Master exists, override cancelled In this case, a CS:recurrence + element will be present, containing a CS:recurrence-id element + with a value equal to the RECURRENCE-ID property value (in UTC) of + the added component. A CS:removed element will be present. There + will not be any CS:added or CS:changes element. There will also + be a CS:master element present, with an appropriate CS:changes + element, likely covering a change to "RRULE" or addition of + "EXDATE" properties. + + Master does not exist, override added In this case, a CS:recurrence + element will be present, containing a CS:recurrence-id element + with a value equal to the RECURRENCE-ID property value (in UTC) of + the added component. A CS:added element will be present. There + will not be a CS:removed or CS:changes element. + + Master does not exist, override changed In this case, a CS: + recurrence element will be present, containing a CS:recurrence-id + element with a value equal to the RECURRENCE-ID property value (in + UTC) of the added component. A CS:changes element will be + present. There will not be any CS:added or CS:removed elements. + + Master does not exist, override removed In this case, a CS: + recurrence element will be present, containing a CS:recurrence-id + element with a value equal to the RECURRENCE-ID property value (in + UTC) of the added component. A CS:removed element will be + present. There will not be any CS:added or CS:changes element. + +5.3.3. CS:deleted-details Element Definition + + Name: deleted-details + + Namespace: http://calendarserver.org/ns/ + + Purpose: Provides summary information about a deleted resource or + collection. + + Description: This XML element is used in a CS:deleted element to + describe useful information about a deleted resource or + collection, so clients can provide a meaningful notification + message to users. This element has two variants: one for deletion + + + +Daboo [Page 18] + + CalDAV User Notifications March 2012 + + + of a calendar object resource, the other for deletion of a + calendar collection. + + Definition: + + <!ELEMENT deleted-details ((deleted-component, + deleted-summary, + deleted-next-instance?, + deleted-had-more-instances?) | + deleted-displayname)> + <!-- deleted-displayname is used for a collection delete, the other + elements used for a resource delete. --> + + <!ELEMENT deleted-component CDATA> + <!-- The main calendar component type of the deleted + resource, e.g., "VEVENT", "VTODO" --> + + <!ELEMENT deleted-summary CDATA> + <!-- Indicates the "SUMMARY" of the next future instance at the + time of deletion, or the previous instance if no future + instances existed at the time of deletion. --> + + <!ELEMENT deleted-next-instance CDATA> + <!ATTLIST deleted-next-instance tzid PCDATA> + <!-- If present, indicates when the next deleted instance would + have occurred. For a VEVENT that would be the DTSTART value, + for a VTODO that would be either DTSTART or DUE, if present. + In each case the value must match the value in the iCalendar + data, and any TZID iCalendar property parameter value must + be included in the tzid XML element attribute value. --> + + <!ELEMENT deleted-had-more-instances EMPTY> + <!-- If present indicates that there was more than one future + instances still to occur at the time of deletion. --> + + <!ELEMENT deleted-displayname CDATA> + <!-- The DAV:getdisplayname property for the collection that + was deleted. --> + + Example: This example indicates deletion of a non-recurring event + that was yet to occur at the time of deletion. + + <CS:deleted-details xmlns:CS="http://calendarserver.org/ns/"> + <CS:deleted-component>VEVENT</CS:deleted-component> + <CS:deleted-summary>Birthday Party</CS:deleted-summary> + <CS:deleted-next-instance tzid="America/New_York + >20120505T120000</CS:deleted-next-instance> + </CS:deleted-details> + + + +Daboo [Page 19] + + CalDAV User Notifications March 2012 + + + Example: This example indicates deletion of a calendar. + + <CS:deleted-details xmlns:CS="http://calendarserver.org/ns/"> + <CS:deleted-displayname>Holidays</CS:deleted-displayname> + </CS:deleted-details> + +5.3.4. CS:notify-changes Property + + Name: notify-changes + + Namespace: http://calendarserver.org/ns/ + + Purpose: Allows a user to specify whether resource change + notifications are generated by the server. + + Protected: This property MUST NOT be protected. + + PROPFIND behavior: This property SHOULD NOT be returned by a + PROPFIND allprop request (as defined in Section 14.2 of + [RFC4918]). + + COPY/MOVE behavior: This property value MUST be preserved in COPY + and MOVE operations. + + Description: This property allows a user to enable or disable the + server generation of resource change notifications for the + calendar collection, and all its child resources, on which the + property resides. If the property is not present on a calendar + collection, the client and server MUST assume that resource change + notifications are enabled. + + Definition: + + <!ELEMENT notify-changes (true|false)> + <!ELEMENT true EMPTY> + <!ELEMENT false EMPTY> + + <!-- true - notifications enabled, + false - notifications disabled --> + + +6. Security Considerations + + Some notification mechanisms might allow a user to trigger a + notification to be delivered to other users (e.g., an invitation to + share a calendar). In such cases servers MUST ensure that suitable + limits are placed on the number and frequency of such user generated + notifications. + + + +Daboo [Page 20] + + CalDAV User Notifications March 2012 + + + TBD: More? + + +7. IANA Considerations + + This document does not require any actions on the part of IANA. + + +8. Acknowledgments + + This specification is the result of discussions between the various + Apple calendar server and client teams. + + +9. References + +9.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the + Internet: Timestamps", RFC 3339, July 2002. + + [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed + Authoring and Versioning (WebDAV)", RFC 4918, June 2007. + +9.2. Informative References + + [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web + Distributed Authoring and Versioning (WebDAV) + Access Control Protocol", RFC 3744, May 2004. + + [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, + "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, + March 2007. + + +Appendix A. Examples + + This section provides more detailed examples of resource change + notifications for illustrative purposes only. + +A.1. Resource Created + + This is an example of the body of a notification resource where one + resource has been created. + + + + +Daboo [Page 21] + + CalDAV User Notifications March 2012 + + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:created> + <D:href>http://example.com/cyrus/calendar/new.ics</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + </CS:created> + </CS:resource-change> + </CS:notification> + +A.2. Resource Updated - Property Change + + This is an example of the body of a notification resource where one + non-recurring event has had its "DTSTART" and "SUMMARY" iCalendar + property values changed. + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:updated> + <D:href>http://example.com/cyrus/calendar/new.ics</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + <CS:calendar-changes> + <CS:recurrence> + <CS:master/> + <CS:changes> + <CS:changed-property name="DTSTART"/> + <CS:changed-property name="SUMMARY"/> + </CS:changes> + </CS:recurrence> + </CS:calendar-changes> + </CS:updated> + </CS:resource-change> + </CS:notification> + + + + + +Daboo [Page 22] + + CalDAV User Notifications March 2012 + + +A.3. Resource Updated - Parameter Change + + This is an example of the body of a notification resource where one + non-recurring event has had the "PARTSTAT" iCalendar property + parameter on an "ATTENDEE" property changed, and a "TRANSP" property + added. + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:updated> + <D:href>http://example.com/cyrus/calendar/new.ics</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + <CS:calendar-changes> + <CS:recurrence> + <CS:master/> + <CS:added> + <CS:changed-property name="TRANSP"/> + </CS:added> + <CS:changes> + <CS:changed-property name="ATTENDEE"> + <CS:changed-parameter name="PARTSTAT"/> + </CS:changed-property> + </CS:changes> + </CS:recurrence> + </CS:calendar-changes> + </CS:updated> + </CS:resource-change> + </CS:notification> + +A.4. Resource Updated - Multiple Instances Change + + This is an example of the body of a notification resource where two + instances of a recurring event have their "DTSTART" and "SUMMARY" + iCalendar property values changed. + + + + + + + + + + +Daboo [Page 23] + + CalDAV User Notifications March 2012 + + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:updated> + <D:href>http://example.com/cyrus/calendar/new.ics</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + <CS:calendar-changes> + <CS:recurrence> + <CS:recurrenceid>20120209T170000Z</CS:recurrenceid> + <CS:changes> + <CS:changed-property name="DTSTART"/> + <CS:changed-property name="SUMMARY"/> + </CS:changes> + </CS:recurrence> + <CS:recurrence> + <CS:recurrenceid>20120210T170000Z</CS:recurrenceid> + <CS:changes> + <CS:changed-property name="DTSTART"/> + <CS:changed-property name="SUMMARY"/> + </CS:changes> + </CS:recurrence> + </CS:calendar-changes> + </CS:updated> + </CS:resource-change> + </CS:notification> + +A.5. Resource Updated - Multiple User Change + + This is an example of the body of a notification resource where two + instances of a recurring event have their "DTSTART" and "SUMMARY" + iCalendar property values changed. Each instance was changed by a + different user. + + + + + + + + + + + + + +Daboo [Page 24] + + CalDAV User Notifications March 2012 + + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:updated> + <D:href>http://example.com/cyrus/calendar/new.ics</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + <CS:calendar-changes> + <CS:recurrence> + <CS:recurrenceid>20120209T170000Z</CS:recurrenceid> + <CS:changes> + <CS:changed-property name="DTSTART"/> + <CS:changed-property name="SUMMARY"/> + </CS:changes> + </CS:recurrence> + </CS:calendar-changes> + </CS:updated> + <CS:updated> + <D:href>http://example.com/cyrus/calendar/new.ics</D:href> + <CS:changed-by> + <CS:first-name>Eric</CS:first-name> + <CS:last-name>York</CS:last-name> + <D:href>/principals/ericyork</D:href> + </CS:changed-by> + <CS:calendar-changes> + <CS:recurrence> + <CS:recurrenceid>20120210T170000Z</CS:recurrenceid> + <CS:changes> + <CS:changed-property name="DTSTART"/> + <CS:changed-property name="SUMMARY"/> + </CS:changes> + </CS:recurrence> + </CS:calendar-changes> + </CS:updated> + </CS:resource-change> + </CS:notification> + +A.6. Resource Deleted + + This is an example of the body of a notification resource where one + resource has been deleted. The resource was a VEVENT whose next + occurrence was in the future on 20120210T170000Z. + + + + +Daboo [Page 25] + + CalDAV User Notifications March 2012 + + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:deleted> + <D:href>http://example.com/cyrus/calendar/new.ics</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + <CS:deleted-details> + <CS:deleted-component>VEVENT</CS:deleted-component> + <CS:deleted-summary>CalDAV Meeting</CS:deleted-summary> + <CS:deleted-next-instance + >20120210T170000Z</CS:deleted-next-instance> + </CS:deleted-details> + </CS:deleted> + </CS:resource-change> + </CS:notification> + +A.7. Collection Created + + This is an example of the body of a notification resource where a + calendar collection has been created. + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:created> + <D:href>http://example.com/cyrus/new-calendar/</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + </CS:created> + </CS:resource-change> + </CS:notification> + +A.8. Collection Updated + + This is an example of the body of a notification resource where + coalesced changes in a calendar collection are shown. In this case 1 + child resource was created, 2 updated, and 1 deleted. + + + +Daboo [Page 26] + + CalDAV User Notifications March 2012 + + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:collection-changes> + <D:href>http://example.com/cyrus/calendar/</D:href> + <CS:child-created>1</CS:child-created> + <CS:child-updated>2</CS:child-updated> + <CS:child-deleted>1</CS:child-deleted> + </CS:collection-changes> + </CS:resource-change> + </CS:notification> + +A.9. Collection Deleted + + This is an example of the body of a notification resource where a + calendar collection has been deleted. + + <?xml version="1.0" encoding="UTF-8"?> + <CS:notification xmlns:D="DAV:" + xmlns:CS="http://calendarserver.org/ns/"> + <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp> + <CS:resource-change> + <CS:deleted> + <D:href>http://example.com/cyrus/old-calendar/</D:href> + <CS:changed-by> + <CS:first-name>Cyrus</CS:first-name> + <CS:last-name>Daboo</CS:last-name> + <D:href>/principals/cyrusdaboo</D:href> + </CS:changed-by> + <CS:deleted-details> + <CS:deleted-displayname>Holidays</CS:deleted-displayname> + </CS:deleted-details> + </CS:deleted> + </CS:resource-change> + </CS:notification> + + + + + + + + + + + + + + +Daboo [Page 27] + + CalDAV User Notifications March 2012 + + +Author's Address + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + USA + + Email: cyrus@daboo.name + URI: http://www.apple.com/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo [Page 28] + |