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, 0 insertions, 1568 deletions
diff --git a/vendor/sabre/dav/docs/caldav-notifications.txt b/vendor/sabre/dav/docs/caldav-notifications.txt deleted file mode 100644 index 75c2e5e07..000000000 --- a/vendor/sabre/dav/docs/caldav-notifications.txt +++ /dev/null @@ -1,1568 +0,0 @@ - - - -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] - |