mirror of
https://git.friendi.ca/friendica/friendica-addons.git
synced 2024-12-11 09:43:15 +00:00
1569 lines
51 KiB
Text
1569 lines
51 KiB
Text
|
|
|||
|
|
|||
|
|
|||
|
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]
|
|||
|
|