dav/SabreDAV/docs/caldav-notifications.txt

   1
   2
   3
   4 Calendar Server Extension                                       C. Daboo
   5                                                               Apple Inc.
   6                                                           March 19, 2012
   7
   8
   9                   CalDAV: Calendar User Notifications
  10
  11 Abstract
  12
  13    This specification defines an extension to CalDAV that allows the
  14    server to provide notifications to calendar users.
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55 Daboo                                                           [Page 1]
  56 \f
  57                         CalDAV User Notifications             March 2012
  58
  59
  60 Table of Contents
  61
  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
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111 Daboo                                                           [Page 2]
 112 \f
 113                         CalDAV User Notifications             March 2012
 114
 115
 116 1.  Introduction
 117
 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.
 122
 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].
 129
 130
 131 2.  Open Issues
 132
 133    1.  Define specific child elements for system status notification,
 134        e.g. "server-maintenance-period", "server-read-only-period",
 135        "client-upgrade-required".
 136
 137
 138 3.  Conventions Used in This Document
 139
 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].
 143
 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.
 148
 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
 153    type names.
 154
 155
 156 4.  Notifications
 157
 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.
 164
 165
 166
 167 Daboo                                                           [Page 3]
 168 \f
 169                         CalDAV User Notifications             March 2012
 170
 171
 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.
 175
 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.
 183
 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.
 189
 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.
 207
 208    Servers MUST prevent clients from adding resources in the
 209    notification collection.
 210
 211 4.1.  Additional Principal Properties
 212
 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
 216    users.
 217
 218
 219
 220
 221
 222
 223 Daboo                                                           [Page 4]
 224 \f
 225                         CalDAV User Notifications             March 2012
 226
 227
 228 4.1.1.  CS:notification-URL Property
 229
 230    Name:  notification-URL
 231
 232    Namespace:  http://calendarserver.org/ns/
 233
 234    Purpose:  Identify the URL of the notification collection owned by
 235       the associated principal resource.
 236
 237    Protected:  This property SHOULD be protected.
 238
 239    PROPFIND behavior:  This property SHOULD NOT be returned by a
 240       PROPFIND allprop request (as defined in Section 14.2 of
 241       [RFC4918]).
 242
 243    COPY/MOVE behavior:  This property value SHOULD be preserved in COPY
 244       and MOVE operations.
 245
 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.
 251
 252    Definition:
 253
 254    <!ELEMENT notification-URL (DAV:href)>
 255
 256 4.2.  Properties on Notification Resources
 257
 258    The following new WebDAV properties are defined for notification
 259    resources.
 260
 261 4.2.1.  CS:notificationtype Property
 262
 263    Name:  notificationtype
 264
 265    Namespace:  http://calendarserver.org/ns/
 266
 267    Purpose:  Identify the type of notification of the corresponding
 268       resource.
 269
 270    Protected:  This property MUST be protected.
 271
 272    PROPFIND behavior:  This property SHOULD NOT be returned by a
 273       PROPFIND allprop request (as defined in Section 14.2 of
 274       [RFC4918]).
 275
 276
 277
 278
 279 Daboo                                                           [Page 5]
 280 \f
 281                         CalDAV User Notifications             March 2012
 282
 283
 284    COPY/MOVE behavior:  This property value MUST be preserved in COPY
 285       and MOVE operations.
 286
 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.
 294
 295    Definition:
 296
 297    <!ELEMENT notificationtype ANY>
 298    <!-- Child elements are empty but will have appropriate attributes.
 299         Any valid notification message child element can appear.-->
 300
 301 4.3.  XML Element Definitions
 302
 303 4.3.1.  CS:notifications
 304
 305    Name:  notifications
 306
 307    Namespace:  http://calendarserver.org/ns/
 308
 309    Purpose:  Indicates a notification collection.
 310
 311    Description:  This XML element is used in a DAV:resourcetype element
 312       to indicate that the corresponding resource is a notification
 313       collection.
 314
 315    Definition:
 316
 317    <!ELEMENT notifications EMPTY>
 318
 319 4.3.2.  CS:notification
 320
 321    Name:  notification
 322
 323    Namespace:  http://calendarserver.org/ns/
 324
 325    Purpose:  Notification message root element.
 326
 327    Description:  The root element used in notification resources.
 328
 329
 330
 331
 332
 333
 334
 335 Daboo                                                           [Page 6]
 336 \f
 337                         CalDAV User Notifications             March 2012
 338
 339
 340    Definition:
 341
 342    <!ELEMENT notification (dtstamp, XXX) >
 343    <!-- Any notification type element can appear after
 344         CS:dtstamp -->
 345
 346 4.3.3.  CS:dtstamp
 347
 348    Name:  dtstamp
 349
 350    Namespace:  http://calendarserver.org/ns/
 351
 352    Purpose:  Date-time stamp.
 353
 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.
 358
 359    Definition:
 360
 361    <!ELEMENT dtstamp (#PCDATA)>
 362    <!-- Value is a date-time in UTZ as per [RFC3339] with
 363         "compact" format allowed.-->
 364
 365
 366 5.  Notification Definitions
 367
 368    This section defines a set of common notification types.
 369
 370 5.1.  System Status Notification
 371
 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
 379    respectively.
 380
 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.
 386
 387
 388
 389
 390
 391 Daboo                                                           [Page 7]
 392 \f
 393                         CalDAV User Notifications             March 2012
 394
 395
 396 5.1.1.  CS:systemstatus Element Definition
 397
 398    Name:  systemstatus
 399
 400    Namespace:  http://calendarserver.org/ns/
 401
 402    Purpose:  Indicates a system status notification.
 403
 404    Description:  This XML element is used in a CS:notification element
 405       to describe a system status notification.
 406
 407    Definition:
 408
 409    <!ELEMENT systemstatus (DAV:href?, CS:description?)>
 410    <!ATTLIST systemstatus type (low | medium | high) "low">
 411
 412      <!ELEMENT description CDATA>
 413
 414    <!-- One of DAV:href of CS:description MUST be present -->
 415
 416    Example:  This is an example of the body of a notification resource
 417       for an emergency system outage:
 418
 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>
 427      </CS:systemstatus>
 428    </CS:notification>
 429
 430    Example:  This is an example of the WebDAV property on the example
 431       notification resource above:
 432
 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>
 438
 439 5.2.  Quota Notification
 440
 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
 444
 445
 446
 447 Daboo                                                           [Page 8]
 448 \f
 449                         CalDAV User Notifications             March 2012
 450
 451
 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
 454    their quota).
 455
 456 5.2.1.  CS:quotastatus Element Definition
 457
 458    Name:  quotastatus
 459
 460    Namespace:  http://calendarserver.org/ns/
 461
 462    Purpose:  Indicates a quota status notification.
 463
 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.
 471
 472    Definition:
 473
 474    <!ELEMENT quota-status (quota+)>
 475
 476      <!ELEMENT quota (quota-type, quota-percent-used?,
 477                       quota-count?, DAV:href?)>
 478      <!ATTLIST quota type (warning | exceeded) "exceeded">
 479
 480      <!ELEMENT quota-type ANY>
 481      <!-- Child elements are application specific -->
 482
 483      <!ELEMENT quota-percent-used CDATA>
 484      <!-- Integer value greater than or equal to zero -->
 485
 486      <!ELEMENT quota-count CDATA>
 487      <!-- Integer value greater than or equal to zero -->
 488
 489    Example:  This is an example of the body of a notification resource
 490       for a quota warning:
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503 Daboo                                                           [Page 9]
 504 \f
 505                         CalDAV User Notifications             March 2012
 506
 507
 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>
 512      <CS:quota-status>
 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>
 517        </CS:quota>
 518      </CS:quota-status>
 519    </CS:notification>
 520
 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:
 524
 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>
 529      <CS:quota-status>
 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>
 534        </CS:quota>
 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>
 540        </CS:quota>
 541      </CS:quota-status>
 542    </CS:notification>
 543
 544 5.3.  Resource Changes Notification
 545
 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
 556
 557
 558
 559 Daboo                                                          [Page 10]
 560 \f
 561                         CalDAV User Notifications             March 2012
 562
 563
 564    next synchronize the notification collection.
 565
 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.
 572
 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.
 581
 582 5.3.1.  CS:resource-change Element Definition
 583
 584    Name:  resource-change
 585
 586    Namespace:  http://calendarserver.org/ns/
 587
 588    Purpose:  Indicates that resources have been created, updated or
 589       deleted.
 590
 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
 594       collection.
 595
 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
 612
 613
 614
 615 Daboo                                                          [Page 11]
 616 \f
 617                         CalDAV User Notifications             March 2012
 618
 619
 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.
 625
 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.
 634
 635    Definition:
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671 Daboo                                                          [Page 12]
 672 \f
 673                         CalDAV User Notifications             March 2012
 674
 675
 676    <!ELEMENT resource-change (created | updated+ | deleted |
 677                               collection-changes)>
 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)>
 683
 684      <!ELEMENT changed-by (common-name | (first-name, last-name),
 685                            dtstamp?, DAV:href)>
 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
 695           the change. -->
 696
 697      <!ELEMENT collection-changes (DAV:href, changed-by*, DAV:prop?,
 698                                    child-created?, child-updated?,
 699                                    child-deleted?>
 700        <!-- When coalescing changes from multiple users, the changed-by
 701             element can appear more than once. -->
 702
 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. -->
 709
 710    Example:  This is an example of the body of a notification resource
 711       for changes where one resource has been created:
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727 Daboo                                                          [Page 13]
 728 \f
 729                         CalDAV User Notifications             March 2012
 730
 731
 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>
 736      <CS:resource-change>
 737        <CS:created>
 738          <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
 739          <CS:changed-by>
 740            <CS:common-name>Cyrus Daboo</CS:common-name>
 741            <D:href>/principals/cyrusdaboo</D:href>
 742          </CS:changed-by>
 743        </CS:created>
 744      </CS:resource-change>
 745    </CS:notification>
 746
 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
 751       changed:
 752
 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>
 757      <CS:resource-change>
 758        <CS:updated>
 759          <D:href>http://example.com/cyrus/calendar/event.ics</D:href>
 760          <CS:changed-by>
 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>
 764          </CS:changed-by>
 765        </CS:updated>
 766        <CS:updated>
 767          <D:href>http://example.com/cyrus/calendar/event.ics</D:href>
 768          <CS:changed-by>
 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>
 772          </CS:changed-by>
 773        </CS:updated>
 774      </CS:resource-change>
 775    </CS:notification>
 776
 777
 778
 779
 780
 781
 782
 783 Daboo                                                          [Page 14]
 784 \f
 785                         CalDAV User Notifications             March 2012
 786
 787
 788    Example:  This is an example of the body of a notification resource
 789       for changes where one resource has been deleted:
 790
 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>
 795      <CS:resource-change>
 796        <CS:deleted>
 797          <D:href>http://example.com/cyrus/calendar/old.ics</D:href>
 798          <CS:changed-by>
 799            <CS:first-name>Cyrus</CS:first-name>
 800            <CS:last-name>Daboo</CS:last-name>
 801            <D:href>/principals/cyrusdaboo</D:href>
 802          </CS:changed-by>
 803        </CS:deleted>
 804      </CS:resource-change>
 805    </CS:notification>
 806
 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
 810       collection:
 811
 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>
 816      <CS:resource-change>
 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>
 824    </CS:notification>
 825
 826 5.3.2.  CS:calendar-changes Element Definition
 827
 828    Name:  calendar-changes
 829
 830    Namespace:  http://calendarserver.org/ns/
 831
 832    Purpose:  Indicates which portions of an calendar object resource
 833       have changed, or provides details of deleted calendar object
 834       resources.
 835
 836
 837
 838
 839 Daboo                                                          [Page 15]
 840 \f
 841                         CalDAV User Notifications             March 2012
 842
 843
 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
 851       Section 5.3.2.1.
 852
 853    Definition:
 854
 855    <!ELEMENT calendar-changes (recurrence+) >
 856
 857      <!ELEMENT recurrence
 858          ((master | recurrenceid), added?, removed?, changes?)>
 859      <!-- Which instances were affected by the change,
 860           and details on the per-instance changes -->
 861
 862        <!ELEMENT master EMPTY>
 863        <!-- The "master" instance was affected -->
 864
 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 -->
 868
 869        <!ELEMENT added EMPTY>
 870        <!-- The component was added -->
 871
 872        <!ELEMENT removed EMPTY>
 873        <!-- The component was removed -->
 874
 875        <!ELEMENT changes changed-property*>
 876        <!-- Detailed changes in the iCalendar data -->
 877
 878          <!ELEMENT changed-property changed-parameter*>
 879          <!ATTLIST changed-property name PCDATA>
 880          <!-- An iCalendar property changed -->
 881
 882            <!ELEMENT changed-parameter EMPTY>
 883            <!ATTLIST changed-parameter name PCDATA>
 884            <!-- An iCalendar property parameter changed -->
 885
 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.
 889
 890
 891
 892
 893
 894
 895 Daboo                                                          [Page 16]
 896 \f
 897                         CalDAV User Notifications             March 2012
 898
 899
 900    <CS:calendar-changes xmlns:CS="http://calendarserver.org/ns/">
 901      <CS:recurrence>
 902        <CS:master/>
 903        <CS:changes>
 904          <CS:changed-property name="SUMMARY"/>
 905        </CS:changes>
 906      </CS:recurrence>
 907    </CS:calendar-changes>
 908
 909    Example:  This example indicates that an instance of a recurring
 910       component was changed and that the change was to the "DTSTART"
 911       iCalendar property.
 912
 913    <CS:calendar-changes xmlns:CS="http://calendarserver.org/ns/">
 914      <CS:recurrence>
 915        <CS:recurrenceid>20111215T160000Z</CS:recurrenceid>
 916        <CS:changes>
 917          <CS:changed-property name="DTSTART"/>
 918        </CS:changes>
 919      </CS:recurrence>
 920    </CS:calendar-changes>
 921
 922 5.3.2.1.  Handling Recurrences in CS:calendar-changes
 923
 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.
 927
 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.
 933
 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.
 939
 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.
 945
 946
 947
 948
 949
 950
 951 Daboo                                                          [Page 17]
 952 \f
 953                         CalDAV User Notifications             March 2012
 954
 955
 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
 962       instance.
 963
 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
 971       "EXDATE" properties.
 972
 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.
 978
 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.
 984
 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.
 990
 991 5.3.3.  CS:deleted-details Element Definition
 992
 993    Name:  deleted-details
 994
 995    Namespace:  http://calendarserver.org/ns/
 996
 997    Purpose:  Provides summary information about a deleted resource or
 998       collection.
 999
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
1004
1005
1006
1007 Daboo                                                          [Page 18]
1008 \f
1009                         CalDAV User Notifications             March 2012
1010
1011
1012       of a calendar object resource, the other for deletion of a
1013       calendar collection.
1014
1015    Definition:
1016
1017    <!ELEMENT deleted-details ((deleted-component,
1018                                deleted-summary,
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. -->
1024
1025      <!ELEMENT deleted-component CDATA>
1026      <!-- The main calendar component type of the deleted
1027           resource, e.g., "VEVENT", "VTODO" -->
1028
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. -->
1033
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. -->
1042
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. -->
1046
1047      <!ELEMENT deleted-displayname CDATA>
1048      <!-- The DAV:getdisplayname property for the collection that
1049           was deleted.  -->
1050
1051    Example:  This example indicates deletion of a non-recurring event
1052       that was yet to occur at the time of deletion.
1053
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>
1060
1061
1062
1063 Daboo                                                          [Page 19]
1064 \f
1065                         CalDAV User Notifications             March 2012
1066
1067
1068    Example:  This example indicates deletion of a calendar.
1069
1070    <CS:deleted-details xmlns:CS="http://calendarserver.org/ns/">
1071      <CS:deleted-displayname>Holidays</CS:deleted-displayname>
1072    </CS:deleted-details>
1073
1074 5.3.4.  CS:notify-changes Property
1075
1076    Name:  notify-changes
1077
1078    Namespace:  http://calendarserver.org/ns/
1079
1080    Purpose:  Allows a user to specify whether resource change
1081       notifications are generated by the server.
1082
1083    Protected:  This property MUST NOT be protected.
1084
1085    PROPFIND behavior:  This property SHOULD NOT be returned by a
1086       PROPFIND allprop request (as defined in Section 14.2 of
1087       [RFC4918]).
1088
1089    COPY/MOVE behavior:  This property value MUST be preserved in COPY
1090       and MOVE operations.
1091
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.
1098
1099    Definition:
1100
1101    <!ELEMENT notify-changes (true|false)>
1102      <!ELEMENT true EMPTY>
1103      <!ELEMENT false EMPTY>
1104
1105    <!-- true - notifications enabled,
1106         false - notifications disabled -->
1107
1108
1109 6.  Security Considerations
1110
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
1115    notifications.
1116
1117
1118
1119 Daboo                                                          [Page 20]
1120 \f
1121                         CalDAV User Notifications             March 2012
1122
1123
1124    TBD: More?
1125
1126
1127 7.  IANA Considerations
1128
1129    This document does not require any actions on the part of IANA.
1130
1131
1132 8.  Acknowledgments
1133
1134    This specification is the result of discussions between the various
1135    Apple calendar server and client teams.
1136
1137
1138 9.  References
1139
1140 9.1.  Normative References
1141
1142    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
1143               Requirement Levels", BCP 14, RFC 2119, March 1997.
1144
1145    [RFC3339]  Klyne, G., Ed. and C. Newman, "Date and Time on the
1146               Internet: Timestamps", RFC 3339, July 2002.
1147
1148    [RFC4918]  Dusseault, L., "HTTP Extensions for Web Distributed
1149               Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
1150
1151 9.2.  Informative References
1152
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.
1156
1157    [RFC4791]  Daboo, C., Desruisseaux, B., and L. Dusseault,
1158               "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
1159               March 2007.
1160
1161
1162 Appendix A.  Examples
1163
1164    This section provides more detailed examples of resource change
1165    notifications for illustrative purposes only.
1166
1167 A.1.  Resource Created
1168
1169    This is an example of the body of a notification resource where one
1170    resource has been created.
1171
1172
1173
1174
1175 Daboo                                                          [Page 21]
1176 \f
1177                         CalDAV User Notifications             March 2012
1178
1179
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>
1185        <CS:created>
1186          <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1187          <CS:changed-by>
1188            <CS:first-name>Cyrus</CS:first-name>
1189            <CS:last-name>Daboo</CS:last-name>
1190            <D:href>/principals/cyrusdaboo</D:href>
1191          </CS:changed-by>
1192        </CS:created>
1193      </CS:resource-change>
1194    </CS:notification>
1195
1196 A.2.  Resource Updated - Property Change
1197
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.
1201
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>
1207        <CS:updated>
1208          <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1209          <CS:changed-by>
1210            <CS:first-name>Cyrus</CS:first-name>
1211            <CS:last-name>Daboo</CS:last-name>
1212            <D:href>/principals/cyrusdaboo</D:href>
1213          </CS:changed-by>
1214          <CS:calendar-changes>
1215            <CS:recurrence>
1216              <CS:master/>
1217              <CS:changes>
1218                <CS:changed-property name="DTSTART"/>
1219                <CS:changed-property name="SUMMARY"/>
1220              </CS:changes>
1221            </CS:recurrence>
1222          </CS:calendar-changes>
1223        </CS:updated>
1224      </CS:resource-change>
1225    </CS:notification>
1226
1227
1228
1229
1230
1231 Daboo                                                          [Page 22]
1232 \f
1233                         CalDAV User Notifications             March 2012
1234
1235
1236 A.3.  Resource Updated - Parameter Change
1237
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
1241    added.
1242
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>
1248        <CS:updated>
1249          <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1250          <CS:changed-by>
1251            <CS:first-name>Cyrus</CS:first-name>
1252            <CS:last-name>Daboo</CS:last-name>
1253            <D:href>/principals/cyrusdaboo</D:href>
1254          </CS:changed-by>
1255          <CS:calendar-changes>
1256            <CS:recurrence>
1257              <CS:master/>
1258              <CS:added>
1259                <CS:changed-property name="TRANSP"/>
1260              </CS:added>
1261              <CS:changes>
1262                <CS:changed-property name="ATTENDEE">
1263                  <CS:changed-parameter name="PARTSTAT"/>
1264                </CS:changed-property>
1265              </CS:changes>
1266            </CS:recurrence>
1267          </CS:calendar-changes>
1268        </CS:updated>
1269      </CS:resource-change>
1270    </CS:notification>
1271
1272 A.4.  Resource Updated - Multiple Instances Change
1273
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.
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287 Daboo                                                          [Page 23]
1288 \f
1289                         CalDAV User Notifications             March 2012
1290
1291
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>
1297        <CS:updated>
1298          <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1299          <CS:changed-by>
1300            <CS:first-name>Cyrus</CS:first-name>
1301            <CS:last-name>Daboo</CS:last-name>
1302            <D:href>/principals/cyrusdaboo</D:href>
1303          </CS:changed-by>
1304          <CS:calendar-changes>
1305            <CS:recurrence>
1306              <CS:recurrenceid>20120209T170000Z</CS:recurrenceid>
1307              <CS:changes>
1308                <CS:changed-property name="DTSTART"/>
1309                <CS:changed-property name="SUMMARY"/>
1310              </CS:changes>
1311            </CS:recurrence>
1312            <CS:recurrence>
1313              <CS:recurrenceid>20120210T170000Z</CS:recurrenceid>
1314              <CS:changes>
1315                <CS:changed-property name="DTSTART"/>
1316                <CS:changed-property name="SUMMARY"/>
1317              </CS:changes>
1318            </CS:recurrence>
1319          </CS:calendar-changes>
1320        </CS:updated>
1321      </CS:resource-change>
1322    </CS:notification>
1323
1324 A.5.  Resource Updated - Multiple User Change
1325
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
1329    different user.
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343 Daboo                                                          [Page 24]
1344 \f
1345                         CalDAV User Notifications             March 2012
1346
1347
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>
1353        <CS:updated>
1354          <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1355          <CS:changed-by>
1356            <CS:first-name>Cyrus</CS:first-name>
1357            <CS:last-name>Daboo</CS:last-name>
1358            <D:href>/principals/cyrusdaboo</D:href>
1359          </CS:changed-by>
1360          <CS:calendar-changes>
1361            <CS:recurrence>
1362              <CS:recurrenceid>20120209T170000Z</CS:recurrenceid>
1363              <CS:changes>
1364                <CS:changed-property name="DTSTART"/>
1365                <CS:changed-property name="SUMMARY"/>
1366              </CS:changes>
1367            </CS:recurrence>
1368          </CS:calendar-changes>
1369        </CS:updated>
1370        <CS:updated>
1371          <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1372          <CS:changed-by>
1373            <CS:first-name>Eric</CS:first-name>
1374            <CS:last-name>York</CS:last-name>
1375            <D:href>/principals/ericyork</D:href>
1376          </CS:changed-by>
1377          <CS:calendar-changes>
1378            <CS:recurrence>
1379              <CS:recurrenceid>20120210T170000Z</CS:recurrenceid>
1380              <CS:changes>
1381                <CS:changed-property name="DTSTART"/>
1382                <CS:changed-property name="SUMMARY"/>
1383              </CS:changes>
1384            </CS:recurrence>
1385          </CS:calendar-changes>
1386        </CS:updated>
1387      </CS:resource-change>
1388    </CS:notification>
1389
1390 A.6.  Resource Deleted
1391
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.
1395
1396
1397
1398
1399 Daboo                                                          [Page 25]
1400 \f
1401                         CalDAV User Notifications             March 2012
1402
1403
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>
1409        <CS:deleted>
1410          <D:href>http://example.com/cyrus/calendar/new.ics</D:href>
1411          <CS:changed-by>
1412            <CS:first-name>Cyrus</CS:first-name>
1413            <CS:last-name>Daboo</CS:last-name>
1414            <D:href>/principals/cyrusdaboo</D:href>
1415          </CS:changed-by>
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>
1422        </CS:deleted>
1423      </CS:resource-change>
1424    </CS:notification>
1425
1426 A.7.  Collection Created
1427
1428    This is an example of the body of a notification resource where a
1429    calendar collection has been created.
1430
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>
1436        <CS:created>
1437          <D:href>http://example.com/cyrus/new-calendar/</D:href>
1438          <CS:changed-by>
1439            <CS:first-name>Cyrus</CS:first-name>
1440            <CS:last-name>Daboo</CS:last-name>
1441            <D:href>/principals/cyrusdaboo</D:href>
1442          </CS:changed-by>
1443        </CS:created>
1444      </CS:resource-change>
1445    </CS:notification>
1446
1447 A.8.  Collection Updated
1448
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.
1452
1453
1454
1455 Daboo                                                          [Page 26]
1456 \f
1457                         CalDAV User Notifications             March 2012
1458
1459
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>
1472    </CS:notification>
1473
1474 A.9.  Collection Deleted
1475
1476    This is an example of the body of a notification resource where a
1477    calendar collection has been deleted.
1478
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>
1484        <CS:deleted>
1485          <D:href>http://example.com/cyrus/old-calendar/</D:href>
1486          <CS:changed-by>
1487            <CS:first-name>Cyrus</CS:first-name>
1488            <CS:last-name>Daboo</CS:last-name>
1489            <D:href>/principals/cyrusdaboo</D:href>
1490          </CS:changed-by>
1491          <CS:deleted-details>
1492            <CS:deleted-displayname>Holidays</CS:deleted-displayname>
1493          </CS:deleted-details>
1494        </CS:deleted>
1495      </CS:resource-change>
1496    </CS:notification>
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511 Daboo                                                          [Page 27]
1512 \f
1513                         CalDAV User Notifications             March 2012
1514
1515
1516 Author's Address
1517
1518    Cyrus Daboo
1519    Apple Inc.
1520    1 Infinite Loop
1521    Cupertino, CA  95014
1522    USA
1523
1524    Email: cyrus@daboo.name
1525    URI:   http://www.apple.com/
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567 Daboo                                                          [Page 28]
1568 \f