1 files changed, 336 insertions, 0 deletions
diff --git a/vendor/sabre/dav/docs/caldav-ctag.txt b/vendor/sabre/dav/docs/caldav-ctag.txt
new file mode 100644
index 000000000..4787ca260
--- /dev/null
+++ b/vendor/sabre/dav/docs/caldav-ctag.txt
@@ -0,0 +1,336 @@
+
+
+
+Calendar Server Extension                                       C. Daboo
+                                                                   Apple
+                                                             May 3, 2007
+
+
+            Calendar Collection Entity Tag (CTag) in CalDAV
+                             caldav-ctag-02
+
+Abstract
+
+   This specification defines an extension to CalDAV that provides a
+   fast way for a client to determine whether the contents of a calendar
+   collection may have changed.
+
+
+Table of Contents
+
+   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
+   2.  Conventions Used in This Document . . . . . . . . . . . . . . . 2
+   3.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+     3.1.  Server  . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+     3.2.  Client  . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+   4.  New features in CalDAV  . . . . . . . . . . . . . . . . . . . . 3
+     4.1.  getctag WebDAV Property . . . . . . . . . . . . . . . . . . 4
+   5.  Security Considerations . . . . . . . . . . . . . . . . . . . . 4
+   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
+   7.  Normative References  . . . . . . . . . . . . . . . . . . . . . 5
+   Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . . . 5
+   Appendix B.  Change History . . . . . . . . . . . . . . . . . . . . 5
+   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo                                                           [Page 1]
+
+                              CalDAV Proxy                      May 2007
+
+
+1.  Introduction
+
+   In CalDAV [RFC4791] calendar data is stored in calendar collection
+   resources.  Clients need to "poll" calendar collections in order to
+   find out what has changed since the last time they examined it.
+   Currently that involves having to do a PROPFIND Depth:1 HTTP request,
+   or a CALDAV:calendar-query REPORT request.  When a calendar
+   collection contains a large number of calendar resources those
+   operations become expensive on the server.
+
+   Calendar users often configure their clients to poll at short time
+   intervals.  So polling traffic to the server will be high, even
+   though the frequency at which changes actually occur to a calendar is
+   typically low.
+
+   To improve on performance, this specification defines a new "calendar
+   collection entity tag" (CTag) WebDAV property that is defined on
+   calendar collections.  When the calendar collection changes, the CTag
+   value changes.  Thus a client can cache the CTag at some point in
+   time, then poll the collection only (i.e.  PROPFIND Depth:0 HTTP
+   requests) and determine if a change has happened based on the
+   returned CTag value.  If there is a change, it can then fall back to
+   doing the full (Depth:1) poll of the collection to actually determine
+   which resources in the collection changed.
+
+   This extension also defines CTag's on CalDAV scheduling
+   [I-D.desruisseaux-caldav-sched] Inbox and Outbox collections.
+
+
+2.  Conventions Used in This Document
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+   document are to be interpreted as described in [RFC2119].
+
+   When XML element types in the namespaces "DAV:" and
+   "urn:ietf:params:xml:ns:caldav" are referenced in this document
+   outside of the context of an XML fragment, the string "DAV:" and
+   "CALDAV:" will be prefixed to the element type names respectively.
+
+   The namespace "http://calendarserver.org/ns/" is used for XML
+   elements defined in this specification.  When XML element types in
+   this 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 respectively.
+
+
+
+
+
+
+Daboo                                                           [Page 2]
+
+                              CalDAV Proxy                      May 2007
+
+
+3.  Overview
+
+3.1.  Server
+
+   For each calendar or scheduling Inbox or Outbox collection on the
+   server, a new CS:getctag WebDAV property is present.
+
+   The property value is an "opaque" token whose value is guaranteed to
+   be unique over the lifetime of any calendar or scheduling Inbox or
+   Outbox collection at a specific URI.
+
+   Whenever a calendar resource is added to, modified or deleted from
+   the calendar collection, the value of the CS:getctag property MUST
+   change.  Typically this change will occur when the DAV:getetag
+   property on a child resource changes due to some protocol action.  It
+   could be the result of a change to the body or properties of the
+   resource.
+
+3.2.  Client
+
+   The client starts off with an empty string as the initial value for
+   the cached CTag of a calendar or scheduling Inbox or Outbox
+   collection that it intends to synchronize with.
+
+   When polling a calendar or scheduling Inbox or Outbox collection, the
+   client issues a PROPFIND Depth:0 HTTP request, asking for the CS:
+   getctag property to be returned.
+
+   If the returned value of CS:getctag property matches the one
+   currently cached for the calendar or scheduling Inbox or Outbox
+   collection, then the collection contents have not changed and no
+   further action is required until the next poll.
+
+   If the returned value of CS:getctag property does not match the one
+   found previously, then the contents of the calendar or scheduling
+   Inbox or Outbox collection have changed.  At that point the client
+   should re-issue the PROPFIND Depth:1 request to get the collection
+   changes in detail and the CS:getctag property value corresponding to
+   the new state.  The new CSgetctag property value should replace the
+   one currently cached for that calendar or scheduling Inbox or Outbox
+   collection.
+
+
+4.  New features in CalDAV
+
+
+
+
+
+
+
+Daboo                                                           [Page 3]
+
+                              CalDAV Proxy                      May 2007
+
+
+4.1.  getctag WebDAV Property
+
+   Name:  getctag
+
+   Namespace:  http://calendarserver.org/ns/
+
+   Purpose:  Specifies a "synchronization" token used to indicate when
+      the contents of a calendar or scheduling Inbox or Outbox
+      collection have changed.
+
+   Conformance:  This property MUST be defined on a calendar or
+      scheduling Inbox or Outbox collection resource.  It MUST be
+      protected and SHOULD be returned by a PROPFIND DAV:allprop request
+      (as defined in Section 12.14.1 of [RFC2518]).
+
+   Description:  The CS:getctag property allows clients to quickly
+      determine if the contents of a calendar or scheduling Inbox or
+      Outbox collection have changed since the last time a
+      "synchronization" operation was done.  The CS:getctag property
+      value MUST change each time the contents of the calendar or
+      scheduling Inbox or Outbox collection change, and each change MUST
+      result in a value that is different from any other used with that
+      collection URI.
+
+   Definition:
+
+       <!ELEMENT getctag #PCDATA>
+
+   Example:
+
+       <T:getctag xmlns:T="http://calendarserver.org/ns/"
+       >ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340</T:getctag>
+
+
+5.  Security Considerations
+
+   The CS:getctag property value changes whenever any resource in the
+   collection or scheduling Inbox or Outbox changes.  Thus a change to a
+   resource that a user does not have read access to will result in a
+   change in the CTag and the user will know that a change occurred.
+   However, that user will not able to get additional details about
+   exactly what changed as WebDAV ACLs [RFC3744] will prevent that.  So
+   this does expose the fact that there are potentially "hidden"
+   resources in a calendar collection, but it does not expose any
+   details about them.
+
+
+
+
+
+
+Daboo                                                           [Page 4]
+
+                              CalDAV Proxy                      May 2007
+
+
+6.  IANA Considerations
+
+   This document does not require any actions on the part of IANA.
+
+
+7.  Normative References
+
+   [I-D.desruisseaux-caldav-sched]
+              Desruisseaux, B., "Scheduling Extensions to CalDAV",
+              draft-desruisseaux-caldav-sched-03 (work in progress),
+              January 2007.
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC2518]  Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
+              Jensen, "HTTP Extensions for Distributed Authoring --
+              WEBDAV", RFC 2518, February 1999.
+
+   [RFC3744]  Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
+              Distributed Authoring and Versioning (WebDAV) Access
+              Control Protocol", RFC 3744, May 2004.
+
+   [RFC4791]  Daboo, C., Desruisseaux, B., and L. Dusseault,
+              "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
+              March 2007.
+
+
+Appendix A.  Acknowledgments
+
+   This specification is the result of discussions between the Apple
+   calendar server and client teams.
+
+
+Appendix B.  Change History
+
+   Changes from -01:
+
+   1.  Updated to RFC4791 reference.
+
+   2.  Added text indicating that ctag applies to schedule Inbox and
+       Outbox as well.
+
+   Changes from -00:
+
+   1.  Relaxed requirement so that any type of change to a child
+       resource can trigger a CTag change (similar behavior to ETag).
+
+
+
+
+Daboo                                                           [Page 5]
+
+                              CalDAV Proxy                      May 2007
+
+
+Author's Address
+
+   Cyrus Daboo
+   Apple Inc.
+   1 Infinite Loop
+   Cupertino, CA  95014
+   USA
+
+   Email: cyrus@daboo.name
+   URI:   http://www.apple.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo                                                           [Page 6]
+