Peler

: / opt / cpanel-ccs / doc / Extensions /
Filename : caldav-notifications.xml
back
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../../rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3339 PUBLIC '' 'bibxml/reference.RFC.3339.xml'>
<!ENTITY rfc3744 PUBLIC '' 'bibxml/reference.RFC.3744.xml'>
<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
<!ENTITY rfc4918 PUBLIC '' 'bibxml/reference.RFC.4918.xml'>
]> 
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc strict="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private="Calendar Server Extension"?>
<rfc ipr="none" docName='caldav-notifications-00'>
    <front>
        <title abbrev="CalDAV User Notifications">CalDAV: Calendar User Notifications</title> 
        <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
            <organization abbrev="Apple Inc.">
                Apple Inc.
            </organization>
            <address>
                <postal>
                    <street>1 Infinite Loop</street>
                    <city>Cupertino</city>
                    <region>CA</region>
                    <code>95014</code> 
                    <country>USA</country>
                </postal>
                <email>cyrus@daboo.name</email>
                <uri>http://www.apple.com/</uri>
            </address>
        </author>
        <date/>
        <abstract>
            <t>
                This specification defines an extension to CalDAV that allows the server to provide notifications to calendar users.
            </t>
        </abstract>
    </front>
    <middle>
        <section title='Introduction'>
            <t><xref target="RFC4791">CalDAV</xref> provides a way for calendar users to store calendar data and exchange this data via scheduling operations. Based on the <xref target='RFC4918'>WebDAV</xref> protocol, it also includes the ability to manage access to calendar data via the <xref target='RFC3744'>WebDAV ACL</xref> extension.</t>
            <t>It is often useful for servers to communicate arbitrary information to calendar users, e.g., system status, message of the day, quota warnings, changes to shared resources made by others etc. This specification defines a generic "notification" mechanism that allows a server to do that. Whilst primarily aimed at <xref target="RFC4791">CalDAV</xref>, this mechanism has been designed to be adaptable to <xref target='RFC4918'>WebDAV</xref>.</t>
        </section>

        <section title="Open Issues">
            <t>
                <list style="numbers">
                    <t>Define specific child elements for system status notification, e.g. "server-maintenance-period", "server-read-only-period", "client-upgrade-required".</t>
                </list>
            </t>
        </section>
            
        <section title='Conventions Used in This Document'>
            <t>
                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 <xref target='RFC2119' />. 
            </t>
            <t>
                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. 
            </t>
            <t>
                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. 
            </t>
        </section>
         
        <section title="Notifications">
            <t>When this feature is available, a <xref target="CS:notification-URL">CS:notification-URL</xref> 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.</t>
            <t>The notification collection referenced by the <xref target="CS:notification-URL">CS:notification-URL</xref> property MUST have a DAV:resourcetype property with DAV:collection and <xref target="CS:notifications">CS:notifications</xref> child elements.</t>
            <t>Notification "messages" are XML documents stored as resources in the notification collection. Each XML document contains a <xref target="CS:notification">CS:notification</xref> element as its root. The root element contains a CS:dtstamp element, and one additional element which represents the type of notification being conveyed in the message. That child element will typically contain additional content that describes the notification.</t>
            <t>Each notification resource has a <xref target="CS:notificationtype">CS:notificationtype</xref> property which contains as its single child element an empty element that matches the child element of the notification resource XML document root. Any attributes on the child element in the XML document are also present in the property child element.</t>
            <t>Notifications are automatically generated by the server (perhaps in response to a   action) with an appropriate resource stored in the notifications collection of the user to whom the notification is targeted. Clients SHOULD monitor the notification collection looking for new notification resources. When doing so, clients SHOULD look at the <xref target="CS:notificationtype">CS:notificationtype</xref> property to ensure that the notification is of a type that the client can handle. Once a client has handled the notification in whatever way is appropriate it SHOULD delete the notification resource. Clients SHOULD remove notifications being displayed to a user when the notification resource is removed from the notification collection, to enable the user to dismiss a notification on one device and have it automatically removed from others. Clients MUST ignore all notifications for types they do not recognize. Servers MAY delete notification resources on their own if they determine that the notifications are no longer relevant or valid. Servers MAY coalesce notifications as appropriate.</t>
            <t>Servers MUST prevent clients from adding resources in the notification collection.</t>
            <section title="Additional Principal Properties" anchor='principal-properties'>
                <t>This section defines new properties for WebDAV principal resources as defined in <xref target="RFC3744">RFC3744</xref>. These properties are likely to be protected but the server MAY allow them to be written by appropriate users.</t>
                <section title="CS:notification-URL Property" anchor="CS:notification-URL">
                  <t>
                    <list style="hanging">
                      <t hangText="Name:">notification-URL</t>
                      <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                      <t hangText="Purpose:">Identify the URL of the notification collection owned by the associated principal resource.</t>
                      <t hangText="Protected:">This property SHOULD be protected.</t>
                      <t hangText="PROPFIND behavior:">This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
                      <t hangText="COPY/MOVE behavior:">This property value SHOULD be preserved in COPY and MOVE operations.</t>
        
                      <t hangText="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.</t>
                      <t hangText="Definition:">
                        <figure>
                          <artwork><![CDATA[
<!ELEMENT notification-URL (DAV:href)>]]></artwork>
                        </figure>
                      </t>
                    </list>
                  </t>
                </section>
            </section>
            <section title="Properties on Notification Resources" anchor='notification-properties'>
                <t>The following new WebDAV properties are defined for notification resources.</t>
                <section title="CS:notificationtype Property" anchor="CS:notificationtype">
                  <t>
                    <list style="hanging">
                      <t hangText="Name:">notificationtype</t>
                      <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                      <t hangText="Purpose:">Identify the type of notification of the corresponding resource.</t>
                      <t hangText="Protected:">This property MUST be protected.</t>
                      <t hangText="PROPFIND behavior:">This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
                      <t hangText="COPY/MOVE behavior:">This property value MUST be preserved in COPY and MOVE operations.</t>
        
                      <t hangText="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.</t>
                      <t hangText="Definition:">
                        <figure>
                          <artwork><![CDATA[
<!ELEMENT notificationtype ANY>
<!-- Child elements are empty but will have appropriate attributes.
     Any valid notification message child element can appear.-->]]></artwork>
                        </figure>
                      </t>
                    </list>
                  </t>
                </section>
            </section>
            <section title='XML Element Definitions'>
                <section title="CS:notifications" anchor="CS:notifications">
                    <t>
                      <list style="hanging">
                        <t hangText="Name:">notifications</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Indicates a notification collection.</t>
                        <t hangText="Description:">This XML element is used in a DAV:resourcetype element to indicate that the corresponding resource is a notification collection.</t>
                        <t hangText="Definition:">
                          <figure>
                            <artwork><![CDATA[
<!ELEMENT notifications EMPTY>]]></artwork>
                          </figure>
                        </t>
                      </list>
                    </t>
                </section>
                <section title="CS:notification" anchor="CS:notification">
                    <t>
                      <list style="hanging">
                        <t hangText="Name:">notification</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Notification message root element.</t>
                        <t hangText="Description:">The root element used in notification resources.</t>
                        <t hangText="Definition:">
                          <figure>
                            <artwork><![CDATA[
<!ELEMENT notification (dtstamp, XXX) >
<!-- Any notification type element can appear after
     CS:dtstamp -->]]></artwork>
                          </figure>
                        </t>
                      </list>
                    </t>
                </section>
              <section title="CS:dtstamp" anchor="CS:dtstamp">
                <t>
                  <list style="hanging">
                    <t hangText="Name:">dtstamp</t>
                    <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                    <t hangText="Purpose:">Date-time stamp.</t>
                    <t hangText="Description:">Contains the date-time stamp corresponding to the creation of a notification message, using the format defined in <xref target="RFC3339"/>, or the "compact" format without "-" and ":" characters between date and time elements, respectively.</t>
                    <t hangText="Definition:">
                      <figure>
                        <artwork><![CDATA[
<!ELEMENT dtstamp (#PCDATA)>
<!-- Value is a date-time in UTZ as per [RFC3339] with 
     "compact" format allowed.-->]]></artwork>
                      </figure>
                    </t>
                  </list>
                </t>
              </section>
            </section>

        </section>

        <section title="Notification Definitions">
            <t>This section defines a set of common notification types.</t>
            <section title="System Status Notification">
                <t>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.</t>
                <t>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.</t>
                <section title="CS:systemstatus Element Definition" anchor="CS:systemstatus">
                    <t>
                      <list style="hanging">
                        <t hangText="Name:">systemstatus</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Indicates a system status notification.</t>
                        <t hangText="Description:">This XML element is used in a CS:notification element to describe a system status notification.</t>
                        <t hangText="Definition:">
                          <figure>
                            <artwork><![CDATA[
<!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 -->
]]></artwork>
                          </figure>
                        </t>
                        <t hangText="Example:">This is an example of the body of a notification resource for an emergency system outage:
                          <figure>
                            <artwork><![CDATA[
<?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>]]></artwork>
                          </figure>
                        </t>
                        <t hangText="Example:">This is an example of the WebDAV property on the example notification resource above:
                          <figure>
                            <artwork><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<CS:notificationtype xmlns:D="DAV:"
                     xmlns:CS="http://calendarserver.org/ns/">
  <CS:systemstatus type="high" />
</CS:notificationtype>]]></artwork>
                          </figure>
                        </t>
                      </list>
                    </t>
                </section>
            </section>
            <section title="Quota Notification">
                <t>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 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).
                </t>
                <section title="CS:quotastatus Element Definition" anchor="CS:quotastatus">
                    <t>
                      <list style="hanging">
                        <t hangText="Name:">quotastatus</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Indicates a quota status notification.</t>
                        <t hangText="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.</t>
                        <t hangText="Definition:">
                          <figure>
                            <artwork><![CDATA[
<!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 -->]]></artwork>
                          </figure>
                        </t>
                        <t hangText="Example:">This is an example of the body of a notification resource for a quota warning:
                          <figure>
                            <artwork><![CDATA[
<?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>]]></artwork>
                          </figure>
                        </t>
                        <t hangText="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:
                          <figure>
                            <artwork><![CDATA[
<?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>]]></artwork>
                          </figure>
                        </t>
                      </list>
                    </t>
                </section>
            </section>
            <section title="Resource Changes Notification">
                <t>The resource change notification is used to inform the user of new, updated or deleted resources caused by changes made by someone else (note: servers MUST NOT generate notifications to users for changes they themselves make, though the possibility of an automated process acting on behalf of a user needs to be considered). This notification can be used by clients to show changes that a user can acknowledge in their own time. When the notification is present, it can be displayed on all devices a user is accessing their data from. When the user acknowledges and dismisses the notification on one device, other devices SHOULD also remove the notification when they next synchronize the notification collection.</t>
                <t>A new WebDAV property <xref target="CS:notify-changes">CS:notify-changes</xref> is defined for calendar collections. This allows users to enable or disable the sending of resource change notifications for the calendar and its child resources. Servers MUST allow users to set this property on a per-user basis on any calendars accessible to them. Servers MUST honor the chosen setting to enable or disable change notifications.</t>
                <t>Servers can send notifications for calendar object resources, and ones for calendar collections. 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.</t>
                <section title="CS:resource-change Element Definition" anchor="CS:resource-change">
                    <t>
                      <list style="hanging">
                        <t hangText="Name:">resource-change</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Indicates that resources have been created, updated or deleted.</t>
                        <t hangText="Description:">This XML element is used in a CS:notification element to describe a resource change notification. It can describe a change directly to a calendar object resource or to a calendar collection.</t>
                        <t>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 is present, the specific details are not provided, and clients will need to assume that some set of changes occurred, but the server is unwilling to disclose the full details. The CS:deleted element can also contain zero or more CS:deleted-details elements to list details of the deleted resource.</t>
                        <t>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.</t>
                        <t hangText="Definition:">
                          <figure>
                            <artwork><![CDATA[
<!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. -->]]></artwork>
                          </figure>
                        </t>
                        <t hangText="Example:">This is an example of the body of a notification resource for changes where one resource has been created:
                          <figure>
                            <artwork><![CDATA[
<?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>]]></artwork>
                          </figure>
                        </t>
                        <t hangText="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:
                          <figure>
                            <artwork><![CDATA[
<?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>]]></artwork>
                          </figure>
                        </t>
                        <t hangText="Example:">This is an example of the body of a notification resource for changes where one resource has been deleted:
                          <figure>
                            <artwork><![CDATA[
<?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>]]></artwork>
                          </figure>
                        </t>
                        <t hangText="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:
                          <figure>
                            <artwork><![CDATA[
<?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>]]></artwork>
                          </figure>
                        </t>
                      </list>
                    </t>
                </section>
                <section title="CS:calendar-changes Element Definition" anchor="CS:calendar-changes">
                    <t>
                      <list style="hanging">
                        <t hangText="Name:">calendar-changes</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Indicates which portions of an calendar object resource have changed, or provides details of deleted calendar object resources.</t>
                        <t hangText="Description:">This XML element is used in a CS:updated element to describe how a calendar object resource changed, or in a CS:deleted element to provide details of a deleted resource. It can identify the master instance, or individual recurrence instances, and for each indicate which iCalendar properties and parameters changed during the update for which the notification was generated. For details of handling recurrences please see <xref target="recurrence_changes"/>.</t>
                        <t hangText="Definition:">
                            <figure>
                                <artwork><![CDATA[
<!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 -->]]></artwork>
                            </figure>
                        </t>
                        <t hangText="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.
                            <figure>
                                <artwork><![CDATA[
<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>]]></artwork>
                            </figure>
                        </t>
                        <t hangText="Example:">
                          This example indicates that an instance of a recurring component was changed and that the change was to the "DTSTART" iCalendar property.
                            <figure>
                                <artwork><![CDATA[
<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>]]></artwork>
                            </figure>
                        </t>
                      </list>
                    </t>
                    <section title="Handling Recurrences in CS:calendar-changes" anchor="recurrence_changes">
                      <t>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.
                      <list style="hanging">

                        <t hangText="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.</t>

                        <t hangText="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.</t>

                        <t hangText="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.</t>

                        <t hangText="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.</t>

                        <t hangText="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.</t>

                        <t hangText="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.</t>

                        <t hangText="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.</t>

                        <t hangText="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.</t>
                      </list></t>
                    </section>
                </section>
                <section title="CS:deleted-details Element Definition" anchor="CS:deleted-details">
                    <t>
                      <list style="hanging">
                        <t hangText="Name:">deleted-details</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Provides summary information about a deleted resource or collection.</t>
                        <t hangText="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 of a calendar object resource, the other for deletion of a calendar collection.</t>
                        <t hangText="Definition:">
                            <figure>
                                <artwork><![CDATA[
<!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.  -->]]></artwork>
                            </figure>
                        </t>
                        <t hangText="Example:">
                          This example indicates deletion of a non-recurring event that was yet to occur at the time of deletion.
                            <figure>
                                <artwork><![CDATA[
<CS:deleted-details xmlns:CS="http://calendarserver.org/ns/">
  <CS:deleted-component>VEVENT</CS:deleted-component>
  <CS:deleted-summary>Birthday Party</CS:deleted-summary>
  <CS:deleted-next-instance tzid="America/New_York
  >20120505T120000</CS:deleted-next-instance>
</CS:deleted-details>]]></artwork>
                            </figure>
                        </t>
                        <t hangText="Example:">
                          This example indicates deletion of a calendar.
                            <figure>
                                <artwork><![CDATA[
<CS:deleted-details xmlns:CS="http://calendarserver.org/ns/">
  <CS:deleted-displayname>Holidays</CS:deleted-displayname>
</CS:deleted-details>]]></artwork>
                            </figure>
                        </t>
                      </list>
                    </t>
                </section>
                <section title="CS:notify-changes Property" anchor="CS:notify-changes">
                  <t>
                    <list style="hanging">
                      <t hangText="Name:">notify-changes</t>
                      <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                      <t hangText="Purpose:">Allows a user to specify whether resource change notifications are generated by the server.</t>
                      <t hangText="Protected:">This property MUST NOT be protected.</t>
                      <t hangText="PROPFIND behavior:">This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
                      <t hangText="COPY/MOVE behavior:">This property value MUST be preserved in COPY and MOVE operations.</t>
        
                      <t hangText="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.</t>
                      <t hangText="Definition:">
                        <figure>
                          <artwork><![CDATA[
<!ELEMENT notify-changes (true|false)>
  <!ELEMENT true EMPTY>
  <!ELEMENT false EMPTY>
  
<!-- true - notifications enabled,
     false - notifications disabled -->]]></artwork>
                        </figure>
                      </t>
                    </list>
                  </t>
                </section>
            </section>
        </section>

        <section title='Security Considerations'>
            <t>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.</t>
            <t>
                TBD: More?
            </t>
        </section>
        <section title='IANA Considerations'>
            <t>
                This document does not require any actions on the part of IANA.
            </t>
        </section>
        <section title='Acknowledgments'>
            <t>
                This specification is the result of discussions between the various Apple calendar server and client teams.
            </t>
        </section>
    </middle>
    <back>
        <references title='Normative References'>
            &rfc2119;
            &rfc3339;
            &rfc4918;
        </references>
        <references title='Informative References'>
            &rfc3744;
            &rfc4791;
        </references>
        <section title='Examples'>
            <t>This section provides more detailed examples of resource change notifications for illustrative purposes only.</t>
            <section title="Resource Created">
              <t hangText="Example:">This is an example of the body of a notification resource where one resource has been created.
                <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
            <section title="Resource Updated - Property Change">
              <t hangText="Example:">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.
                <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
            <section title="Resource Updated - Parameter Change">
              <t hangText="Example:">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.
                <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
            <section title="Resource Updated - Multiple Instances Change">
              <t hangText="Example:">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.
                <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
            <section title="Resource Updated - Multiple User Change">
              <t hangText="Example:">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.
                <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
            <section title="Resource Deleted">
              <t hangText="Example:">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.
                <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
            <section title="Collection Created">
              <t hangText="Example:">This is an example of the body of a notification resource where a calendar collection has been created.
                <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
            <section title="Collection Updated">
              <t hangText="Example:">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.
              <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
            <section title="Collection Deleted">
              <t hangText="Example:">This is an example of the body of a notification resource where a calendar collection has been deleted.
                <figure><artwork><![CDATA[
<?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>]]></artwork></figure>
              </t>
            </section>
        </section>
        <!--
        <section title='Change History'>
            <t>Changes in -01:
                <list style='numbers'>
                    <t></t>
                </list>
            </t>
        </section>
        -->
    </back>
</rfc>