4 Calendar Server Extension C. Daboo
9 CalDAV: Calendar User Notifications
13 This specification defines an extension to CalDAV that allows the
14 server to provide notifications to calendar users.
57 CalDAV User Notifications March 2012
62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
63 2. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 3
64 3. Conventions Used in This Document . . . . . . . . . . . . . . 3
65 4. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 3
66 4.1. Additional Principal Properties . . . . . . . . . . . . . 4
67 4.1.1. CS:notification-URL Property . . . . . . . . . . . . . 5
68 4.2. Properties on Notification Resources . . . . . . . . . . . 5
69 4.2.1. CS:notificationtype Property . . . . . . . . . . . . . 5
70 4.3. XML Element Definitions . . . . . . . . . . . . . . . . . 6
71 4.3.1. CS:notifications . . . . . . . . . . . . . . . . . . . 6
72 4.3.2. CS:notification . . . . . . . . . . . . . . . . . . . 6
73 4.3.3. CS:dtstamp . . . . . . . . . . . . . . . . . . . . . . 7
74 5. Notification Definitions . . . . . . . . . . . . . . . . . . . 7
75 5.1. System Status Notification . . . . . . . . . . . . . . . . 7
76 5.1.1. CS:systemstatus Element Definition . . . . . . . . . . 8
77 5.2. Quota Notification . . . . . . . . . . . . . . . . . . . . 8
78 5.2.1. CS:quotastatus Element Definition . . . . . . . . . . 9
79 5.3. Resource Changes Notification . . . . . . . . . . . . . . 10
80 5.3.1. CS:resource-change Element Definition . . . . . . . . 11
81 5.3.2. CS:calendar-changes Element Definition . . . . . . . . 15
82 5.3.2.1. Handling Recurrences in CS:calendar-changes . . . 17
83 5.3.3. CS:deleted-details Element Definition . . . . . . . . 18
84 5.3.4. CS:notify-changes Property . . . . . . . . . . . . . . 20
85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20
86 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
87 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21
88 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
89 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21
90 9.2. Informative References . . . . . . . . . . . . . . . . . . 21
91 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21
92 A.1. Resource Created . . . . . . . . . . . . . . . . . . . . . 21
93 A.2. Resource Updated - Property Change . . . . . . . . . . . . 22
94 A.3. Resource Updated - Parameter Change . . . . . . . . . . . 23
95 A.4. Resource Updated - Multiple Instances Change . . . . . . . 23
96 A.5. Resource Updated - Multiple User Change . . . . . . . . . 24
97 A.6. Resource Deleted . . . . . . . . . . . . . . . . . . . . . 25
98 A.7. Collection Created . . . . . . . . . . . . . . . . . . . . 26
99 A.8. Collection Updated . . . . . . . . . . . . . . . . . . . . 26
100 A.9. Collection Deleted . . . . . . . . . . . . . . . . . . . . 27
101 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 27
113 CalDAV User Notifications March 2012
118 CalDAV [RFC4791] provides a way for calendar users to store calendar
119 data and exchange this data via scheduling operations. Based on the
120 WebDAV [RFC4918] protocol, it also includes the ability to manage
121 access to calendar data via the WebDAV ACL [RFC3744] extension.
123 It is often useful for servers to communicate arbitrary information
124 to calendar users, e.g., system status, message of the day, quota
125 warnings, changes to shared resources made by others etc. This
126 specification defines a generic "notification" mechanism that allows
127 a server to do that. Whilst primarily aimed at CalDAV [RFC4791],
128 this mechanism has been designed to be adaptable to WebDAV [RFC4918].
133 1. Define specific child elements for system status notification,
134 e.g. "server-maintenance-period", "server-read-only-period",
135 "client-upgrade-required".
138 3. Conventions Used in This Document
140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
141 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
142 document are to be interpreted as described in [RFC2119].
144 When XML element types in the namespaces "DAV:" and
145 "urn:ietf:params:xml:ns:caldav" are referenced in this document
146 outside of the context of an XML fragment, the string "DAV:" and
147 "CALDAV:" will be prefixed to the element type names respectively.
149 The namespace "http://calendarserver.org/ns/" is used for XML
150 elements defined in this specification. When XML element types in
151 that namespace are referenced in this document outside of the context
152 of an XML fragment, the string "CS:" will be prefixed to the element
158 When this feature is available, a CS:notification-URL (Section 4.1.1)
159 property appears on principal resources for those principals who are
160 able to receive notifications. That property specifies a single DAV:
161 href element whose content refers to a WebDAV collection resource.
162 Notification "messages" are deposited into this collection and can be
163 retrieved by clients and acted on accordingly.
169 CalDAV User Notifications March 2012
172 The notification collection referenced by the CS:notification-URL
173 (Section 4.1.1) property MUST have a DAV:resourcetype property with
174 DAV:collection and CS:notifications (Section 4.3.1) child elements.
176 Notification "messages" are XML documents stored as resources in the
177 notification collection. Each XML document contains a CS:
178 notification (Section 4.3.2) element as its root. The root element
179 contains a CS:dtstamp element, and one additional element which
180 represents the type of notification being conveyed in the message.
181 That child element will typically contain additional content that
182 describes the notification.
184 Each notification resource has a CS:notificationtype (Section 4.2.1)
185 property which contains as its single child element an empty element
186 that matches the child element of the notification resource XML
187 document root. Any attributes on the child element in the XML
188 document are also present in the property child element.
190 Notifications are automatically generated by the server (perhaps in
191 response to a action) with an appropriate resource stored in the
192 notifications collection of the user to whom the notification is
193 targeted. Clients SHOULD monitor the notification collection looking
194 for new notification resources. When doing so, clients SHOULD look
195 at the CS:notificationtype (Section 4.2.1) property to ensure that
196 the notification is of a type that the client can handle. Once a
197 client has handled the notification in whatever way is appropriate it
198 SHOULD delete the notification resource. Clients SHOULD remove
199 notifications being displayed to a user when the notification
200 resource is removed from the notification collection, to enable the
201 user to dismiss a notification on one device and have it
202 automatically removed from others. Clients MUST ignore all
203 notifications for types they do not recognize. Servers MAY delete
204 notification resources on their own if they determine that the
205 notifications are no longer relevant or valid. Servers MAY coalesce
206 notifications as appropriate.
208 Servers MUST prevent clients from adding resources in the
209 notification collection.
211 4.1. Additional Principal Properties
213 This section defines new properties for WebDAV principal resources as
214 defined in RFC3744 [RFC3744]. These properties are likely to be
215 protected but the server MAY allow them to be written by appropriate
225 CalDAV User Notifications March 2012
228 4.1.1. CS:notification-URL Property
230 Name: notification-URL
232 Namespace: http://calendarserver.org/ns/
234 Purpose: Identify the URL of the notification collection owned by
235 the associated principal resource.
237 Protected: This property SHOULD be protected.
239 PROPFIND behavior: This property SHOULD NOT be returned by a
240 PROPFIND allprop request (as defined in Section 14.2 of
243 COPY/MOVE behavior: This property value SHOULD be preserved in COPY
246 Description: This property is needed for a client to determine where
247 the notification collection of the current user is located so that
248 processing of notification messages can occur. If not present,
249 then the associated calendar user is not enabled for notification
250 messages on the server.
254 <!ELEMENT notification-URL (DAV:href)>
256 4.2. Properties on Notification Resources
258 The following new WebDAV properties are defined for notification
261 4.2.1. CS:notificationtype Property
263 Name: notificationtype
265 Namespace: http://calendarserver.org/ns/
267 Purpose: Identify the type of notification of the corresponding
270 Protected: This property MUST be protected.
272 PROPFIND behavior: This property SHOULD NOT be returned by a
273 PROPFIND allprop request (as defined in Section 14.2 of
281 CalDAV User Notifications March 2012
284 COPY/MOVE behavior: This property value MUST be preserved in COPY
287 Description: This property allows a client, via a PROPFIND Depth:1
288 request, to quickly find notification messages that the client can
289 handle in a notification collection. The single child element is
290 the notification resource root element's child defining the
291 notification itself. This element MUST be empty, though any
292 attributes on the element in the notification resource MUST be
293 present in the property element.
297 <!ELEMENT notificationtype ANY>
298 <!-- Child elements are empty but will have appropriate attributes.
299 Any valid notification message child element can appear.-->
301 4.3. XML Element Definitions
303 4.3.1. CS:notifications
307 Namespace: http://calendarserver.org/ns/
309 Purpose: Indicates a notification collection.
311 Description: This XML element is used in a DAV:resourcetype element
312 to indicate that the corresponding resource is a notification
317 <!ELEMENT notifications EMPTY>
319 4.3.2. CS:notification
323 Namespace: http://calendarserver.org/ns/
325 Purpose: Notification message root element.
327 Description: The root element used in notification resources.
337 CalDAV User Notifications March 2012
342 <!ELEMENT notification (dtstamp, XXX) >
343 <!-- Any notification type element can appear after
350 Namespace: http://calendarserver.org/ns/
352 Purpose: Date-time stamp.
354 Description: Contains the date-time stamp corresponding to the
355 creation of a notification message, using the format defined in
356 [RFC3339], or the "compact" format without "-" and ":" characters
357 between date and time elements, respectively.
361 <!ELEMENT dtstamp (#PCDATA)>
362 <!-- Value is a date-time in UTZ as per [RFC3339] with
363 "compact" format allowed.-->
366 5. Notification Definitions
368 This section defines a set of common notification types.
370 5.1. System Status Notification
372 The system status notification is used to convey a URI and/or textual
373 description to the user. The assumption is that the URI points to a
374 webpage where current system status is described in detail, with the
375 provided description being a summary of that. A "type" attribute on
376 the element is used to indicate the importance of the current status
377 notification, and has the values "low", "medium" and "high",
378 representing the increasing level of importance of the message
381 Servers might have knowledge of specific calendar user language
382 preferences, in which case it MAY localise the CS:description value
383 as appropriate based on the calendar user accessing the notification,
384 but if it does, it SHOULD include an xml:lang attribute on the CS:
385 description element to indicate what language is being used.
393 CalDAV User Notifications March 2012
396 5.1.1. CS:systemstatus Element Definition
400 Namespace: http://calendarserver.org/ns/
402 Purpose: Indicates a system status notification.
404 Description: This XML element is used in a CS:notification element
405 to describe a system status notification.
409 <!ELEMENT systemstatus (DAV:href?, CS:description?)>
410 <!ATTLIST systemstatus type (low | medium | high) "low">
412 <!ELEMENT description CDATA>
414 <!-- One of DAV:href of CS:description MUST be present -->
416 Example: This is an example of the body of a notification resource
417 for an emergency system outage:
419 <?xml version="1.0" encoding="UTF-8"?>
420 <CS:notification xmlns:D="DAV:"
421 xmlns:CS="http://calendarserver.org/ns/">
422 <CS:dtstamp>2011-12-09T11:12:53-05:00</CS:dtstamp>
423 <CS:systemstatus type="high">
424 <D:href>http://example.com/emergency_shutdown.html</D:href>
425 <CS:description xml:lang='en_US'
426 >Emergency shutdown now</CS:description>
430 Example: This is an example of the WebDAV property on the example
431 notification resource above:
433 <?xml version="1.0" encoding="UTF-8"?>
434 <CS:notificationtype xmlns:D="DAV:"
435 xmlns:CS="http://calendarserver.org/ns/">
436 <CS:systemstatus type="high" />
437 </CS:notificationtype>
439 5.2. Quota Notification
441 The quota notification is used to convey information about the status
442 of one or more quotas for the user. The notification contains
443 elements for different types of quota being reported to the user. In
449 CalDAV User Notifications March 2012
452 some cases these may be warnings (e.g., a user getting to 80% of
453 their quota limit), or in other cases errors (e.g., a user exceeding
456 5.2.1. CS:quotastatus Element Definition
460 Namespace: http://calendarserver.org/ns/
462 Purpose: Indicates a quota status notification.
464 Description: This XML element is used in a CS:notification element
465 to describe a quota status notification. The CS:quota-percent-
466 used element contains an integer greater than or equal to zero.
467 If the value is greater than or equal to 100, then the user's
468 quota has been reached or exceeded. The DAV:href element contains
469 a URI for a webpage where the user can go to get further
470 information about their quota status or take corrective action.
474 <!ELEMENT quota-status (quota+)>
476 <!ELEMENT quota (quota-type, quota-percent-used?,
477 quota-count?, DAV:href?)>
478 <!ATTLIST quota type (warning | exceeded) "exceeded">
480 <!ELEMENT quota-type ANY>
481 <!-- Child elements are application specific -->
483 <!ELEMENT quota-percent-used CDATA>
484 <!-- Integer value greater than or equal to zero -->
486 <!ELEMENT quota-count CDATA>
487 <!-- Integer value greater than or equal to zero -->
489 Example: This is an example of the body of a notification resource
505 CalDAV User Notifications March 2012
508 <?xml version="1.0" encoding="UTF-8"?>
509 <CS:notification xmlns:D="DAV:"
510 xmlns:CS="http://calendarserver.org/ns/">
511 <CS:dtstamp>2011-12-09T11:12:53-05:00</CS:dtstamp>
513 <CS:quota type="warning">
514 <CS:quota-type><CS:attachments /></CS:quota-type>
515 <CS:quota-percent-used>80</CS:quota-percent-used>
516 <D:href>https://example.com/your-account.html</D:href>
521 Example: This is an example of the body of a notification resource
522 for a quota that has been exceeded, and a count-based limit that
523 is shown as a warning:
525 <?xml version="1.0" encoding="UTF-8"?>
526 <CS:notification xmlns:D="DAV:"
527 xmlns:CS="http://calendarserver.org/ns/">
528 <CS:dtstamp>2011-12-09T11:12:53-05:00</CS:dtstamp>
530 <CS:quota type="exceeded">
531 <CS:quota-type><CS:attachments /></CS:quota-type>
532 <CS:quota-percent-used>102</CS:quota-percent-used>
533 <D:href>https://example.com/fix-account.html</D:href>
535 <CS:quota type="warning">
536 <CS:quota-type><CS:events /></CS:quota-type>
537 <CS:quota-percent-used>82</CS:quota-percent-used>
538 <CS:quota-count>4980</CS:quota-count>
539 <D:href>https://example.com/buy-more-space.html</D:href>
544 5.3. Resource Changes Notification
546 The resource change notification is used to inform the user of new,
547 updated or deleted resources caused by changes made by someone else
548 (note: servers MUST NOT generate notifications to users for changes
549 they themselves make, though the possibility of an automated process
550 acting on behalf of a user needs to be considered). This
551 notification can be used by clients to show changes that a user can
552 acknowledge in their own time. When the notification is present, it
553 can be displayed on all devices a user is accessing their data from.
554 When the user acknowledges and dismisses the notification on one
555 device, other devices SHOULD also remove the notification when they
561 CalDAV User Notifications March 2012
564 next synchronize the notification collection.
566 A new WebDAV property CS:notify-changes (Section 5.3.4) is defined
567 for calendar collections. This allows users to enable or disable the
568 sending of resource change notifications for the calendar and its
569 child resources. Servers MUST allow users to set this property on a
570 per-user basis on any calendars accessible to them. Servers MUST
571 honor the chosen setting to enable or disable change notifications.
573 Servers can send notifications for calendar object resources, and
574 ones for calendar collections. Servers SHOULD coalesce notifications
575 that refer to the same resource into a single notification resource,
576 containing multiple CS:created, CS:updated or CS:deleted elements all
577 with the same DAV:href child element value. Servers MAY coalesce
578 changes to multiple resources into a change notification for the
579 parent collection of those resources and use a CS:collection-changes
580 element to indicate the number of individual resources that changed.
582 5.3.1. CS:resource-change Element Definition
584 Name: resource-change
586 Namespace: http://calendarserver.org/ns/
588 Purpose: Indicates that resources have been created, updated or
591 Description: This XML element is used in a CS:notification element
592 to describe a resource change notification. It can describe a
593 change directly to a calendar object resource or to a calendar
596 When used for a calendar object resource change, it can contain
597 one of the CS:created, or CS:deleted elements, or multiple CS:
598 updated elements, which indicate a created, deleted or updated
599 resource, respectively. The DAV:href element within those
600 elements, contains the URI of the changed resource, optional
601 information about who changed the resource and when that change
602 was made (the CS:changed-by element), and information specific to
603 the nature of the change. Servers SHOULD coalesce resource change
604 notifications for the same resource into a single notification
605 resource where possible. The CS:updated element optionally
606 contains CS:content and/or DAV:prop elements to indicate a change
607 to the body of the resource or resource WebDAV properties,
608 respectively. The DAV:prop element MAY contain a list of property
609 elements to indicate which properties changed. The CS:updated
610 element can also contain zero or more CS:calendar-changes elements
611 to list details of the changes. If no CS:calendar-changes element
617 CalDAV User Notifications March 2012
620 is present, the specific details are not provided, and clients
621 will need to assume that some set of changes occurred, but the
622 server is unwilling to disclose the full details. The CS:deleted
623 element can also contain zero or more CS:deleted-details elements
624 to list details of the deleted resource.
626 When used for a calendar collection change, it can contain a CS:
627 collection-changes element. The DAV:href element within that
628 element, contains the URI of the changed calendar collection. The
629 DAV:prop element indicates a change to WebDAV properties on the
630 calendar collection resource. The CS:child-created, CS:child-
631 updated, and CS:child-deleted elements each contain a positive
632 integer value indicating how many child resources were added,
633 updated or deleted in the collection, respectively.
673 CalDAV User Notifications March 2012
676 <!ELEMENT resource-change (created | updated+ | deleted |
678 <!ELEMENT created (DAV:href, changed-by?, ANY)>
679 <!ELEMENT updated (DAV:href, changed-by?, content?,
680 DAV:prop?, calendar-changes*)>
681 <!ELEMENT content EMPTY>
682 <!ELEMENT deleted (DAV:href, changed-by?, deleted-details)>
684 <!ELEMENT changed-by (common-name | (first-name, last-name),
686 <!ELEMENT common-name CDATA>
687 <!ELEMENT first-name CDATA>
688 <!ELEMENT last-name CDATA>
689 <!-- CS:changed-by indicates who made the change that caused the
690 notification. CS:first-name and CS:last-name are the first
691 and last names of the corresponding user. or the
692 CS:common-name is the overall display name. CS:dtstamp is the
693 time in UTC when the change was made. The DAV:href element
694 is the principal URI or email address of the user who made
697 <!ELEMENT collection-changes (DAV:href, changed-by*, DAV:prop?,
698 child-created?, child-updated?,
700 <!-- When coalescing changes from multiple users, the changed-by
701 element can appear more than once. -->
703 <!ELEMENT child-created CDATA>
704 <!ELEMENT child-updated CDATA>
705 <!ELEMENT child-deleted CDATA>
706 <!-- Each of the three elements above MUST contain a positive,
707 non-zero integer value indicate the total number of changes
708 being reported for the collection. -->
710 Example: This is an example of the body of a notification resource
711 for changes where one resource has been created:
729 CalDAV User Notifications March 2012
732 <?xml version="1.0" encoding="UTF-8"?>
733 <CS:notification xmlns:D="DAV:"
734 xmlns:CS="http://calendarserver.org/ns/">
735 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
738 <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
740 <CS:common-name>Cyrus Daboo</CS:common-name>
741 <D:href>/principals/cyrusdaboo</D:href>
744 </CS:resource-change>
747 Example: This is an example of the body of a notification resource
748 for changes where a resource has been updated twice. One of the
749 updated resources elements contains additional information
750 indicating which recurrence instances in the iCalendar data were
753 <?xml version="1.0" encoding="UTF-8"?>
754 <CS:notification xmlns:D="DAV:"
755 xmlns:CS="http://calendarserver.org/ns/">
756 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
759 <D:href>http://example.com/cyrus/calendar/event.ics</D:href>
761 <CS:first-name>Oliver</CS:first-name>
762 <CS:last-name>Daboo</CS:last-name>
763 <D:href>mailto:oliver@example.com</D:href>
767 <D:href>http://example.com/cyrus/calendar/event.ics</D:href>
769 <CS:first-name>Eleanor</CS:first-name>
770 <CS:last-name>Daboo</CS:last-name>
771 <D:href>mailto:eleanor@example.com</D:href>
774 </CS:resource-change>
785 CalDAV User Notifications March 2012
788 Example: This is an example of the body of a notification resource
789 for changes where one resource has been deleted:
791 <?xml version="1.0" encoding="UTF-8"?>
792 <CS:notification xmlns:D="DAV:"
793 xmlns:CS="http://calendarserver.org/ns/">
794 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
797 <D:href>http://example.com/cyrus/calendar/old.ics</D:href>
799 <CS:first-name>Cyrus</CS:first-name>
800 <CS:last-name>Daboo</CS:last-name>
801 <D:href>/principals/cyrusdaboo</D:href>
804 </CS:resource-change>
807 Example: This example is the same as the previous three, except that
808 all the individual resource changes have been coalesced into a
809 single notification about changes to the parent calendar
812 <?xml version="1.0" encoding="UTF-8"?>
813 <CS:notification xmlns:D="DAV:"
814 xmlns:CS="http://calendarserver.org/ns/">
815 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
817 <CS:collection-changes>
818 <D:href>http://example.com/cyrus/calendar/</D:href>
819 <CS:child-created>1</CS:child-created>
820 <CS:child-updated>2</CS:child-updated>
821 <CS:child-deleted>1</CS:child-deleted>
822 </CS:collection-changes>
823 </CS:resource-change>
826 5.3.2. CS:calendar-changes Element Definition
828 Name: calendar-changes
830 Namespace: http://calendarserver.org/ns/
832 Purpose: Indicates which portions of an calendar object resource
833 have changed, or provides details of deleted calendar object
841 CalDAV User Notifications March 2012
844 Description: This XML element is used in a CS:updated element to
845 describe how a calendar object resource changed, or in a CS:
846 deleted element to provide details of a deleted resource. It can
847 identify the master instance, or individual recurrence instances,
848 and for each indicate which iCalendar properties and parameters
849 changed during the update for which the notification was
850 generated. For details of handling recurrences please see
855 <!ELEMENT calendar-changes (recurrence+) >
858 ((master | recurrenceid), added?, removed?, changes?)>
859 <!-- Which instances were affected by the change,
860 and details on the per-instance changes -->
862 <!ELEMENT master EMPTY>
863 <!-- The "master" instance was affected -->
865 <!ELEMENT recurrenceid CDATA>
866 <!-- RECURRENCE-ID value in iCalendar form (in UTC if a
867 non-floating DATE-TIME value) for the affected instance -->
869 <!ELEMENT added EMPTY>
870 <!-- The component was added -->
872 <!ELEMENT removed EMPTY>
873 <!-- The component was removed -->
875 <!ELEMENT changes changed-property*>
876 <!-- Detailed changes in the iCalendar data -->
878 <!ELEMENT changed-property changed-parameter*>
879 <!ATTLIST changed-property name PCDATA>
880 <!-- An iCalendar property changed -->
882 <!ELEMENT changed-parameter EMPTY>
883 <!ATTLIST changed-parameter name PCDATA>
884 <!-- An iCalendar property parameter changed -->
886 Example: This example indicates that a non-recurring component, or
887 the master component in a recurring component, was changed and
888 that the change was to the "SUMMARY" iCalendar property.
897 CalDAV User Notifications March 2012
900 <CS:calendar-changes xmlns:CS="http://calendarserver.org/ns/">
904 <CS:changed-property name="SUMMARY"/>
907 </CS:calendar-changes>
909 Example: This example indicates that an instance of a recurring
910 component was changed and that the change was to the "DTSTART"
913 <CS:calendar-changes xmlns:CS="http://calendarserver.org/ns/">
915 <CS:recurrenceid>20111215T160000Z</CS:recurrenceid>
917 <CS:changed-property name="DTSTART"/>
920 </CS:calendar-changes>
922 5.3.2.1. Handling Recurrences in CS:calendar-changes
924 Changes to recurring components can be complex. This section
925 describes the possible set of changes that could occur, and what the
926 CS:calendar-changes element will contain as a result.
928 Master exists, unchanged override added In this case, a CS:
929 recurrence element will be present, containing a CS:recurrence-id
930 element with a value equal to the RECURRENCE-ID property value (in
931 UTC) of the added component. A CS:added element will be present.
932 There will not be any CS:removed or CS:changes elements.
934 Master exists, changed override added In this case, a CS:recurrence
935 element will be present, containing a CS:recurrence-id element
936 with a value equal to the RECURRENCE-ID property value (in UTC) of
937 the added component. Both CS:added and CS:changes elements will
938 be present. There will not be a CS:removed element.
940 Master exists, override changed In this case, a CS:recurrence
941 element will be present, containing a CS:recurrence-id element
942 with a value equal to the RECURRENCE-ID property value (in UTC) of
943 the added component. A CS:changes element will be present. There
944 will not be any CS:added or CS:removed elements.
953 CalDAV User Notifications March 2012
956 Master exists, override removed In this case, a CS:recurrence
957 element will be present, containing a CS:recurrence-id element
958 with a value equal to the RECURRENCE-ID property value (in UTC) of
959 the added component. A CS:removed element will be present. There
960 will not be a CS:added element. A CS:changes element will only be
961 present if the removed component differs from the "derived" master
964 Master exists, override cancelled In this case, a CS:recurrence
965 element will be present, containing a CS:recurrence-id element
966 with a value equal to the RECURRENCE-ID property value (in UTC) of
967 the added component. A CS:removed element will be present. There
968 will not be any CS:added or CS:changes element. There will also
969 be a CS:master element present, with an appropriate CS:changes
970 element, likely covering a change to "RRULE" or addition of
973 Master does not exist, override added In this case, a CS:recurrence
974 element will be present, containing a CS:recurrence-id element
975 with a value equal to the RECURRENCE-ID property value (in UTC) of
976 the added component. A CS:added element will be present. There
977 will not be a CS:removed or CS:changes element.
979 Master does not exist, override changed In this case, a CS:
980 recurrence element will be present, containing a CS:recurrence-id
981 element with a value equal to the RECURRENCE-ID property value (in
982 UTC) of the added component. A CS:changes element will be
983 present. There will not be any CS:added or CS:removed elements.
985 Master does not exist, override removed In this case, a CS:
986 recurrence element will be present, containing a CS:recurrence-id
987 element with a value equal to the RECURRENCE-ID property value (in
988 UTC) of the added component. A CS:removed element will be
989 present. There will not be any CS:added or CS:changes element.
991 5.3.3. CS:deleted-details Element Definition
993 Name: deleted-details
995 Namespace: http://calendarserver.org/ns/
997 Purpose: Provides summary information about a deleted resource or
1000 Description: This XML element is used in a CS:deleted element to
1001 describe useful information about a deleted resource or
1002 collection, so clients can provide a meaningful notification
1003 message to users. This element has two variants: one for deletion
1009 CalDAV User Notifications March 2012
1012 of a calendar object resource, the other for deletion of a
1013 calendar collection.
1017 <!ELEMENT deleted-details ((deleted-component,
1019 deleted-next-instance?,
1020 deleted-had-more-instances?) |
1021 deleted-displayname)>
1022 <!-- deleted-displayname is used for a collection delete, the other
1023 elements used for a resource delete. -->
1025 <!ELEMENT deleted-component CDATA>
1026 <!-- The main calendar component type of the deleted
1027 resource, e.g., "VEVENT", "VTODO" -->
1029 <!ELEMENT deleted-summary CDATA>
1030 <!-- Indicates the "SUMMARY" of the next future instance at the
1031 time of deletion, or the previous instance if no future
1032 instances existed at the time of deletion. -->
1034 <!ELEMENT deleted-next-instance CDATA>
1035 <!ATTLIST deleted-next-instance tzid PCDATA>
1036 <!-- If present, indicates when the next deleted instance would
1037 have occurred. For a VEVENT that would be the DTSTART value,
1038 for a VTODO that would be either DTSTART or DUE, if present.
1039 In each case the value must match the value in the iCalendar
1040 data, and any TZID iCalendar property parameter value must
1041 be included in the tzid XML element attribute value. -->
1043 <!ELEMENT deleted-had-more-instances EMPTY>
1044 <!-- If present indicates that there was more than one future
1045 instances still to occur at the time of deletion. -->
1047 <!ELEMENT deleted-displayname CDATA>
1048 <!-- The DAV:getdisplayname property for the collection that
1051 Example: This example indicates deletion of a non-recurring event
1052 that was yet to occur at the time of deletion.
1054 <CS:deleted-details xmlns:CS="http://calendarserver.org/ns/">
1055 <CS:deleted-component>VEVENT</CS:deleted-component>
1056 <CS:deleted-summary>Birthday Party</CS:deleted-summary>
1057 <CS:deleted-next-instance tzid="America/New_York
1058 >20120505T120000</CS:deleted-next-instance>
1059 </CS:deleted-details>
1065 CalDAV User Notifications March 2012
1068 Example: This example indicates deletion of a calendar.
1070 <CS:deleted-details xmlns:CS="http://calendarserver.org/ns/">
1071 <CS:deleted-displayname>Holidays</CS:deleted-displayname>
1072 </CS:deleted-details>
1074 5.3.4. CS:notify-changes Property
1076 Name: notify-changes
1078 Namespace: http://calendarserver.org/ns/
1080 Purpose: Allows a user to specify whether resource change
1081 notifications are generated by the server.
1083 Protected: This property MUST NOT be protected.
1085 PROPFIND behavior: This property SHOULD NOT be returned by a
1086 PROPFIND allprop request (as defined in Section 14.2 of
1089 COPY/MOVE behavior: This property value MUST be preserved in COPY
1090 and MOVE operations.
1092 Description: This property allows a user to enable or disable the
1093 server generation of resource change notifications for the
1094 calendar collection, and all its child resources, on which the
1095 property resides. If the property is not present on a calendar
1096 collection, the client and server MUST assume that resource change
1097 notifications are enabled.
1101 <!ELEMENT notify-changes (true|false)>
1102 <!ELEMENT true EMPTY>
1103 <!ELEMENT false EMPTY>
1105 <!-- true - notifications enabled,
1106 false - notifications disabled -->
1109 6. Security Considerations
1111 Some notification mechanisms might allow a user to trigger a
1112 notification to be delivered to other users (e.g., an invitation to
1113 share a calendar). In such cases servers MUST ensure that suitable
1114 limits are placed on the number and frequency of such user generated
1121 CalDAV User Notifications March 2012
1127 7. IANA Considerations
1129 This document does not require any actions on the part of IANA.
1134 This specification is the result of discussions between the various
1135 Apple calendar server and client teams.
1140 9.1. Normative References
1142 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1143 Requirement Levels", BCP 14, RFC 2119, March 1997.
1145 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
1146 Internet: Timestamps", RFC 3339, July 2002.
1148 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
1149 Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
1151 9.2. Informative References
1153 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
1154 Distributed Authoring and Versioning (WebDAV)
1155 Access Control Protocol", RFC 3744, May 2004.
1157 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
1158 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
1162 Appendix A. Examples
1164 This section provides more detailed examples of resource change
1165 notifications for illustrative purposes only.
1167 A.1. Resource Created
1169 This is an example of the body of a notification resource where one
1170 resource has been created.
1177 CalDAV User Notifications March 2012
1180 <?xml version="1.0" encoding="UTF-8"?>
1181 <CS:notification xmlns:D="DAV:"
1182 xmlns:CS="http://calendarserver.org/ns/">
1183 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1184 <CS:resource-change>
1186 <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1188 <CS:first-name>Cyrus</CS:first-name>
1189 <CS:last-name>Daboo</CS:last-name>
1190 <D:href>/principals/cyrusdaboo</D:href>
1193 </CS:resource-change>
1196 A.2. Resource Updated - Property Change
1198 This is an example of the body of a notification resource where one
1199 non-recurring event has had its "DTSTART" and "SUMMARY" iCalendar
1200 property values changed.
1202 <?xml version="1.0" encoding="UTF-8"?>
1203 <CS:notification xmlns:D="DAV:"
1204 xmlns:CS="http://calendarserver.org/ns/">
1205 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1206 <CS:resource-change>
1208 <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1210 <CS:first-name>Cyrus</CS:first-name>
1211 <CS:last-name>Daboo</CS:last-name>
1212 <D:href>/principals/cyrusdaboo</D:href>
1214 <CS:calendar-changes>
1218 <CS:changed-property name="DTSTART"/>
1219 <CS:changed-property name="SUMMARY"/>
1222 </CS:calendar-changes>
1224 </CS:resource-change>
1233 CalDAV User Notifications March 2012
1236 A.3. Resource Updated - Parameter Change
1238 This is an example of the body of a notification resource where one
1239 non-recurring event has had the "PARTSTAT" iCalendar property
1240 parameter on an "ATTENDEE" property changed, and a "TRANSP" property
1243 <?xml version="1.0" encoding="UTF-8"?>
1244 <CS:notification xmlns:D="DAV:"
1245 xmlns:CS="http://calendarserver.org/ns/">
1246 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1247 <CS:resource-change>
1249 <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1251 <CS:first-name>Cyrus</CS:first-name>
1252 <CS:last-name>Daboo</CS:last-name>
1253 <D:href>/principals/cyrusdaboo</D:href>
1255 <CS:calendar-changes>
1259 <CS:changed-property name="TRANSP"/>
1262 <CS:changed-property name="ATTENDEE">
1263 <CS:changed-parameter name="PARTSTAT"/>
1264 </CS:changed-property>
1267 </CS:calendar-changes>
1269 </CS:resource-change>
1272 A.4. Resource Updated - Multiple Instances Change
1274 This is an example of the body of a notification resource where two
1275 instances of a recurring event have their "DTSTART" and "SUMMARY"
1276 iCalendar property values changed.
1289 CalDAV User Notifications March 2012
1292 <?xml version="1.0" encoding="UTF-8"?>
1293 <CS:notification xmlns:D="DAV:"
1294 xmlns:CS="http://calendarserver.org/ns/">
1295 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1296 <CS:resource-change>
1298 <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1300 <CS:first-name>Cyrus</CS:first-name>
1301 <CS:last-name>Daboo</CS:last-name>
1302 <D:href>/principals/cyrusdaboo</D:href>
1304 <CS:calendar-changes>
1306 <CS:recurrenceid>20120209T170000Z</CS:recurrenceid>
1308 <CS:changed-property name="DTSTART"/>
1309 <CS:changed-property name="SUMMARY"/>
1313 <CS:recurrenceid>20120210T170000Z</CS:recurrenceid>
1315 <CS:changed-property name="DTSTART"/>
1316 <CS:changed-property name="SUMMARY"/>
1319 </CS:calendar-changes>
1321 </CS:resource-change>
1324 A.5. Resource Updated - Multiple User Change
1326 This is an example of the body of a notification resource where two
1327 instances of a recurring event have their "DTSTART" and "SUMMARY"
1328 iCalendar property values changed. Each instance was changed by a
1345 CalDAV User Notifications March 2012
1348 <?xml version="1.0" encoding="UTF-8"?>
1349 <CS:notification xmlns:D="DAV:"
1350 xmlns:CS="http://calendarserver.org/ns/">
1351 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1352 <CS:resource-change>
1354 <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1356 <CS:first-name>Cyrus</CS:first-name>
1357 <CS:last-name>Daboo</CS:last-name>
1358 <D:href>/principals/cyrusdaboo</D:href>
1360 <CS:calendar-changes>
1362 <CS:recurrenceid>20120209T170000Z</CS:recurrenceid>
1364 <CS:changed-property name="DTSTART"/>
1365 <CS:changed-property name="SUMMARY"/>
1368 </CS:calendar-changes>
1371 <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1373 <CS:first-name>Eric</CS:first-name>
1374 <CS:last-name>York</CS:last-name>
1375 <D:href>/principals/ericyork</D:href>
1377 <CS:calendar-changes>
1379 <CS:recurrenceid>20120210T170000Z</CS:recurrenceid>
1381 <CS:changed-property name="DTSTART"/>
1382 <CS:changed-property name="SUMMARY"/>
1385 </CS:calendar-changes>
1387 </CS:resource-change>
1390 A.6. Resource Deleted
1392 This is an example of the body of a notification resource where one
1393 resource has been deleted. The resource was a VEVENT whose next
1394 occurrence was in the future on 20120210T170000Z.
1401 CalDAV User Notifications March 2012
1404 <?xml version="1.0" encoding="UTF-8"?>
1405 <CS:notification xmlns:D="DAV:"
1406 xmlns:CS="http://calendarserver.org/ns/">
1407 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1408 <CS:resource-change>
1410 <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1412 <CS:first-name>Cyrus</CS:first-name>
1413 <CS:last-name>Daboo</CS:last-name>
1414 <D:href>/principals/cyrusdaboo</D:href>
1416 <CS:deleted-details>
1417 <CS:deleted-component>VEVENT</CS:deleted-component>
1418 <CS:deleted-summary>CalDAV Meeting</CS:deleted-summary>
1419 <CS:deleted-next-instance
1420 >20120210T170000Z</CS:deleted-next-instance>
1421 </CS:deleted-details>
1423 </CS:resource-change>
1426 A.7. Collection Created
1428 This is an example of the body of a notification resource where a
1429 calendar collection has been created.
1431 <?xml version="1.0" encoding="UTF-8"?>
1432 <CS:notification xmlns:D="DAV:"
1433 xmlns:CS="http://calendarserver.org/ns/">
1434 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1435 <CS:resource-change>
1437 <D:href>http://example.com/cyrus/new-calendar/</D:href>
1439 <CS:first-name>Cyrus</CS:first-name>
1440 <CS:last-name>Daboo</CS:last-name>
1441 <D:href>/principals/cyrusdaboo</D:href>
1444 </CS:resource-change>
1447 A.8. Collection Updated
1449 This is an example of the body of a notification resource where
1450 coalesced changes in a calendar collection are shown. In this case 1
1451 child resource was created, 2 updated, and 1 deleted.
1457 CalDAV User Notifications March 2012
1460 <?xml version="1.0" encoding="UTF-8"?>
1461 <CS:notification xmlns:D="DAV:"
1462 xmlns:CS="http://calendarserver.org/ns/">
1463 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1464 <CS:resource-change>
1465 <CS:collection-changes>
1466 <D:href>http://example.com/cyrus/calendar/</D:href>
1467 <CS:child-created>1</CS:child-created>
1468 <CS:child-updated>2</CS:child-updated>
1469 <CS:child-deleted>1</CS:child-deleted>
1470 </CS:collection-changes>
1471 </CS:resource-change>
1474 A.9. Collection Deleted
1476 This is an example of the body of a notification resource where a
1477 calendar collection has been deleted.
1479 <?xml version="1.0" encoding="UTF-8"?>
1480 <CS:notification xmlns:D="DAV:"
1481 xmlns:CS="http://calendarserver.org/ns/">
1482 <CS:dtstamp>2011-12-09T11:51:14-05:00</CS:dtstamp>
1483 <CS:resource-change>
1485 <D:href>http://example.com/cyrus/old-calendar/</D:href>
1487 <CS:first-name>Cyrus</CS:first-name>
1488 <CS:last-name>Daboo</CS:last-name>
1489 <D:href>/principals/cyrusdaboo</D:href>
1491 <CS:deleted-details>
1492 <CS:deleted-displayname>Holidays</CS:deleted-displayname>
1493 </CS:deleted-details>
1495 </CS:resource-change>
1513 CalDAV User Notifications March 2012
1524 Email: cyrus@daboo.name
1525 URI: http://www.apple.com/