{"payload":{"allShortcutsEnabled":false,"fileTree":{"doc/Extensions":{"items":[{"name":"caldav-ctag.txt","path":"doc/Extensions/caldav-ctag.txt","contentType":"file"},{"name":"caldav-ctag.xml","path":"doc/Extensions/caldav-ctag.xml","contentType":"file"},{"name":"caldav-notifications.txt","path":"doc/Extensions/caldav-notifications.txt","contentType":"file"},{"name":"caldav-notifications.xml","path":"doc/Extensions/caldav-notifications.xml","contentType":"file"},{"name":"caldav-privatecomments.txt","path":"doc/Extensions/caldav-privatecomments.txt","contentType":"file"},{"name":"caldav-privatecomments.xml","path":"doc/Extensions/caldav-privatecomments.xml","contentType":"file"},{"name":"caldav-privateevents.txt","path":"doc/Extensions/caldav-privateevents.txt","contentType":"file"},{"name":"caldav-privateevents.xml","path":"doc/Extensions/caldav-privateevents.xml","contentType":"file"},{"name":"caldav-proxy.txt","path":"doc/Extensions/caldav-proxy.txt","contentType":"file"},{"name":"caldav-proxy.xml","path":"doc/Extensions/caldav-proxy.xml","contentType":"file"},{"name":"caldav-pubsubdiscovery.txt","path":"doc/Extensions/caldav-pubsubdiscovery.txt","contentType":"file"},{"name":"caldav-pubsubdiscovery.xml","path":"doc/Extensions/caldav-pubsubdiscovery.xml","contentType":"file"},{"name":"caldav-recursplit.txt","path":"doc/Extensions/caldav-recursplit.txt","contentType":"file"},{"name":"caldav-recursplit.xml","path":"doc/Extensions/caldav-recursplit.xml","contentType":"file"},{"name":"caldav-schedulingchanges.txt","path":"doc/Extensions/caldav-schedulingchanges.txt","contentType":"file"},{"name":"caldav-schedulingchanges.xml","path":"doc/Extensions/caldav-schedulingchanges.xml","contentType":"file"},{"name":"caldav-sharing.txt","path":"doc/Extensions/caldav-sharing.txt","contentType":"file"},{"name":"caldav-sharing.xml","path":"doc/Extensions/caldav-sharing.xml","contentType":"file"},{"name":"calendarserver-bulk-change.txt","path":"doc/Extensions/calendarserver-bulk-change.txt","contentType":"file"},{"name":"calendarserver-bulk-change.xml","path":"doc/Extensions/calendarserver-bulk-change.xml","contentType":"file"},{"name":"icalendar-maskuids.txt","path":"doc/Extensions/icalendar-maskuids.txt","contentType":"file"},{"name":"icalendar-maskuids.xml","path":"doc/Extensions/icalendar-maskuids.xml","contentType":"file"}],"totalCount":22},"doc":{"items":[{"name":"Admin","path":"doc/Admin","contentType":"directory"},{"name":"Client-Server","path":"doc/Client-Server","contentType":"directory"},{"name":"Developer","path":"doc/Developer","contentType":"directory"},{"name":"Extensions","path":"doc/Extensions","contentType":"directory"},{"name":"Notes","path":"doc/Notes","contentType":"directory"},{"name":"OracleVM","path":"doc/OracleVM","contentType":"directory"},{"name":"RFC","path":"doc/RFC","contentType":"directory"},{"name":"caldavd.8","path":"doc/caldavd.8","contentType":"file"},{"name":"calendarserver_command_gateway.8","path":"doc/calendarserver_command_gateway.8","contentType":"file"},{"name":"calendarserver_config.8","path":"doc/calendarserver_config.8","contentType":"file"},{"name":"calendarserver_export.8","path":"doc/calendarserver_export.8","contentType":"file"},{"name":"calendarserver_manage_principals.8","path":"doc/calendarserver_manage_principals.8","contentType":"file"},{"name":"calendarserver_manage_push.8","path":"doc/calendarserver_manage_push.8","contentType":"file"},{"name":"calendarserver_manage_timezones.8","path":"doc/calendarserver_manage_timezones.8","contentType":"file"},{"name":"calendarserver_migrate_resources.8","path":"doc/calendarserver_migrate_resources.8","contentType":"file"},{"name":"calendarserver_migrate_wiki.8","path":"doc/calendarserver_migrate_wiki.8","contentType":"file"},{"name":"calendarserver_monitor_notifications.8","path":"doc/calendarserver_monitor_notifications.8","contentType":"file"},{"name":"calendarserver_purge_attachments.8","path":"doc/calendarserver_purge_attachments.8","contentType":"file"},{"name":"calendarserver_purge_events.8","path":"doc/calendarserver_purge_events.8","contentType":"file"},{"name":"calendarserver_purge_principals.8","path":"doc/calendarserver_purge_principals.8","contentType":"file"},{"name":"calendarserver_shell.8","path":"doc/calendarserver_shell.8","contentType":"file"}],"totalCount":21},"":{"items":[{"name":"bin","path":"bin","contentType":"directory"},{"name":"calendarserver","path":"calendarserver","contentType":"directory"},{"name":"conf","path":"conf","contentType":"directory"},{"name":"contrib","path":"contrib","contentType":"directory"},{"name":"doc","path":"doc","contentType":"directory"},{"name":"lib-patches","path":"lib-patches","contentType":"directory"},{"name":"locales","path":"locales","contentType":"directory"},{"name":"simplugin","path":"simplugin","contentType":"directory"},{"name":"support","path":"support","contentType":"directory"},{"name":"twisted","path":"twisted","contentType":"directory"},{"name":"twistedcaldav","path":"twistedcaldav","contentType":"directory"},{"name":"txdav","path":"txdav","contentType":"directory"},{"name":"txweb2","path":"txweb2","contentType":"directory"},{"name":".gitignore","path":".gitignore","contentType":"file"},{"name":".project","path":".project","contentType":"file"},{"name":".pydevproject","path":".pydevproject","contentType":"file"},{"name":".travis.yml","path":".travis.yml","contentType":"file"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","contentType":"file"},{"name":"HACKING.rst","path":"HACKING.rst","contentType":"file"},{"name":"LICENSE.txt","path":"LICENSE.txt","contentType":"file"},{"name":"PULL_REQUEST_TEMPLATE.md","path":"PULL_REQUEST_TEMPLATE.md","contentType":"file"},{"name":"README.rst","path":"README.rst","contentType":"file"},{"name":"requirements-cs.txt","path":"requirements-cs.txt","contentType":"file"},{"name":"requirements-default.txt","path":"requirements-default.txt","contentType":"file"},{"name":"requirements-dev.txt","path":"requirements-dev.txt","contentType":"file"},{"name":"requirements-ignore-installed.txt","path":"requirements-ignore-installed.txt","contentType":"file"},{"name":"requirements-osx.txt","path":"requirements-osx.txt","contentType":"file"},{"name":"requirements-twisted-default.txt","path":"requirements-twisted-default.txt","contentType":"file"},{"name":"requirements-twisted-osx.txt","path":"requirements-twisted-osx.txt","contentType":"file"},{"name":"setup.py","path":"setup.py","contentType":"file"}],"totalCount":30}},"fileTreeProcessingTime":38.235053,"foldersToFetch":[],"repo":{"id":64889658,"defaultBranch":"master","name":"ccs-calendarserver","ownerLogin":"apple","currentUserCanPush":false,"isFork":false,"isEmpty":false,"createdAt":"2016-08-04T00:52:17.000Z","ownerAvatar":"https://avatars.githubusercontent.com/u/10639145?v=4","public":true,"private":false,"isOrgOwned":true},"symbolsExpanded":false,"treeExpanded":true,"refInfo":{"name":"master","listCacheKey":"v0:1572616090.0","canEdit":false,"refType":"branch","currentOid":"13c706b985fb728b9aab42dc0fef85aae21921c3"},"path":"doc/Extensions/caldav-ctag.txt","currentUser":null,"blob":{"rawLines":["","","",""," C. Daboo"," Apple"," May 27, 2015","",""," Calendar Collection Entity Tag (CTag) in CalDAV"," caldav-ctag-03","","Abstract",""," IMPORTANT: The feature defined by this specification is now"," deprecated in favor of support for the WebDAV Sync REPORT as defined"," by [RFC6578]. Clients MUST NOT rely on this feature to detect"," changes to collections, instead they MUST support the WebDAV Sync"," REPORT. Servers MUST support the WebDAV Sync REPORT to allow clients"," to efficiently synchronize calendar collections. Whilst most modern"," clients do support the WebDAV Sync REPORT, servers MAY continue to"," support this specification by simply using the DAV:sync-token"," property value for the getctag property value, in order to provide"," backwards compatibility with old clients.",""," 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 . . . . . . . . . . . . . . . . . . . . . . . . 1"," 2. Conventions Used in This Document . . . . . . . . . . . . . . 2"," 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2"," 3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . 2"," 3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . 3"," 4. New features in CalDAV . . . . . . . . . . . . . . . . . . . 3"," 4.1. getctag WebDAV Property . . . . . . . . . . . . . . . . . 3"," 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4"," 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4"," 7. Normative References . . . . . . . . . . . . . . . . . . . . 4"," Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 5"," Appendix B. Change History . . . . . . . . . . . . . . . . . . . 5"," Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5","","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","","","","Daboo Expires November 28, 2015 [Page 1]","\f"," CalDAV CTag May 2015","",""," 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 [RFC6638]"," 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.","","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.","","","","Daboo Expires November 28, 2015 [Page 2]","\f"," CalDAV CTag May 2015","",""," 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 CS:getctag property value should replace the"," one currently cached for that calendar or scheduling Inbox or Outbox"," collection.","","4. New features in CalDAV","","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]).","","","","","Daboo Expires November 28, 2015 [Page 3]","\f"," CalDAV CTag May 2015","",""," 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:",""," ",""," Example:",""," ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340","","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.","","6. IANA Considerations",""," This document does not require any actions on the part of IANA.","","7. Normative References",""," [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.","","","","","","Daboo Expires November 28, 2015 [Page 4]","\f"," CalDAV CTag May 2015","",""," [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,"," \"Calendaring Extensions to WebDAV (CalDAV)\", RFC 4791,"," March 2007.",""," [RFC6578] Daboo, C. and A. Quillaud, \"Collection Synchronization for"," Web Distributed Authoring and Versioning (WebDAV)\", RFC"," 6578, March 2012.",""," [RFC6638] Daboo, C. and B. Desruisseaux, \"Scheduling Extensions to"," CalDAV\", RFC 6638, June 2012.","","Appendix A. Acknowledgments",""," This specification is the result of discussions between the Apple"," calendar server and client teams.","","Appendix B. Change History",""," Changes in -03:",""," 1. Added deprecation warning.",""," 2. Updated references.",""," Changes in -02:",""," 1. Updated to RFC4791 reference.",""," 2. Added text indicating that ctag applies to schedule Inbox and"," Outbox as well.",""," Changes in -01:",""," 1. Relaxed requirement so that any type of change to a child"," resource can trigger a CTag change (similar behavior to ETag).","","Author's Address",""," Cyrus Daboo"," Apple Inc."," 1 Infinite Loop"," Cupertino, CA 95014"," USA",""," Email: cyrus@daboo.name"," URI: http://www.apple.com/","","","","","","Daboo Expires November 28, 2015 [Page 5]"],"stylingDirectives":[[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[]],"colorizedLines":null,"csv":null,"csvError":null,"dependabotInfo":{"showConfigurationBanner":false,"configFilePath":null,"networkDependabotPath":"/apple/ccs-calendarserver/network/updates","dismissConfigurationNoticePath":"/settings/dismiss-notice/dependabot_configuration_notice","configurationNoticeDismissed":null},"displayName":"caldav-ctag.txt","displayUrl":"https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt?raw=true","headerInfo":{"blobSize":"10.3 KB","deleteTooltip":"You must be signed in to make or propose changes","editTooltip":"You must be signed in to make or propose changes","ghDesktopPath":"https://desktop.github.com","isGitLfs":false,"onBranch":true,"shortPath":"36c92e9","siteNavLoginPath":"/login?return_to=https%3A%2F%2Fgithub.com%2Fapple%2Fccs-calendarserver%2Fblob%2Fmaster%2Fdoc%2FExtensions%2Fcaldav-ctag.txt","isCSV":false,"isRichtext":false,"toc":null,"lineInfo":{"truncatedLoc":"280","truncatedSloc":"185"},"mode":"file"},"image":false,"isCodeownersFile":null,"isPlain":false,"isValidLegacyIssueTemplate":false,"issueTemplate":null,"discussionTemplate":null,"language":"Text","languageID":372,"large":false,"planSupportInfo":{"repoIsFork":null,"repoOwnedByCurrentUser":null,"requestFullPath":"/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt","showFreeOrgGatedFeatureMessage":null,"showPlanSupportBanner":null,"upgradeDataAttributes":null,"upgradePath":null},"publishBannersInfo":{"dismissActionNoticePath":"/settings/dismiss-notice/publish_action_from_dockerfile","releasePath":"/apple/ccs-calendarserver/releases/new?marketplace=true","showPublishActionBanner":false},"rawBlobUrl":"https://github.com/apple/ccs-calendarserver/raw/master/doc/Extensions/caldav-ctag.txt","renderImageOrRaw":false,"richText":null,"renderedFileInfo":null,"shortPath":null,"symbolsEnabled":true,"tabSize":8,"topBannersInfo":{"overridingGlobalFundingFile":false,"globalPreferredFundingPath":null,"showInvalidCitationWarning":false,"citationHelpUrl":"https://docs.github.com/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files","actionsOnboardingTip":null},"truncated":false,"viewable":true,"workflowRedirectUrl":null,"symbols":{"timed_out":false,"not_analyzed":true,"symbols":[]}},"copilotInfo":null,"copilotAccessAllowed":false,"csrf_tokens":{"/apple/ccs-calendarserver/branches":{"post":"GtbUCC-yKtajPxhXPNX6F1vtQGHfB5DWH4Bj5xZ-Jih0j3tYO6fOI-NJGFl-gyJ-DTc1kOXOAMcb28BPFnQSNw"},"/repos/preferences":{"post":"5izyV4KEtQQa7pGSFVsBfIvwJ4-26Y6Y3WcqnXYoB4_aKM8naO1H26VIUdrq6zCeAnWObC7zFpdiwWFIqDrnlg"}}},"title":"ccs-calendarserver/doc/Extensions/caldav-ctag.txt at master ยท apple/ccs-calendarserver"}