[CalendarServer-changes] [8562] CalendarServer/trunk/doc/Extensions
source_changes at macosforge.org
source_changes at macosforge.org
Thu Jan 19 13:07:46 PST 2012
Revision: 8562
http://trac.macosforge.org/projects/calendarserver/changeset/8562
Author: cdaboo at apple.com
Date: 2012-01-19 13:07:44 -0800 (Thu, 19 Jan 2012)
Log Message:
-----------
Updated spec.
Modified Paths:
--------------
CalendarServer/trunk/doc/Extensions/caldav-notifications.txt
CalendarServer/trunk/doc/Extensions/caldav-notifications.xml
Modified: CalendarServer/trunk/doc/Extensions/caldav-notifications.txt
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-notifications.txt 2012-01-19 19:45:22 UTC (rev 8561)
+++ CalendarServer/trunk/doc/Extensions/caldav-notifications.txt 2012-01-19 21:07:44 UTC (rev 8562)
@@ -3,7 +3,7 @@
Calendar Server Extension C. Daboo
Apple Inc.
- January 11, 2012
+ January 17, 2012
CalDAV: Server Notifications
@@ -11,47 +11,47 @@
Abstract
This specification defines an extension to CalDAV that allows the
- server to provide notifications to a client.
+ server to provide notifications to calendar users.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Conventions Used in This Document . . . . . . . . . . . . . . 2
- 3. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 2
- 3.1. Additional Principal Properties . . . . . . . . . . . . . 3
- 3.1.1. CS:notification-URL Property . . . . . . . . . . . . . 3
- 3.2. Properties on Notification Resources . . . . . . . . . . . 4
- 3.2.1. CS:notificationtype Property . . . . . . . . . . . . . 4
- 3.3. XML Element Definitions . . . . . . . . . . . . . . . . . 5
- 3.3.1. CS:notifications . . . . . . . . . . . . . . . . . . . 5
- 3.3.2. CS:notification . . . . . . . . . . . . . . . . . . . 5
- 3.3.3. CS:dtstamp . . . . . . . . . . . . . . . . . . . . . . 6
- 4. Notification Definitions . . . . . . . . . . . . . . . . . . . 6
- 4.1. System Status Notification . . . . . . . . . . . . . . . . 6
- 4.1.1. CS:systemstatus Element Definition . . . . . . . . . . 6
- 4.2. Quota Notification . . . . . . . . . . . . . . . . . . . . 7
- 4.2.1. CS:quotastatus Element Definition . . . . . . . . . . 7
- 4.3. Resource Changes Notification . . . . . . . . . . . . . . 9
- 4.3.1. CS:resource-change Element Definition . . . . . . . . 10
- 4.3.2. CS:calendar-changes Element Definition . . . . . . . . 11
- 4.3.2.1. Handling Recurrences in CS:calendar-changes . . . 13
- 4.3.3. CS:notify-changes Property . . . . . . . . . . . . . . 14
- 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15
- 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
- 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15
- 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
- 8.1. Normative References . . . . . . . . . . . . . . . . . . . 15
- 8.2. Informative References . . . . . . . . . . . . . . . . . . 16
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16
+ 2. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 3. Conventions Used in This Document . . . . . . . . . . . . . . 2
+ 4. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 4.1. Additional Principal Properties . . . . . . . . . . . . . 3
+ 4.1.1. CS:notification-URL Property . . . . . . . . . . . . . 4
+ 4.2. Properties on Notification Resources . . . . . . . . . . . 4
+ 4.2.1. CS:notificationtype Property . . . . . . . . . . . . . 4
+ 4.3. XML Element Definitions . . . . . . . . . . . . . . . . . 5
+ 4.3.1. CS:notifications . . . . . . . . . . . . . . . . . . . 5
+ 4.3.2. CS:notification . . . . . . . . . . . . . . . . . . . 5
+ 4.3.3. CS:dtstamp . . . . . . . . . . . . . . . . . . . . . . 6
+ 4.3.4. CS:uid . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 5. Notification Definitions . . . . . . . . . . . . . . . . . . . 6
+ 5.1. System Status Notification . . . . . . . . . . . . . . . . 7
+ 5.1.1. CS:systemstatus Element Definition . . . . . . . . . . 7
+ 5.2. Quota Notification . . . . . . . . . . . . . . . . . . . . 8
+ 5.2.1. CS:quotastatus Element Definition . . . . . . . . . . 8
+ 5.3. Resource Changes Notification . . . . . . . . . . . . . . 10
+ 5.3.1. CS:resource-change Element Definition . . . . . . . . 10
+ 5.3.2. CS:calendar-changes Element Definition . . . . . . . . 13
+ 5.3.2.1. Handling Recurrences in CS:calendar-changes . . . 15
+ 5.3.3. CS:deleted-details Element Definition . . . . . . . . 16
+ 5.3.4. CS:notify-changes Property . . . . . . . . . . . . . . 17
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . . 18
+ 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
+ 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . . 19
+ 9.2. Informative References . . . . . . . . . . . . . . . . . . 19
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19
-
-
-
Daboo [Page 1]
CalDAV Notifications January 2012
@@ -65,15 +65,22 @@
access to calendar data via the WebDAV ACL [RFC3744] extension.
It is often useful for servers to communicate arbitrary information
- to clients, 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 generic to WebDAV [RFC4918].
+ 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. Conventions Used in This Document
+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].
@@ -90,85 +97,84 @@
type names.
-3. Notifications
+4. Notifications
- When this feature is available, a CS:notification-URL (Section 3.1.1)
+ 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.
- The notification collection referenced by the CS:notification-URL
- (Section 3.1.1) property MUST have a DAV:resourcetype property with
- DAV:collection and CS:notifications (Section 3.3.1) child elements.
- Notification "messages" are XML documents stored as resources in the
- notification collection. Each XML document contains a CS:
-
-
Daboo [Page 2]
CalDAV Notifications January 2012
- notification (Section 3.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.
+ 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.
- Each notification resource has a CS:notificationtype (Section 3.2.1)
+ 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, a CS:uid 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 client action) with an appropriate resource stored in
- the notifications collection of the user to whom the notification is
+ 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 3.2.1) property to ensure that
+ 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. 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.
+ 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.
-3.1. Additional Principal Properties
+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.
-3.1.1. CS:notification-URL Property
- Name: notification-URL
- Namespace: http://calendarserver.org/ns/
+Daboo [Page 3]
+
+ CalDAV Notifications January 2012
+4.1.1. CS:notification-URL Property
+ Name: notification-URL
-Daboo [Page 3]
-
- CalDAV Notifications January 2012
+ Namespace: http://calendarserver.org/ns/
-
Purpose: Identify the URL of the notification collection owned by
the associated principal resource.
@@ -191,12 +197,12 @@
<!ELEMENT notification-URL (DAV:href)>
-3.2. Properties on Notification Resources
+4.2. Properties on Notification Resources
The following new WebDAV properties are defined for notification
resources.
-3.2.1. CS:notificationtype Property
+4.2.1. CS:notificationtype Property
Name: notificationtype
@@ -211,20 +217,17 @@
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.
-
-
-
-
Daboo [Page 4]
CalDAV Notifications January 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
@@ -239,9 +242,9 @@
<!-- Child elements are empty but will have appropriate attributes.
Any valid notification message child element can appear.-->
-3.3. XML Element Definitions
+4.3. XML Element Definitions
-3.3.1. CS:notifications
+4.3.1. CS:notifications
Name: notifications
@@ -257,7 +260,7 @@
<!ELEMENT notifications EMPTY>
-3.3.2. CS:notification
+4.3.2. CS:notification
Name: notification
@@ -267,22 +270,25 @@
Description: The root element used in notification resources.
- Definition:
- <!ELEMENT notification (dtstamp, XXX) >
- <!-- Any notification type element can appear after
- CS:dtstamp -->
+
Daboo [Page 5]
CalDAV Notifications January 2012
-3.3.3. CS:dtstamp
+ Definition:
+ <!ELEMENT notification (dtstamp, uid, XXX) >
+ <!-- Any notification type element can appear after
+ CS:dtstamp -->
+
+4.3.3. CS:dtstamp
+
Name: dtstamp
Namespace: http://calendarserver.org/ns/
@@ -296,13 +302,43 @@
<!ELEMENT dtstamp (#PCDATA)>
+4.3.4. CS:uid
-4. Notification Definitions
+ Name: uid
+ Namespace: http://calendarserver.org/ns/
+
+ Purpose: Unique identifier for a notification.
+
+ Description: Contains the unique identifier for a notification
+ message. In some situation a server might update an existing
+ notification with new information (e.g., when coalescing), but the
+ server might create a new resource and delete the old one.
+ However, clients will likely want to track this change as an
+ update rather than a deletion and creation of a new notification.
+ To aid that servers MUST include a unique identifier in the CS:uid
+ element in the notification to allow clients to track notification
+ updates.
+
+ Definition:
+
+ <!ELEMENT uid (#PCDATA)>
+
+
+5. Notification Definitions
+
This section defines a set of common notification types.
-4.1. System Status Notification
+
+
+Daboo [Page 6]
+
+ CalDAV Notifications January 2012
+
+
+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
@@ -318,7 +354,7 @@
but if it does, it SHOULD include an xml:lang attribute on the CS:
description element to indicate what language is being used.
-4.1.1. CS:systemstatus Element Definition
+5.1.1. CS:systemstatus Element Definition
Name: systemstatus
@@ -326,17 +362,6 @@
Purpose: Indicates a system status notification.
-
-
-
-
-
-
-Daboo [Page 6]
-
- CalDAV Notifications January 2012
-
-
Description: This XML element is used in a CS:notification element
to describe a system status notification.
@@ -352,10 +377,27 @@
Example: This is an example of the body of a notification resource
for an emergency system outage:
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 7]
+
+ CalDAV Notifications January 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:uid>9B75C4F9-80CB-4E3B-A231-4AEEDD50D2FA</CS:uid>
<CS:systemstatus type="high">
<D:href>http://example.com/emergency_shutdown.html</D:href>
<CS:description xml:lang='en_US'
@@ -372,7 +414,7 @@
<CS:systemstatus type="high" />
</CS:notificationtype>
-4.2. Quota Notification
+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
@@ -381,18 +423,8 @@
their quota limit), or in other cases errors (e.g., a user exceeding
their quota).
-4.2.1. CS:quotastatus Element Definition
+5.2.1. CS:quotastatus Element Definition
-
-
-
-
-
-Daboo [Page 7]
-
- CalDAV Notifications January 2012
-
-
Name: quotastatus
Namespace: http://calendarserver.org/ns/
@@ -407,6 +439,16 @@
a URI for a webpage where the user can go to get further
information about their quota status or take corrective action.
+
+
+
+
+
+Daboo [Page 8]
+
+ CalDAV Notifications January 2012
+
+
Definition:
<!ELEMENT quota-status (quota+)>
@@ -432,6 +474,7 @@
<CS:notification xmlns:D="DAV:"
xmlns:CS="http://calendarserver.org/ns/">
<CS:dtstamp>2011-12-09T11:12:53-05:00</CS:dtstamp>
+ <CS:uid>9B61A79D-7C07-48C2-B9E4-B3DFD9506C80</CS:uid>
<CS:quota-status>
<CS:quota type="warning">
<CS:quota-type><CS:attachments /></CS:quota-type>
@@ -441,22 +484,32 @@
</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:
-Daboo [Page 8]
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 9]
CalDAV Notifications January 2012
- 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:uid>E3892573-5605-45F8-8F21-62C63ED013A3</CS:uid>
<CS:quota-status>
<CS:quota type="exceeded">
<CS:quota-type><CS:attachments /></CS:quota-type>
@@ -472,41 +525,42 @@
</CS:quota-status>
</CS:notification>
-4.3. Resource Changes 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). 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 next synchronize the notification collection.
+ 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
+ next synchronize the notification collection.
- A new WebDAV property CS:notify-changes (Section 4.3.3) is defined
+ 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 and not "owned" by
- them. Servers MUST honor the chosen setting to enable or disable
- change notifications.
+ 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.
+5.3.1. CS:resource-change Element Definition
-Daboo [Page 9]
+
+Daboo [Page 10]
CalDAV Notifications January 2012
-4.3.1. CS:resource-change Element Definition
-
Name: resource-change
Namespace: http://calendarserver.org/ns/
@@ -519,32 +573,69 @@
created, CS:updated, CS:deleted elements each of which indicates a
created, updated or deleted resource, respectively. The DAV:href
element within those three elements, contain the URI of the
- changed resource, and optionally additional information specific
- to the nature of the change. Servers SHOULD coalesce resource
- changes notifications into a single resource. 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 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:
- calendar-changes elements to list details of the deleted resource.
- Servers SHOULD include at least the "SUMMARY" details of the
- deleted item, and MAY include others.
+ 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. Servers MAY
+ coalesce resource change notifications to multiple resources into
+ a single notification resource. 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
+ 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.
Definition:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 11]
+
+ CalDAV Notifications January 2012
+
+
<!ELEMENT resource-change (created*, updated*, deleted*)>
- <!ELEMENT created (DAV:href, ANY)>
- <!ELEMENT updated (DAV:href, CS:content?,
- DAV:prop?, CS:calendar-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, CS:calendar-changes*)>
+ <!ELEMENT deleted (DAV:href, changed-by?, deleted-details)>
+ <!ELEMENT changed-by (first-name, last-name,
+ dtstamp?, DAV:href)>
+ <!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. 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. -->
+
+
Example: This is an example of the body of a notification resource
for changes where one resource has been created, two updated, and
one deleted. One of the updated resources elements contains
@@ -556,7 +647,28 @@
-Daboo [Page 10]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo [Page 12]
CalDAV Notifications January 2012
@@ -565,58 +677,75 @@
<CS:notification xmlns:D="DAV:"
xmlns:CS="http://calendarserver.org/ns/">
<CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
+ <CS:uid>0EAA94D2-CD76-417C-B278-220A4D2D0ABB</CS:uid>
<CS:resource-changed>
<CS:created>
<D:href>http://example.com/cyrus/tasks/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: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 at example.com</D:href>
+ </CS:changed-by>
</CS:updated>
<CS:updated>
<D:href>http://example.com/cyrus/tasks/todo.ics</D:href>
+ <CS:changed-by>
+ <CS:first-name>Eleanor</CS:first-name>
+ <CS:last-name>Daboo</CS:last-name>
+ <D:href>mailto:eleanor at example.com</D:href>
+ </CS:changed-by>
</CS:updated>
<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-changed>
</CS:notification>
-4.3.2. CS:calendar-changes Element Definition
+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.
- Description: This XML element is used in a CS:updated element to
- describe how a calendar object resource changed. 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 4.3.2.1.
- Definition:
+Daboo [Page 13]
+
+ CalDAV Notifications January 2012
+ Namespace: http://calendarserver.org/ns/
+ Purpose: Indicates which portions of an calendar object resource
+ have changed, or provides details of deleted calendar object
+ resources.
+ 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:
-
-
-
-
-
-Daboo [Page 11]
-
- CalDAV Notifications January 2012
-
-
<!ELEMENT calendar-changes (recurrence+) >
<!ELEMENT recurrence
@@ -648,6 +777,14 @@
<!-- An iCalendar property parameter changed -->
+
+
+
+Daboo [Page 14]
+
+ CalDAV Notifications January 2012
+
+
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.
@@ -661,18 +798,6 @@
<CS:recurrence/>
</CS:calendar-changes>
-
-
-
-
-
-
-
-Daboo [Page 12]
-
- CalDAV Notifications January 2012
-
-
Example: This example indicates that an instance of a recurring
component was changed and that the change was to the "DTSTART"
iCalendar property.
@@ -686,7 +811,7 @@
<CS:recurrence/>
</CS:calendar-changes>
-4.3.2.1. Handling Recurrences in 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
@@ -708,6 +833,14 @@
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
+
+
+
+Daboo [Page 15]
+
+ CalDAV Notifications January 2012
+
+
will not be any CS:added or CS:removed elements.
Master exists, override removed In this case, a CS:recurrence
@@ -718,17 +851,6 @@
present if the removed component differs from the "derived" master
instance.
-
-
-
-
-
-
-Daboo [Page 13]
-
- CalDAV Notifications January 2012
-
-
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
@@ -756,35 +878,93 @@
UTC) of the added component. A CS:removed element will be
present. There will not be any CS:added or CS:changes element.
-4.3.3. CS:notify-changes Property
+5.3.3. CS:deleted-details Element Definition
- Name: notify-changes
+ Name: deleted-details
Namespace: http://calendarserver.org/ns/
- Purpose: Allows a user to specify whether resource change
- notifications are generated by the server.
+ Purpose: Provides summary information about a deleted resource.
- 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.
+Daboo [Page 16]
+
+ CalDAV Notifications January 2012
+ Description: This XML element is used in a CS:deleted element to
+ describe specific summary information about a deleted resource, so
+ clients can provide a meaningful notification message to users.
-Daboo [Page 14]
+ Definition:
+
+ <!ELEMENT deleted-details (deleted-component, deleted-summary,
+ deleted-next-instance?,
+ deleted-had-more-instances?) >
+
+ <!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>
+ <!-- If present indicates the UTC date-time, or date value for
+ the "RECURRENCE-ID" of the next future instance at the time
+ of deletion. If not present, then there were no future
+ instances at the time of deletion. -->
+
+ <!ELEMENT deleted-had-more-instances CDATA>
+ <!-- If present indicates that there was more than one future
+ instances still to occur at the time of deletion. -->
+
+
+
+ Example: This example indicates shows 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>20120505</CS:deleted-next-instance>
+ </CS:deleted-details>
+
+5.3.4. CS:notify-changes Property
+
+ Name: notify-changes
+
+ Namespace: http://calendarserver.org/ns/
+
+
+
+
+
+
+Daboo [Page 17]
CalDAV Notifications January 2012
+ 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
@@ -802,7 +982,7 @@
false - notifications disabled -->
-5. Security Considerations
+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
@@ -813,36 +993,37 @@
TBD: More?
-6. IANA Considerations
+7. IANA Considerations
This document does not require any actions on the part of IANA.
-7. Acknowledgments
+8. Acknowledgments
- This specification is the result of discussions between the Apple
- calendar server and client teams.
+ This specification is the result of discussions between the various
-8. References
-8.1. Normative References
+Daboo [Page 18]
+
+ CalDAV Notifications January 2012
+
+ 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.
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+9.2. Informative References
-
-Daboo [Page 15]
-
- CalDAV Notifications January 2012
-
-
-8.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.
@@ -879,18 +1060,5 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 16]
+Daboo [Page 19]
Modified: CalendarServer/trunk/doc/Extensions/caldav-notifications.xml
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-notifications.xml 2012-01-19 19:45:22 UTC (rev 8561)
+++ CalendarServer/trunk/doc/Extensions/caldav-notifications.xml 2012-01-19 21:07:44 UTC (rev 8562)
@@ -38,24 +38,23 @@
<date/>
<abstract>
<t>
- This specification defines an extension to CalDAV that allows the server to provide notifications to a client.
+ This specification defines an extension to CalDAV that allows the server to provide notifications to calendar users.
</t>
</abstract>
</front>
<middle>
<section title='Introduction'>
<t><xref target="RFC4791">CalDAV</xref> provides a way for calendar users to store calendar data and exchange this data via scheduling operations. Based on the <xref target='RFC4918'>WebDAV</xref> protocol, it also includes the ability to manage access to calendar data via the <xref target='RFC3744'>WebDAV ACL</xref> extension.</t>
- <t>It is often useful for servers to communicate arbitrary information to clients, 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 <xref target="RFC4791">CalDAV</xref>, this mechanism has been designed to be generic to <xref target='RFC4918'>WebDAV</xref>.</t>
+ <t>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 <xref target="RFC4791">CalDAV</xref>, this mechanism has been designed to be adaptable to <xref target='RFC4918'>WebDAV</xref>.</t>
</section>
- <!--<section title="Open Issues">
+ <section title="Open Issues">
<t>
<list style="numbers">
- <t>
- </t>
+ <t>Define specific child elements for system status notification, e.g. "server-maintenance-period", "server-read-only-period", "client-upgrade-required".</t>
</list>
</t>
- </section>-->
+ </section>
<section title='Conventions Used in This Document'>
<t>
@@ -74,7 +73,7 @@
<t>The notification collection referenced by the <xref target="CS:notification-URL">CS:notification-URL</xref> property MUST have a DAV:resourcetype property with DAV:collection and <xref target="CS:notifications">CS:notifications</xref> child elements.</t>
<t>Notification "messages" are XML documents stored as resources in the notification collection. Each XML document contains a <xref target="CS:notification">CS:notification</xref> 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.</t>
<t>Each notification resource has a <xref target="CS:notificationtype">CS:notificationtype</xref> 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.</t>
- <t>Notifications are automatically generated by the server (perhaps in response to a client 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 <xref target="CS:notificationtype">CS:notificationtype</xref> 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. 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.</t>
+ <t>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 <xref target="CS:notificationtype">CS:notificationtype</xref> 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.</t>
<t>Servers MUST prevent clients from adding resources in the notification collection.</t>
<section title="Additional Principal Properties" anchor='principal-properties'>
<t>This section defines new properties for WebDAV principal resources as defined in <xref target="RFC3744">RFC3744</xref>. These properties are likely to be protected but the server MAY allow them to be written by appropriate users.</t>
@@ -308,8 +307,8 @@
</section>
</section>
<section title="Resource Changes Notification">
- <t>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). 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 next synchronize the notification collection.</t>
- <t>A new WebDAV property <xref target="CS:notify-changes">CS:notify-changes</xref> 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 and not "owned" by them. Servers MUST honor the chosen setting to enable or disable change notifications.</t>
+ <t>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 next synchronize the notification collection.</t>
+ <t>A new WebDAV property <xref target="CS:notify-changes">CS:notify-changes</xref> 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.</t>
<t>Servers can send notifications for calendar object resources, and ones for calendar collections.</t>
<section title="CS:resource-change Element Definition" anchor="CS:resource-change">
<t>
@@ -317,16 +316,28 @@
<t hangText="Name:">resource-change</t>
<t hangText="Namespace:">http://calendarserver.org/ns/</t>
<t hangText="Purpose:">Indicates that resources have been created, updated or deleted.</t>
- <t hangText="Description:">This XML element is used in a CS:notification element to describe a resource changes notification. It can contain CS:created, CS:updated, CS:deleted elements each of which indicates a created, updated or deleted resource, respectively. The DAV:href element within those three elements, contain the URI of the changed resource, and optionally additional information specific to the nature of the change. Servers SHOULD coalesce resource changes notifications into a single resource. 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 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:calendar-changes elements to list details of the deleted resource. Servers SHOULD include at least the "SUMMARY" details of the deleted item, and MAY include others.</t>
+ <t hangText="Description:">This XML element is used in a CS:notification element to describe a resource changes notification. It can contain CS:created, CS:updated, CS:deleted elements each of which indicates a created, updated or deleted resource, respectively. The DAV:href element within those three elements, contain 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. Servers MAY coalesce resource change notifications to multiple resources into a single notification resource. 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 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.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT resource-change (created*, updated*, deleted*)>
- <!ELEMENT created (DAV:href, ANY)>
- <!ELEMENT updated (DAV:href, CS:content?,
- DAV:prop?, CS:calendar-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, CS:calendar-changes*)>
+ <!ELEMENT deleted (DAV:href, changed-by?, deleted-details)>
+
+ <!ELEMENT changed-by (first-name, last-name,
+ dtstamp?, DAV:href)>
+ <!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. 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. -->
+
]]></artwork>
</figure>
</t>
@@ -340,15 +351,35 @@
<CS:resource-changed>
<CS:created>
<D:href>http://example.com/cyrus/tasks/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: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 at example.com</D:href>
+ </CS:changed-by>
</CS:updated>
<CS:updated>
<D:href>http://example.com/cyrus/tasks/todo.ics</D:href>
+ <CS:changed-by>
+ <CS:first-name>Eleanor</CS:first-name>
+ <CS:last-name>Daboo</CS:last-name>
+ <D:href>mailto:eleanor at example.com</D:href>
+ </CS:changed-by>
</CS:updated>
<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-changed>
</CS:notification>]]></artwork>
@@ -362,8 +393,8 @@
<list style="hanging">
<t hangText="Name:">calendar-changes</t>
<t hangText="Namespace:">http://calendarserver.org/ns/</t>
- <t hangText="Purpose:">Indicates which portions of an calendar object resource have changed.</t>
- <t hangText="Description:">This XML element is used in a CS:updated element to describe how a calendar object resource changed. 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 <xref target="recurrence_changes"/>.</t>
+ <t hangText="Purpose:">Indicates which portions of an calendar object resource have changed, or provides details of deleted calendar object resources.</t>
+ <t hangText="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 <xref target="recurrence_changes"/>.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
@@ -454,6 +485,58 @@
</list></t>
</section>
</section>
+ <section title="CS:deleted-details Element Definition" anchor="CS:deleted-details">
+ <t>
+ <list style="hanging">
+ <t hangText="Name:">deleted-details</t>
+ <t hangText="Namespace:">http://calendarserver.org/ns/</t>
+ <t hangText="Purpose:">Provides summary information about a deleted resource.</t>
+ <t hangText="Description:">This XML element is used in a CS:deleted element to describe specific summary information about a deleted resource, so clients can provide a meaningful notification message to users.</t>
+ <t hangText="Definition:">
+ <figure>
+ <artwork><![CDATA[
+ <!ELEMENT deleted-details (deleted-component, deleted-summary,
+ deleted-next-instance?,
+ deleted-had-more-instances?) >
+
+ <!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>
+ <!-- If present indicates the UTC date-time, or date value for
+ the "RECURRENCE-ID" of the next future instance at the time
+ of deletion. If not present, then there were no future
+ instances at the time of deletion. -->
+
+ <!ELEMENT deleted-had-more-instances CDATA>
+ <!-- If present indicates that there was more than one future
+ instances still to occur at the time of deletion. -->
+
+
+ ]]></artwork>
+ </figure>
+ </t>
+ <t hangText="Example:">
+ This example indicates shows deletion of a non-recurring event that was yet to occur at the time of deletion.
+ <figure>
+ <artwork><![CDATA[
+<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>20120505</CS:deleted-next-instance>
+</CS:deleted-details>
+ ]]></artwork>
+ </figure>
+ </t>
+ </list>
+ </t>
+ </section>
<section title="CS:notify-changes Property" anchor="CS:notify-changes">
<t>
<list style="hanging">
@@ -495,7 +578,7 @@
</section>
<section title='Acknowledgments'>
<t>
- This specification is the result of discussions between the Apple calendar server and client teams.
+ This specification is the result of discussions between the various Apple calendar server and client teams.
</t>
</section>
</middle>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20120119/4f6cc5dd/attachment-0001.html>
More information about the calendarserver-changes
mailing list