diff options
Diffstat (limited to 'vendor/sabre/dav/docs/rfc4791.txt')
| -rw-r--r-- | vendor/sabre/dav/docs/rfc4791.txt | 5995 |
1 files changed, 0 insertions, 5995 deletions
diff --git a/vendor/sabre/dav/docs/rfc4791.txt b/vendor/sabre/dav/docs/rfc4791.txt deleted file mode 100644 index 7a30bb214..000000000 --- a/vendor/sabre/dav/docs/rfc4791.txt +++ /dev/null @@ -1,5995 +0,0 @@ - - - - - - -Network Working Group C. Daboo -Request for Comments: 4791 Apple -Category: Standards Track B. Desruisseaux - Oracle - L. Dusseault - CommerceNet - March 2007 - - - Calendaring Extensions to WebDAV (CalDAV) - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The IETF Trust (2007). - -Abstract - - This document defines extensions to the Web Distributed Authoring and - Versioning (WebDAV) protocol to specify a standard way of accessing, - managing, and sharing calendaring and scheduling information based on - the iCalendar format. This document defines the "calendar-access" - feature of CalDAV. - - - - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 1] - -RFC 4791 CalDAV March 2007 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 - 1.2. XML Namespaces and Processing . . . . . . . . . . . . . . 5 - 1.3. Method Preconditions and Postconditions . . . . . . . . . 6 - 2. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6 - 3. Calendaring Data Model . . . . . . . . . . . . . . . . . . . . 7 - 3.1. Calendar Server . . . . . . . . . . . . . . . . . . . . . 7 - 3.2. Recurrence and the Data Model . . . . . . . . . . . . . . 8 - 4. Calendar Resources . . . . . . . . . . . . . . . . . . . . . . 9 - 4.1. Calendar Object Resources . . . . . . . . . . . . . . . . 9 - 4.2. Calendar Collection . . . . . . . . . . . . . . . . . . . 10 - 5. Calendar Access Feature . . . . . . . . . . . . . . . . . . . 11 - 5.1. Calendar Access Support . . . . . . . . . . . . . . . . . 11 - 5.1.1. Example: Using OPTIONS for the Discovery of - Calendar Access Support . . . . . . . . . . . . . . . 12 - 5.2. Calendar Collection Properties . . . . . . . . . . . . . . 12 - 5.2.1. CALDAV:calendar-description Property . . . . . . . . . 12 - 5.2.2. CALDAV:calendar-timezone Property . . . . . . . . . . 13 - 5.2.3. CALDAV:supported-calendar-component-set Property . . . 14 - 5.2.4. CALDAV:supported-calendar-data Property . . . . . . . 15 - 5.2.5. CALDAV:max-resource-size Property . . . . . . . . . . 16 - 5.2.6. CALDAV:min-date-time Property . . . . . . . . . . . . 17 - 5.2.7. CALDAV:max-date-time Property . . . . . . . . . . . . 18 - 5.2.8. CALDAV:max-instances Property . . . . . . . . . . . . 19 - 5.2.9. CALDAV:max-attendees-per-instance Property . . . . . . 19 - 5.2.10. Additional Precondition for PROPPATCH . . . . . . . . 20 - 5.3. Creating Resources . . . . . . . . . . . . . . . . . . . . 20 - 5.3.1. MKCALENDAR Method . . . . . . . . . . . . . . . . . . 20 - 5.3.1.1. Status Codes . . . . . . . . . . . . . . . . . . . 22 - 5.3.1.2. Example: Successful MKCALENDAR Request . . . . . . 23 - 5.3.2. Creating Calendar Object Resources . . . . . . . . . . 25 - 5.3.2.1. Additional Preconditions for PUT, COPY, and - MOVE . . . . . . . . . . . . . . . . . . . . . . . 26 - 5.3.3. Non-Standard Components, Properties, and Parameters . 28 - 5.3.4. Calendar Object Resource Entity Tag . . . . . . . . . 28 - 6. Calendaring Access Control . . . . . . . . . . . . . . . . . . 29 - 6.1. Calendaring Privilege . . . . . . . . . . . . . . . . . . 29 - 6.1.1. CALDAV:read-free-busy Privilege . . . . . . . . . . . 29 - 6.2. Additional Principal Property . . . . . . . . . . . . . . 30 - 6.2.1. CALDAV:calendar-home-set Property . . . . . . . . . . 30 - 7. Calendaring Reports . . . . . . . . . . . . . . . . . . . . . 31 - 7.1. REPORT Method . . . . . . . . . . . . . . . . . . . . . . 31 - 7.2. Ordinary Collections . . . . . . . . . . . . . . . . . . . 31 - 7.3. Date and Floating Time . . . . . . . . . . . . . . . . . . 32 - 7.4. Time Range Filtering . . . . . . . . . . . . . . . . . . . 32 - 7.5. Searching Text: Collations . . . . . . . . . . . . . . . . 33 - - - -Daboo, et al. Standards Track [Page 2] - -RFC 4791 CalDAV March 2007 - - - 7.5.1. CALDAV:supported-collation-set Property . . . . . . . 34 - 7.6. Partial Retrieval . . . . . . . . . . . . . . . . . . . . 34 - 7.7. Non-Standard Components, Properties, and Parameters . . . 35 - 7.8. CALDAV:calendar-query REPORT . . . . . . . . . . . . . . . 36 - 7.8.1. Example: Partial Retrieval of Events by Time Range . . 38 - 7.8.2. Example: Partial Retrieval of Recurring Events . . . . 42 - 7.8.3. Example: Expanded Retrieval of Recurring Events . . . 45 - 7.8.4. Example: Partial Retrieval of Stored Free Busy - Components . . . . . . . . . . . . . . . . . . . . . . 48 - 7.8.5. Example: Retrieval of To-Dos by Alarm Time Range . . . 50 - 7.8.6. Example: Retrieval of Event by UID . . . . . . . . . . 51 - 7.8.7. Example: Retrieval of Events by PARTSTAT . . . . . . . 53 - 7.8.8. Example: Retrieval of Events Only . . . . . . . . . . 55 - 7.8.9. Example: Retrieval of All Pending To-Dos . . . . . . . 59 - 7.8.10. Example: Attempt to Query Unsupported Property . . . . 62 - 7.9. CALDAV:calendar-multiget REPORT . . . . . . . . . . . . . 63 - 7.9.1. Example: Successful CALDAV:calendar-multiget REPORT . 64 - 7.10. CALDAV:free-busy-query REPORT . . . . . . . . . . . . . . 66 - 7.10.1. Example: Successful CALDAV:free-busy-query REPORT . . 68 - 8. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . 69 - 8.1. Client-to-Client Interoperability . . . . . . . . . . . . 69 - 8.2. Synchronization Operations . . . . . . . . . . . . . . . . 69 - 8.2.1. Use of Reports . . . . . . . . . . . . . . . . . . . . 69 - 8.2.1.1. Restrict the Time Range . . . . . . . . . . . . . 69 - 8.2.1.2. Synchronize by Time Range . . . . . . . . . . . . 70 - 8.2.1.3. Synchronization Process . . . . . . . . . . . . . 70 - 8.2.2. Restrict the Properties Returned . . . . . . . . . . . 72 - 8.3. Use of Locking . . . . . . . . . . . . . . . . . . . . . . 72 - 8.4. Finding Calendars . . . . . . . . . . . . . . . . . . . . 72 - 8.5. Storing and Using Attachments . . . . . . . . . . . . . . 74 - 8.5.1. Inline Attachments . . . . . . . . . . . . . . . . . . 74 - 8.5.2. External Attachments . . . . . . . . . . . . . . . . . 75 - 8.6. Storing and Using Alarms . . . . . . . . . . . . . . . . . 76 - 9. XML Element Definitions . . . . . . . . . . . . . . . . . . . 77 - 9.1. CALDAV:calendar XML Element . . . . . . . . . . . . . . . 77 - 9.2. CALDAV:mkcalendar XML Element . . . . . . . . . . . . . . 77 - 9.3. CALDAV:mkcalendar-response XML Element . . . . . . . . . . 78 - 9.4. CALDAV:supported-collation XML Element . . . . . . . . . . 78 - 9.5. CALDAV:calendar-query XML Element . . . . . . . . . . . . 78 - 9.6. CALDAV:calendar-data XML Element . . . . . . . . . . . . . 79 - 9.6.1. CALDAV:comp XML Element . . . . . . . . . . . . . . . 80 - 9.6.2. CALDAV:allcomp XML Element . . . . . . . . . . . . . . 81 - 9.6.3. CALDAV:allprop XML Element . . . . . . . . . . . . . . 81 - 9.6.4. CALDAV:prop XML Element . . . . . . . . . . . . . . . 82 - 9.6.5. CALDAV:expand XML Element . . . . . . . . . . . . . . 82 - 9.6.6. CALDAV:limit-recurrence-set XML Element . . . . . . . 83 - 9.6.7. CALDAV:limit-freebusy-set XML Element . . . . . . . . 84 - 9.7. CALDAV:filter XML Element . . . . . . . . . . . . . . . . 85 - - - -Daboo, et al. Standards Track [Page 3] - -RFC 4791 CalDAV March 2007 - - - 9.7.1. CALDAV:comp-filter XML Element . . . . . . . . . . . . 85 - 9.7.2. CALDAV:prop-filter XML Element . . . . . . . . . . . . 86 - 9.7.3. CALDAV:param-filter XML Element . . . . . . . . . . . 87 - 9.7.4. CALDAV:is-not-defined XML Element . . . . . . . . . . 88 - 9.7.5. CALDAV:text-match XML Element . . . . . . . . . . . . 88 - 9.8. CALDAV:timezone XML Element . . . . . . . . . . . . . . . 89 - 9.9. CALDAV:time-range XML Element . . . . . . . . . . . . . . 90 - 9.10. CALDAV:calendar-multiget XML Element . . . . . . . . . . . 94 - 9.11. CALDAV:free-busy-query XML Element . . . . . . . . . . . . 95 - 10. Internationalization Considerations . . . . . . . . . . . . . 95 - 11. Security Considerations . . . . . . . . . . . . . . . . . . . 95 - 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 96 - 12.1. Namespace Registration . . . . . . . . . . . . . . . . . . 96 - 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 96 - 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 97 - 14.1. Normative References . . . . . . . . . . . . . . . . . . . 97 - 14.2. Informative References . . . . . . . . . . . . . . . . . . 98 - Appendix A. CalDAV Method Privilege Table (Normative) . . . . . . 99 - Appendix B. Calendar Collections Used in the Examples . . . . . . 99 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 4] - -RFC 4791 CalDAV March 2007 - - -1. Introduction - - The concept of using HTTP [RFC2616] and WebDAV [RFC2518] as a basis - for a calendar access protocol is by no means a new concept: it was - discussed in the IETF CALSCH working group as early as 1997 or 1998. - Several companies have implemented calendar access protocols using - HTTP to upload and download iCalendar [RFC2445] objects, and using - WebDAV to get listings of resources. However, those implementations - do not interoperate because there are many small and big decisions to - be made in how to model calendaring data as WebDAV resources, as well - as how to implement required features that aren't already part of - WebDAV. This document proposes a way to model calendar data in - WebDAV, with additional features to make an interoperable calendar - access protocol. - -1.1. Notational Conventions - - 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]. - - The term "protected" is used in the Conformance field of property - definitions as defined in Section 1.4.2 of [RFC3253]. - - 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. - -1.2. XML Namespaces and Processing - - Definitions of XML elements in this document use XML element type - declarations (as found in XML Document Type Declarations), described - in Section 3.2 of [W3C.REC-xml-20060816]. - - The namespace "urn:ietf:params:xml:ns:caldav" is reserved for the XML - elements defined in this specification, its revisions, and related - CalDAV specifications. XML elements defined by individual - implementations MUST NOT use the "urn:ietf:params:xml:ns:caldav" - namespace, and instead should use a namespace that they control. - - The XML declarations used in this document do not include namespace - information. Thus, implementers must not use these declarations as - the only way to create valid CalDAV properties or to validate CalDAV - XML element types. Some of the declarations refer to XML elements - defined by WebDAV [RFC2518], which use the "DAV:" namespace. - Wherever such XML elements appear, they are explicitly prefixed with - "DAV:" to avoid confusion. - - - -Daboo, et al. Standards Track [Page 5] - -RFC 4791 CalDAV March 2007 - - - Also note that some CalDAV XML element names are identical to WebDAV - XML element names, though their namespace differs. Care must be - taken not to confuse the two sets of names. - - Processing of XML by CalDAV clients and servers MUST follow the rules - described in [RFC2518]; in particular, Section 14, and Appendix 3 of - that specification. - -1.3. Method Preconditions and Postconditions - - A "precondition" of a method describes the state of the server that - must be true for that method to be performed. A "postcondition" of a - method describes the state of the server that must be true after that - method has been completed. If a method precondition or postcondition - for a request is not satisfied, the response status of the request - MUST either be 403 (Forbidden), if the request should not be repeated - because it will always fail, or 409 (Conflict), if it is expected - that the user might be able to resolve the conflict and resubmit the - request. - - In order to allow better client handling of 403 and 409 responses, a - distinct XML element type is associated with each method precondition - and postcondition of a request. When a particular precondition is - not satisfied or a particular postcondition cannot be achieved, the - appropriate XML element MUST be returned as the child of a top-level - DAV:error element in the response body, unless otherwise negotiated - by the request. - -2. Requirements Overview - - This section lists what functionality is required of a CalDAV server. - To advertise support for CalDAV, a server: - - o MUST support iCalendar [RFC2445] as a media type for the calendar - object resource format; - - o MUST support WebDAV Class 1 [RFC2518] (note that [rfc2518bis] - describes clarifications to [RFC2518] that aid interoperability); - - o MUST support WebDAV ACL [RFC3744] with the additional privilege - defined in Section 6.1 of this document; - - o MUST support transport over TLS [RFC2246] as defined in [RFC2818] - (note that [RFC2246] has been obsoleted by [RFC4346]); - - o MUST support ETags [RFC2616] with additional requirements - specified in Section 5.3.4 of this document; - - - - -Daboo, et al. Standards Track [Page 6] - -RFC 4791 CalDAV March 2007 - - - o MUST support all calendaring reports defined in Section 7 of this - document; and - - o MUST advertise support on all calendar collections and calendar - object resources for the calendaring reports in the DAV:supported- - report-set property, as defined in Versioning Extensions to WebDAV - [RFC3253]. - - In addition, a server: - - o SHOULD support the MKCALENDAR method defined in Section 5.3.1 of - this document. - -3. Calendaring Data Model - - One of the features that has made WebDAV a successful protocol is its - firm data model. This makes it a useful framework for other - applications such as calendaring. This specification follows the - same pattern by developing all features based on a well-described - data model. - - As a brief overview, a CalDAV calendar is modeled as a WebDAV - collection with a defined structure; each calendar collection - contains a number of resources representing calendar objects as its - direct child resource. Each resource representing a calendar object - (event, to-do, journal entry, or other calendar components) is called - a "calendar object resource". Each calendar object resource and each - calendar collection can be individually locked and have individual - WebDAV properties. Requirements derived from this model are provided - in Section 4.1 and Section 4.2. - -3.1. Calendar Server - - A CalDAV server is a calendaring-aware engine combined with a WebDAV - repository. A WebDAV repository is a set of WebDAV collections, - containing other WebDAV resources, within a unified URL namespace. - For example, the repository "http://www.example.com/webdav/" may - contain WebDAV collections and resources, all of which have URLs - beginning with "http://www.example.com/webdav/". Note that the root - URL, "http://www.example.com/", may not itself be a WebDAV repository - (for example, if the WebDAV support is implemented through a servlet - or other Web server extension). - - A WebDAV repository MAY include calendar data in some parts of its - URL namespace, and non-calendaring data in other parts. - - A WebDAV repository can advertise itself as a CalDAV server if it - supports the functionality defined in this specification at any point - - - -Daboo, et al. Standards Track [Page 7] - -RFC 4791 CalDAV March 2007 - - - within the root of the repository. That might mean that calendaring - data is spread throughout the repository and mixed with non-calendar - data in nearby collections (e.g., calendar data may be found in - /home/lisa/calendars/ as well as in /home/bernard/calendars/, and - non-calendar data in /home/lisa/contacts/). Or, it might mean that - calendar data can be found only in certain sections of the repository - (e.g., /calendar/). Calendaring features are only required in the - repository sections that are or contain calendar object resources. - Therefore, a repository confining calendar data to the /calendar/ - collection would only need to support the CalDAV required features - within that collection. - - The CalDAV server or repository is the canonical location for - calendar data and state information. Clients may submit requests to - change data or download data. Clients may store calendar objects - offline and attempt to synchronize at a later time. However, clients - MUST be prepared for calendar data on the server to change between - the time of last synchronization and when attempting an update, as - calendar collections may be shared and accessible via multiple - clients. Entity tags and other features make this possible. - -3.2. Recurrence and the Data Model - - Recurrence is an important part of the data model because it governs - how many resources are expected to exist. This specification models - a recurring calendar component and its recurrence exceptions as a - single resource. In this model, recurrence rules, recurrence dates, - exception rules, and exception dates are all part of the data in a - single calendar object resource. This model avoids problems of - limiting how many recurrence instances to store in the repository, - how to keep recurrence instances in sync with the recurring calendar - component, and how to link recurrence exceptions with the recurring - calendar component. It also results in less data to synchronize - between client and server, and makes it easier to make changes to all - recurrence instances or to a recurrence rule. It makes it easier to - create a recurring calendar component and to delete all recurrence - instances. - - Clients are not forced to retrieve information about all recurrence - instances of a recurring component. The CALDAV:calendar-query and - CALDAV:calendar-multiget reports defined in this document allow - clients to retrieve only recurrence instances that overlap a given - time range. - - - - - - - - -Daboo, et al. Standards Track [Page 8] - -RFC 4791 CalDAV March 2007 - - -4. Calendar Resources - -4.1. Calendar Object Resources - - Calendar object resources contained in calendar collections MUST NOT - contain more than one type of calendar component (e.g., VEVENT, - VTODO, VJOURNAL, VFREEBUSY, etc.) with the exception of VTIMEZONE - components, which MUST be specified for each unique TZID parameter - value specified in the iCalendar object. For instance, a calendar - object resource can contain one VEVENT component and one VTIMEZONE - component, but it cannot contain one VEVENT component and one VTODO - component. Instead, the VEVENT and VTODO components would have to be - stored in separate calendar object resources in the same collection. - - Calendar object resources contained in calendar collections MUST NOT - specify the iCalendar METHOD property. - - The UID property value of the calendar components contained in a - calendar object resource MUST be unique in the scope of the calendar - collection in which they are stored. - - Calendar components in a calendar collection that have different UID - property values MUST be stored in separate calendar object resources. - - Calendar components with the same UID property value, in a given - calendar collection, MUST be contained in the same calendar object - resource. This ensures that all components in a recurrence "set" are - contained in the same calendar object resource. It is possible for a - calendar object resource to just contain components that represent - "overridden" instances (ones that modify the behavior of a regular - instance, and thus include a RECURRENCE-ID property) without also - including the "master" recurring component (the one that defines the - recurrence "set" and does not contain any RECURRENCE-ID property). - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 9] - -RFC 4791 CalDAV March 2007 - - - For example, given the following iCalendar object: - - BEGIN:VCALENDAR - PRODID:-//Example Corp.//CalDAV Client//EN - VERSION:2.0 - BEGIN:VEVENT - UID:1@example.com - SUMMARY:One-off Meeting - DTSTAMP:20041210T183904Z - DTSTART:20041207T120000Z - DTEND:20041207T130000Z - END:VEVENT - BEGIN:VEVENT - UID:2@example.com - SUMMARY:Weekly Meeting - DTSTAMP:20041210T183838Z - DTSTART:20041206T120000Z - DTEND:20041206T130000Z - RRULE:FREQ=WEEKLY - END:VEVENT - BEGIN:VEVENT - UID:2@example.com - SUMMARY:Weekly Meeting - RECURRENCE-ID:20041213T120000Z - DTSTAMP:20041210T183838Z - DTSTART:20041213T130000Z - DTEND:20041213T140000Z - END:VEVENT - END:VCALENDAR - - The VEVENT component with the UID value "1@example.com" would be - stored in its own calendar object resource. The two VEVENT - components with the UID value "2@example.com", which represent a - recurring event where one recurrence instance has been overridden, - would be stored in the same calendar object resource. - -4.2. Calendar Collection - - A calendar collection contains calendar object resources that - represent calendar components within a calendar. A calendar - collection is manifested to clients as a WebDAV resource collection - identified by a URL. A calendar collection MUST report the DAV: - collection and CALDAV:calendar XML elements in the value of the DAV: - resourcetype property. The element type declaration for CALDAV: - calendar is: - - <!ELEMENT calendar EMPTY> - - - - -Daboo, et al. Standards Track [Page 10] - -RFC 4791 CalDAV March 2007 - - - A calendar collection can be created through provisioning (i.e., - automatically created when a user's account is provisioned), or it - can be created with the MKCALENDAR method (see Section 5.3.1). This - method can be useful for a user to create additional calendars (e.g., - soccer schedule) or for users to share a calendar (e.g., team events - or conference rooms). However, note that this document doesn't - define the purpose of extra calendar collections. Users must rely on - non-standard cues to find out what a calendar collection is for, or - use the CALDAV:calendar-description property defined in Section 5.2.1 - to provide such a cue. - - The following restrictions are applied to the resources within a - calendar collection: - - a. Calendar collections MUST only contain calendar object resources - and collections that are not calendar collections, i.e., the only - "top-level" non-collection resources allowed in a calendar - collection are calendar object resources. This ensures that - calendar clients do not have to deal with non-calendar data in a - calendar collection, though they do have to distinguish between - calendar object resources and collections when using standard - WebDAV techniques to examine the contents of a collection. - - b. Collections contained in calendar collections MUST NOT contain - calendar collections at any depth, i.e., "nesting" of calendar - collections within other calendar collections at any depth is not - allowed. This specification does not define how collections - contained in a calendar collection are used or how they relate to - any calendar object resources contained in the calendar - collection. - - Multiple calendar collections MAY be children of the same collection. - -5. Calendar Access Feature - -5.1. Calendar Access Support - - A server supporting the features described in this document MUST - include "calendar-access" as a field in the DAV response header from - an OPTIONS request on any resource that supports any calendar - properties, reports, method, or privilege. A value of "calendar- - access" in the DAV response header MUST indicate that the server - supports all MUST level requirements specified in this document. - - - - - - - - -Daboo, et al. Standards Track [Page 11] - -RFC 4791 CalDAV March 2007 - - -5.1.1. Example: Using OPTIONS for the Discovery of Calendar Access - Support - - >> Request << - - OPTIONS /home/bernard/calendars/ HTTP/1.1 - Host: cal.example.com - - >> Response << - - HTTP/1.1 200 OK - Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE - Allow: PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL - DAV: 1, 2, access-control, calendar-access - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Length: 0 - - In this example, the OPTIONS method returns the value "calendar- - access" in the DAV response header to indicate that the collection - "/home/bernard/calendars/" supports the properties, reports, method, - or privilege defined in this specification. - -5.2. Calendar Collection Properties - - This section defines properties for calendar collections. - -5.2.1. CALDAV:calendar-description Property - - Name: calendar-description - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Provides a human-readable description of the calendar - collection. - - Conformance: This property MAY be defined on any calendar - collection. If defined, it MAY be protected and SHOULD NOT be - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). An xml:lang attribute indicating the human - language of the description SHOULD be set for this property by - clients or through server provisioning. Servers MUST return any - xml:lang attribute if set for the property. - - Description: If present, the property contains a description of the - calendar collection that is suitable for presentation to a user. - If not present, the client should assume no description for the - calendar collection. - - - - -Daboo, et al. Standards Track [Page 12] - -RFC 4791 CalDAV March 2007 - - - Definition: - - <!ELEMENT calendar-description (#PCDATA)> - PCDATA value: string - - Example: - - <C:calendar-description xml:lang="fr-CA" - xmlns:C="urn:ietf:params:xml:ns:caldav" - >Calendrier de Mathilde Desruisseaux</C:calendar-description> - -5.2.2. CALDAV:calendar-timezone Property - - Name: calendar-timezone - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies a time zone on a calendar collection. - - Conformance: This property SHOULD be defined on all calendar - collections. If defined, it SHOULD NOT be returned by a PROPFIND - DAV:allprop request (as defined in Section 12.14.1 of [RFC2518]). - - Description: The CALDAV:calendar-timezone property is used to - specify the time zone the server should rely on to resolve "date" - values and "date with local time" values (i.e., floating time) to - "date with UTC time" values. The server will require this - information to determine if a calendar component scheduled with - "date" values or "date with local time" values overlaps a CALDAV: - time-range specified in a CALDAV:calendar-query REPORT. The - server will also require this information to compute the proper - FREEBUSY time period as "date with UTC time" in the VFREEBUSY - component returned in a response to a CALDAV:free-busy-query - REPORT request that takes into account calendar components - scheduled with "date" values or "date with local time" values. In - the absence of this property, the server MAY rely on the time zone - of their choice. - - Note: The iCalendar data embedded within the CALDAV:calendar- - timezone XML element MUST follow the standard XML character data - encoding rules, including use of <, >, & etc. entity - encoding or the use of a <![CDATA[ ... ]]> construct. In the - later case, the iCalendar data cannot contain the character - sequence "]]>", which is the end delimiter for the CDATA section. - - - - - - - -Daboo, et al. Standards Track [Page 13] - -RFC 4791 CalDAV March 2007 - - - Definition: - - <!ELEMENT calendar-timezone (#PCDATA)> - PCDATA value: an iCalendar object with exactly one VTIMEZONE - component. - - Example: - - <C:calendar-timezone - xmlns:C="urn:ietf:params:xml:ns:caldav">BEGIN:VCALENDAR - PRODID:-//Example Corp.//CalDAV Client//EN - VERSION:2.0 - BEGIN:VTIMEZONE - TZID:US-Eastern - LAST-MODIFIED:19870101T000000Z - BEGIN:STANDARD - DTSTART:19671029T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - TZNAME:Eastern Standard Time (US & Canada) - END:STANDARD - BEGIN:DAYLIGHT - DTSTART:19870405T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - TZNAME:Eastern Daylight Time (US & Canada) - END:DAYLIGHT - END:VTIMEZONE - END:VCALENDAR - </C:calendar-timezone> - -5.2.3. CALDAV:supported-calendar-component-set Property - - Name: supported-calendar-component-set - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies the calendar component types (e.g., VEVENT, - VTODO, etc.) that calendar object resources can contain in the - calendar collection. - - Conformance: This property MAY be defined on any calendar - collection. If defined, it MUST be protected and SHOULD NOT be - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). - - - - -Daboo, et al. Standards Track [Page 14] - -RFC 4791 CalDAV March 2007 - - - Description: The CALDAV:supported-calendar-component-set property is - used to specify restrictions on the calendar component types that - calendar object resources may contain in a calendar collection. - Any attempt by the client to store calendar object resources with - component types not listed in this property, if it exists, MUST - result in an error, with the CALDAV:supported-calendar-component - precondition (Section 5.3.2.1) being violated. Since this - property is protected, it cannot be changed by clients using a - PROPPATCH request. However, clients can initialize the value of - this property when creating a new calendar collection with - MKCALENDAR. The empty-element tag <C:comp name="VTIMEZONE"/> MUST - only be specified if support for calendar object resources that - only contain VTIMEZONE components is provided or desired. Support - for VTIMEZONE components in calendar object resources that contain - VEVENT or VTODO components is always assumed. In the absence of - this property, the server MUST accept all component types, and the - client can assume that all component types are accepted. - - Definition: - - <!ELEMENT supported-calendar-component-set (comp+)> - - Example: - - <C:supported-calendar-component-set - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <C:comp name="VEVENT"/> - <C:comp name="VTODO"/> - </C:supported-calendar-component-set> - -5.2.4. CALDAV:supported-calendar-data Property - - Name: supported-calendar-data - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies what media types are allowed for calendar object - resources in a calendar collection. - - Conformance: This property MAY be defined on any calendar - collection. If defined, it MUST be protected and SHOULD NOT be - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). - - Description: The CALDAV:supported-calendar-data property is used to - specify the media type supported for the calendar object resources - contained in a given calendar collection (e.g., iCalendar version - 2.0). Any attempt by the client to store calendar object - - - -Daboo, et al. Standards Track [Page 15] - -RFC 4791 CalDAV March 2007 - - - resources with a media type not listed in this property MUST - result in an error, with the CALDAV:supported-calendar-data - precondition (Section 5.3.2.1) being violated. In the absence of - this property, the server MUST only accept data with the media - type "text/calendar" and iCalendar version 2.0, and clients can - assume that the server will only accept this data. - - Definition: - - <!ELEMENT supported-calendar-data (calendar-data+)> - - Example: - - <C:supported-calendar-data - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <C:calendar-data content-type="text/calendar" version="2.0"/> - </C:supported-calendar-data> - -5.2.5. CALDAV:max-resource-size Property - - Name: max-resource-size - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Provides a numeric value indicating the maximum size of a - resource in octets that the server is willing to accept when a - calendar object resource is stored in a calendar collection. - - Conformance: This property MAY be defined on any calendar - collection. If defined, it MUST be protected and SHOULD NOT be - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). - - Description: The CALDAV:max-resource-size is used to specify a - numeric value that represents the maximum size in octets that the - server is willing to accept when a calendar object resource is - stored in a calendar collection. Any attempt to store a calendar - object resource exceeding this size MUST result in an error, with - the CALDAV:max-resource-size precondition (Section 5.3.2.1) being - violated. In the absence of this property, the client can assume - that the server will allow storing a resource of any reasonable - size. - - Definition: - - <!ELEMENT max-resource-size (#PCDATA)> - PCDATA value: a numeric value (positive integer) - - - - -Daboo, et al. Standards Track [Page 16] - -RFC 4791 CalDAV March 2007 - - - Example: - - <C:max-resource-size xmlns:C="urn:ietf:params:xml:ns:caldav" - >102400</C:max-resource-size> - -5.2.6. CALDAV:min-date-time Property - - Name: min-date-time - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Provides a DATE-TIME value indicating the earliest date and - time (in UTC) that the server is willing to accept for any DATE or - DATE-TIME value in a calendar object resource stored in a calendar - collection. - - Conformance: This property MAY be defined on any calendar - collection. If defined, it MUST be protected and SHOULD NOT be - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). - - Description: The CALDAV:min-date-time is used to specify an - iCalendar DATE-TIME value in UTC that indicates the earliest - inclusive date that the server is willing to accept for any - explicit DATE or DATE-TIME value in a calendar object resource - stored in a calendar collection. Any attempt to store a calendar - object resource using a DATE or DATE-TIME value earlier than this - value MUST result in an error, with the CALDAV:min-date-time - precondition (Section 5.3.2.1) being violated. Note that servers - MUST accept recurring components that specify instances beyond - this limit, provided none of those instances have been overridden. - In that case, the server MAY simply ignore those instances outside - of the acceptable range when processing reports on the calendar - object resource. In the absence of this property, the client can - assume any valid iCalendar date may be used at least up to the - CALDAV:max-date-time value, if that is defined. - - Definition: - - <!ELEMENT min-date-time (#PCDATA)> - PCDATA value: an iCalendar format DATE-TIME value in UTC - - Example: - - <C:min-date-time xmlns:C="urn:ietf:params:xml:ns:caldav" - >19000101T000000Z</C:min-date-time> - - - - - -Daboo, et al. Standards Track [Page 17] - -RFC 4791 CalDAV March 2007 - - -5.2.7. CALDAV:max-date-time Property - - Name: max-date-time - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Provides a DATE-TIME value indicating the latest date and - time (in UTC) that the server is willing to accept for any DATE or - DATE-TIME value in a calendar object resource stored in a calendar - collection. - - Conformance: This property MAY be defined on any calendar - collection. If defined, it MUST be protected and SHOULD NOT be - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). - - Description: The CALDAV:max-date-time is used to specify an - iCalendar DATE-TIME value in UTC that indicates the inclusive - latest date that the server is willing to accept for any date or - time value in a calendar object resource stored in a calendar - collection. Any attempt to store a calendar object resource using - a DATE or DATE-TIME value later than this value MUST result in an - error, with the CALDAV:max-date-time precondition - (Section 5.3.2.1) being violated. Note that servers MUST accept - recurring components that specify instances beyond this limit, - provided none of those instances have been overridden. In that - case, the server MAY simply ignore those instances outside of the - acceptable range when processing reports on the calendar object - resource. In the absence of this property, the client can assume - any valid iCalendar date may be used at least down to the CALDAV: - min-date-time value, if that is defined. - - Definition: - - <!ELEMENT max-date-time (#PCDATA)> - PCDATA value: an iCalendar format DATE-TIME value in UTC - - Example: - - <C:max-date-time xmlns:C="urn:ietf:params:xml:ns:caldav" - >20491231T235959Z</C:max-date-time> - - - - - - - - - - -Daboo, et al. Standards Track [Page 18] - -RFC 4791 CalDAV March 2007 - - -5.2.8. CALDAV:max-instances Property - - Name: max-instances - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Provides a numeric value indicating the maximum number of - recurrence instances that a calendar object resource stored in a - calendar collection can generate. - - Conformance: This property MAY be defined on any calendar - collection. If defined, it MUST be protected and SHOULD NOT be - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). - - Description: The CALDAV:max-instances is used to specify a numeric - value that indicates the maximum number of recurrence instances - that a calendar object resource stored in a calendar collection - can generate. Any attempt to store a calendar object resource - with a recurrence pattern that generates more instances than this - value MUST result in an error, with the CALDAV:max-instances - precondition (Section 5.3.2.1) being violated. In the absence of - this property, the client can assume that the server has no limits - on the number of recurrence instances it can handle or expand. - - Definition: - - <!ELEMENT max-instances (#PCDATA)> - PCDATA value: a numeric value (integer greater than zero) - - Example: - - <C:max-instances xmlns:C="urn:ietf:params:xml:ns:caldav" - >100</C:max-instances> - -5.2.9. CALDAV:max-attendees-per-instance Property - - Name: max-attendees-per-instance - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Provides a numeric value indicating the maximum number of - ATTENDEE properties in any instance of a calendar object resource - stored in a calendar collection. - - Conformance: This property MAY be defined on any calendar - collection. If defined, it MUST be protected and SHOULD NOT be - - - - -Daboo, et al. Standards Track [Page 19] - -RFC 4791 CalDAV March 2007 - - - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). - - Description: The CALDAV:max-attendees-per-instance is used to - specify a numeric value that indicates the maximum number of - iCalendar ATTENDEE properties on any one instance of a calendar - object resource stored in a calendar collection. Any attempt to - store a calendar object resource with more ATTENDEE properties per - instance than this value MUST result in an error, with the CALDAV: - max-attendees-per-instance precondition (Section 5.3.2.1) being - violated. In the absence of this property, the client can assume - that the server can handle any number of ATTENDEE properties in a - calendar component. - - Definition: - - <!ELEMENT max-attendees-per-instance (#PCDATA)> - PCDATA value: a numeric value (integer greater than zero) - - Example: - - <C:max-attendees-per-instance - xmlns:C="urn:ietf:params:xml:ns:caldav" - >25</C:max-attendees-per-instance> - -5.2.10. Additional Precondition for PROPPATCH - - This specification requires an additional Precondition for the - PROPPATCH method. The precondition is: - - (CALDAV:valid-calendar-data): The time zone specified in CALDAV: - calendar-timezone property MUST be a valid iCalendar object - containing a single valid VTIMEZONE component. - -5.3. Creating Resources - - Calendar collections and calendar object resources may be created by - either a CalDAV client or by the CalDAV server. This specification - defines restrictions and a data model that both clients and servers - MUST adhere to when manipulating such calendar data. - -5.3.1. MKCALENDAR Method - - An HTTP request using the MKCALENDAR method creates a new calendar - collection resource. A server MAY restrict calendar collection - creation to particular collections. - - - - - -Daboo, et al. Standards Track [Page 20] - -RFC 4791 CalDAV March 2007 - - - Support for MKCALENDAR on the server is only RECOMMENDED and not - REQUIRED because some calendar stores only support one calendar per - user (or principal), and those are typically pre-created for each - account. However, servers and clients are strongly encouraged to - support MKCALENDAR whenever possible to allow users to create - multiple calendar collections to help organize their data better. - - Clients SHOULD use the DAV:displayname property for a human-readable - name of the calendar. Clients can either specify the value of the - DAV:displayname property in the request body of the MKCALENDAR - request, or alternatively issue a PROPPATCH request to change the - DAV:displayname property to the appropriate value immediately after - issuing the MKCALENDAR request. Clients SHOULD NOT set the DAV: - displayname property to be the same as any other calendar collection - at the same URI "level". When displaying calendar collections to - users, clients SHOULD check the DAV:displayname property and use that - value as the name of the calendar. In the event that the DAV: - displayname property is empty, the client MAY use the last part of - the calendar collection URI as the name; however, that path segment - may be "opaque" and not represent any meaningful human-readable text. - - If a MKCALENDAR request fails, the server state preceding the request - MUST be restored. - - Marshalling: - If a request body is included, it MUST be a CALDAV:mkcalendar XML - element. Instruction processing MUST occur in the order - instructions are received (i.e., from top to bottom). - Instructions MUST either all be executed or none executed. Thus, - if any error occurs during processing, all executed instructions - MUST be undone and a proper error result returned. Instruction - processing details can be found in the definition of the DAV:set - instruction in Section 12.13.2 of [RFC2518]. - - <!ELEMENT mkcalendar (DAV:set)> - - If a response body for a successful request is included, it MUST - be a CALDAV:mkcalendar-response XML element. - - <!ELEMENT mkcalendar-response ANY> - - The response MUST include a Cache-Control:no-cache header. - - Preconditions: - - (DAV:resource-must-be-null): A resource MUST NOT exist at the - Request-URI; - - - - -Daboo, et al. Standards Track [Page 21] - -RFC 4791 CalDAV March 2007 - - - (CALDAV:calendar-collection-location-ok): The Request-URI MUST - identify a location where a calendar collection can be created; - - (CALDAV:valid-calendar-data): The time zone specified in the - CALDAV:calendar-timezone property MUST be a valid iCalendar object - containing a single valid VTIMEZONE component; - - (DAV:needs-privilege): The DAV:bind privilege MUST be granted to - the current user on the parent collection of the Request-URI. - - Postconditions: - - (CALDAV:initialize-calendar-collection): A new calendar collection - exists at the Request-URI. The DAV:resourcetype of the calendar - collection MUST contain both DAV:collection and CALDAV:calendar - XML elements. - -5.3.1.1. Status Codes - - The following are examples of response codes one would expect to get - in a response to a MKCALENDAR request. Note that this list is by no - means exhaustive. - - 201 (Created) - The calendar collection resource was created in - its entirety; - - 207 (Multi-Status) - The calendar collection resource was not - created since one or more DAV:set instructions specified in the - request body could not be processed successfully. The following - are examples of response codes one would expect to be used in a - 207 (Multi-Status) response in this situation: - - 403 (Forbidden) - The client, for reasons the server chooses - not to specify, cannot alter one of the properties; - - 409 (Conflict) - The client has provided a value whose - semantics are not appropriate for the property. This includes - trying to set read-only properties; - - 424 (Failed Dependency) - The DAV:set instruction on the - specified resource would have succeeded if it were not for the - failure of another DAV:set instruction specified in the request - body; - - 423 (Locked) - The specified resource is locked and the client - either is not a lock owner or the lock type requires a lock - token to be submitted and the client did not submit it; and - - - - -Daboo, et al. Standards Track [Page 22] - -RFC 4791 CalDAV March 2007 - - - 507 (Insufficient Storage) - The server did not have sufficient - space to record the property; - - 403 (Forbidden) - This indicates at least one of two conditions: - 1) the server does not allow the creation of calendar collections - at the given location in its namespace, or 2) the parent - collection of the Request-URI exists but cannot accept members; - - 409 (Conflict) - A collection cannot be made at the Request-URI - until one or more intermediate collections have been created; - - 415 (Unsupported Media Type) - The server does not support the - request type of the body; and - - 507 (Insufficient Storage) - The resource does not have sufficient - space to record the state of the resource after the execution of - this method. - -5.3.1.2. Example: Successful MKCALENDAR Request - - This example creates a calendar collection called /home/lisa/ - calendars/events/ on the server cal.example.com with specific values - for the properties DAV:displayname, CALDAV:calendar-description, - CALDAV:supported-calendar-component-set, and CALDAV:calendar- - timezone. - - - - - - - - - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 23] - -RFC 4791 CalDAV March 2007 - - - >> Request << - - MKCALENDAR /home/lisa/calendars/events/ HTTP/1.1 - Host: cal.example.com - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:mkcalendar xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:set> - <D:prop> - <D:displayname>Lisa's Events</D:displayname> - <C:calendar-description xml:lang="en" - >Calendar restricted to events.</C:calendar-description> - <C:supported-calendar-component-set> - <C:comp name="VEVENT"/> - </C:supported-calendar-component-set> - <C:calendar-timezone><![CDATA[BEGIN:VCALENDAR - PRODID:-//Example Corp.//CalDAV Client//EN - VERSION:2.0 - BEGIN:VTIMEZONE - TZID:US-Eastern - LAST-MODIFIED:19870101T000000Z - BEGIN:STANDARD - DTSTART:19671029T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - TZNAME:Eastern Standard Time (US & Canada) - END:STANDARD - BEGIN:DAYLIGHT - DTSTART:19870405T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - TZNAME:Eastern Daylight Time (US & Canada) - END:DAYLIGHT - END:VTIMEZONE - END:VCALENDAR - ]]></C:calendar-timezone> - </D:prop> - </D:set> - </C:mkcalendar> - - - - - - - -Daboo, et al. Standards Track [Page 24] - -RFC 4791 CalDAV March 2007 - - - >> Response << - - HTTP/1.1 201 Created - Cache-Control: no-cache - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Length: 0 - -5.3.2. Creating Calendar Object Resources - - Clients populate calendar collections with calendar object resources. - The URL for each calendar object resource is entirely arbitrary and - does not need to bear a specific relationship to the calendar object - resource's iCalendar properties or other metadata. New calendar - object resources MUST be created with a PUT request targeted at an - unmapped URI. A PUT request targeted at a mapped URI updates an - existing calendar object resource. - - When servers create new resources, it's not hard for the server to - choose an unmapped URI. It's slightly tougher for clients, because a - client might not want to examine all resources in the collection and - might not want to lock the entire collection to ensure that a new - resource isn't created with a name collision. However, there is an - HTTP feature to mitigate this. If the client intends to create a new - non-collection resource, such as a new VEVENT, the client SHOULD use - the HTTP request header "If-None-Match: *" on the PUT request. The - Request-URI on the PUT request MUST include the target collection, - where the resource is to be created, plus the name of the resource in - the last path segment. The "If-None-Match: *" request header ensures - that the client will not inadvertently overwrite an existing resource - if the last path segment turned out to already be used. - - - - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 25] - -RFC 4791 CalDAV March 2007 - - - >> Request << - - PUT /home/lisa/calendars/events/qwue23489.ics HTTP/1.1 - If-None-Match: * - Host: cal.example.com - Content-Type: text/calendar - Content-Length: xxxx - - BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VEVENT - UID:20010712T182145Z-123401@example.com - DTSTAMP:20060712T182145Z - DTSTART:20060714T170000Z - DTEND:20060715T040000Z - SUMMARY:Bastille Day Party - END:VEVENT - END:VCALENDAR - - >> Response << - - HTTP/1.1 201 Created - Content-Length: 0 - Date: Sat, 11 Nov 2006 09:32:12 GMT - ETag: "123456789-000-111" - - The request to change an existing event is the same, but with a - specific ETag in the "If-Match" header, rather than the "If-None- - Match" header. - - As indicated in Section 3.10 of [RFC2445], the URL of calendar object - resources containing (an arbitrary set of) calendaring and scheduling - information may be suffixed by ".ics", and the URL of calendar object - resources containing free or busy time information may be suffixed by - ".ifb". - -5.3.2.1. Additional Preconditions for PUT, COPY, and MOVE - - This specification creates additional Preconditions for PUT, COPY, - and MOVE methods. These preconditions apply when a PUT operation of - a calendar object resource into a calendar collection occurs, or when - a COPY or MOVE operation of a calendar object resource into a - calendar collection occurs, or when a COPY or MOVE operation occurs - on a calendar collection. - - - - - - -Daboo, et al. Standards Track [Page 26] - -RFC 4791 CalDAV March 2007 - - - The new preconditions are: - - (CALDAV:supported-calendar-data): The resource submitted in the - PUT request, or targeted by a COPY or MOVE request, MUST be a - supported media type (i.e., iCalendar) for calendar object - resources; - - (CALDAV:valid-calendar-data): The resource submitted in the PUT - request, or targeted by a COPY or MOVE request, MUST be valid data - for the media type being specified (i.e., MUST contain valid - iCalendar data); - - (CALDAV:valid-calendar-object-resource): The resource submitted in - the PUT request, or targeted by a COPY or MOVE request, MUST obey - all restrictions specified in Section 4.1 (e.g., calendar object - resources MUST NOT contain more than one type of calendar - component, calendar object resources MUST NOT specify the - iCalendar METHOD property, etc.); - - (CALDAV:supported-calendar-component): The resource submitted in - the PUT request, or targeted by a COPY or MOVE request, MUST - contain a type of calendar component that is supported in the - targeted calendar collection; - - (CALDAV:no-uid-conflict): The resource submitted in the PUT - request, or targeted by a COPY or MOVE request, MUST NOT specify - an iCalendar UID property value already in use in the targeted - calendar collection or overwrite an existing calendar object - resource with one that has a different UID property value. - Servers SHOULD report the URL of the resource that is already - making use of the same UID property value in the DAV:href element; - - <!ELEMENT no-uid-conflict (DAV:href)> - - (CALDAV:calendar-collection-location-ok): In a COPY or MOVE - request, when the Request-URI is a calendar collection, the - Destination-URI MUST identify a location where a calendar - collection can be created; - - (CALDAV:max-resource-size): The resource submitted in the PUT - request, or targeted by a COPY or MOVE request, MUST have an octet - size less than or equal to the value of the CALDAV:max-resource- - size property value (Section 5.2.5) on the calendar collection - where the resource will be stored; - - (CALDAV:min-date-time): The resource submitted in the PUT request, - or targeted by a COPY or MOVE request, MUST have all of its - iCalendar DATE or DATE-TIME property values (for each recurring - - - -Daboo, et al. Standards Track [Page 27] - -RFC 4791 CalDAV March 2007 - - - instance) greater than or equal to the value of the CALDAV:min- - date-time property value (Section 5.2.6) on the calendar - collection where the resource will be stored; - - (CALDAV:max-date-time): The resource submitted in the PUT request, - or targeted by a COPY or MOVE request, MUST have all of its - iCalendar DATE or DATE-TIME property values (for each recurring - instance) less than the value of the CALDAV:max-date-time property - value (Section 5.2.7) on the calendar collection where the - resource will be stored; - - (CALDAV:max-instances): The resource submitted in the PUT request, - or targeted by a COPY or MOVE request, MUST generate a number of - recurring instances less than or equal to the value of the CALDAV: - max-instances property value (Section 5.2.8) on the calendar - collection where the resource will be stored; - - (CALDAV:max-attendees-per-instance): The resource submitted in the - PUT request, or targeted by a COPY or MOVE request, MUST have a - number of ATTENDEE properties on any one instance less than or - equal to the value of the CALDAV:max-attendees-per-instance - property value (Section 5.2.9) on the calendar collection where - the resource will be stored; - -5.3.3. Non-Standard Components, Properties, and Parameters - - iCalendar provides a "standard mechanism for doing non-standard - things". This extension support allows implementers to make use of - non-standard components, properties, and parameters whose names are - prefixed with the text "X-". - - Servers MUST support the use of non-standard components, properties, - and parameters in calendar object resources stored via the PUT - method. - - Servers may need to enforce rules for their own "private" components, - properties, or parameters, so servers MAY reject any attempt by the - client to change those or use values for those outside of any - restrictions the server may have. Servers SHOULD ensure that any - "private" components, properties, or parameters it uses follow the - convention of including a vendor id in the "X-" name, as described in - Section 4.2 of [RFC2445], e.g., "X-ABC-PRIVATE". - -5.3.4. Calendar Object Resource Entity Tag - - The DAV:getetag property MUST be defined and set to a strong entity - tag on all calendar object resources. - - - - -Daboo, et al. Standards Track [Page 28] - -RFC 4791 CalDAV March 2007 - - - A response to a GET request targeted at a calendar object resource - MUST contain an ETag response header field indicating the current - value of the strong entity tag of the calendar object resource. - - Servers SHOULD return a strong entity tag (ETag header) in a PUT - response when the stored calendar object resource is equivalent by - octet equality to the calendar object resource submitted in the body - of the PUT request. This allows clients to reliably use the returned - strong entity tag for data synchronization purposes. For instance, - the client can do a PROPFIND request on the stored calendar object - resource and have the DAV:getetag property returned, and compare that - value with the strong entity tag it received on the PUT response, and - know that if they are equal, then the calendar object resource on the - server has not been changed. - - In the case where the data stored by a server as a result of a PUT - request is not equivalent by octet equality to the submitted calendar - object resource, the behavior of the ETag response header is not - specified here, with the exception that a strong entity tag MUST NOT - be returned in the response. As a result, clients may need to - retrieve the modified calendar object resource (and ETag) as a basis - for further changes, rather than use the calendar object resource it - had sent with the PUT request. - -6. Calendaring Access Control - -6.1. Calendaring Privilege - - CalDAV servers MUST support and adhere to the requirements of WebDAV - ACL [RFC3744]. WebDAV ACL provides a framework for an extensible set - of privileges that can be applied to WebDAV collections and ordinary - resources. CalDAV servers MUST also support the calendaring - privilege defined in this section. - -6.1.1. CALDAV:read-free-busy Privilege - - Calendar users often wish to allow other users to see their busy time - information, without viewing the other details of the calendar - components (e.g., location, summary, attendees). This allows a - significant amount of privacy while still allowing other users to - schedule meetings at times when the user is likely to be free. - - The CALDAV:read-free-busy privilege controls which calendar - collections, regular collections, and calendar object resources are - examined when a CALDAV:free-busy-query REPORT request is processed - (see Section 7.10). This privilege can be granted on calendar - collections, regular collections, or calendar object resources. - - - - -Daboo, et al. Standards Track [Page 29] - -RFC 4791 CalDAV March 2007 - - - Servers MUST support this privilege on all calendar collections, - regular collections, and calendar object resources. - - - <!ELEMENT read-free-busy EMPTY> - - The CALDAV:read-free-busy privilege MUST be aggregated in the DAV: - read privilege. Servers MUST allow the CALDAV:read-free-busy to be - granted without the DAV:read privilege being granted. - - Clients should note that when only the CALDAV:read-free-busy - privilege has been granted on a resource, access to GET, HEAD, - OPTIONS, and PROPFIND on the resource is not implied (those - operations are governed by the DAV:read privilege). - -6.2. Additional Principal Property - - This section defines an additional property for WebDAV principal - resources, as defined in [RFC3744]. - -6.2.1. CALDAV:calendar-home-set Property - - Name: calendar-home-set - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Identifies the URL of any WebDAV collections that contain - calendar collections owned by the associated principal resource. - - Conformance: This property SHOULD be defined on a principal - resource. If defined, it MAY be protected and SHOULD NOT be - returned by a PROPFIND DAV:allprop request (as defined in Section - 12.14.1 of [RFC2518]). - - Description: The CALDAV:calendar-home-set property is meant to allow - users to easily find the calendar collections owned by the - principal. Typically, users will group all the calendar - collections that they own under a common collection. This - property specifies the URL of collections that are either calendar - collections or ordinary collections that have child or descendant - calendar collections owned by the principal. - - Definition: - - <!ELEMENT calendar-home-set (DAV:href*)> - - - - - - -Daboo, et al. Standards Track [Page 30] - -RFC 4791 CalDAV March 2007 - - - Example: - - <C:calendar-home-set xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:href>http://cal.example.com/home/bernard/calendars/</D:href> - </C:calendar-home-set> - -7. Calendaring Reports - - This section defines the reports that CalDAV servers MUST support on - calendar collections and calendar object resources. - - CalDAV servers MUST advertise support for these reports on all - calendar collections and calendar object resources with the DAV: - supported-report-set property, defined in Section 3.1.5 of [RFC3253]. - CalDAV servers MAY also advertise support for these reports on - ordinary collections. - - Some of these reports allow calendar data (from possibly multiple - resources) to be returned. - -7.1. REPORT Method - - The REPORT method (defined in Section 3.6 of [RFC3253]) provides an - extensible mechanism for obtaining information about one or more - resources. Unlike the PROPFIND method, which returns the value of - one or more named properties, the REPORT method can involve more - complex processing. REPORT is valuable in cases where the server has - access to all of the information needed to perform the complex - request (such as a query), and where it would require multiple - requests for the client to retrieve the information needed to perform - the same request. - - CalDAV servers MUST support the DAV:expand-property REPORT defined in - Section 3.8 of [RFC3253]. - -7.2. Ordinary Collections - - Servers MAY support the reports defined in this document on ordinary - collections (collections that are not calendar collections), in - addition to calendar collections or calendar object resources. In - computing responses to the reports on ordinary collections, servers - MUST only consider calendar object resources contained in calendar - collections that are targeted by the REPORT request, based on the - value of the Depth request header. - - - - - - -Daboo, et al. Standards Track [Page 31] - -RFC 4791 CalDAV March 2007 - - -7.3. Date and Floating Time - - iCalendar provides a way to specify DATE and DATE-TIME values that - are not bound to any time zone in particular, hereafter called - "floating date" and "floating time", respectively. These values are - used to represent the same day, hour, minute, and second value, - regardless of which time zone is being observed. For instance, the - DATE value "20051111", represents November 11, 2005 in no specific - time zone, while the DATE-TIME value "20051111T111100" represents - November 11, 2005, at 11:11 A.M. in no specific time zone. - - CalDAV servers may need to convert "floating date" and "floating - time" values in date with UTC time values in the processing of - calendaring REPORT requests. - - For the CALDAV:calendar-query REPORT, CalDAV servers MUST rely on the - value of the CALDAV:timezone XML element, if specified as part of the - request body, to perform the proper conversion of "floating date" and - "floating time" values to date with UTC time values. If the CALDAV: - timezone XML element is not specified in the request body, CalDAV - servers MUST rely on the value of the CALDAV:calendar-timezone - property, if defined, or else the CalDAV servers MAY rely on the time - zone of their choice. - - For the CALDAV:free-busy-query REPORT, CalDAV servers MUST rely on - the value of the CALDAV:calendar-timezone property, if defined, to - compute the proper FREEBUSY time period value as date with UTC time - for calendar components scheduled with "floating date" or "floating - time". If the CALDAV:calendar-timezone property is not defined, - CalDAV servers MAY rely on the time zone of their choice. - -7.4. Time Range Filtering - - Some of the reports defined in this section can include a time range - filter that is used to restrict the set of calendar object resources - returned to just those that overlap the specified time range. The - time range filter can be applied to a calendar component as a whole, - or to specific calendar component properties with DATE or DATE-TIME - value types. - - To determine whether a calendar object resource matches the time - range filter element, the start and end times for the targeted - component or property are determined and then compared to the - requested time range. If there is an overlap with the requested time - range, then the calendar object resource matches the filter element. - The rules defined in [RFC2445] for determining the actual start and - end times of calendar components MUST be used, and these are fully - enumerated in Section 9.9 of this document. - - - -Daboo, et al. Standards Track [Page 32] - -RFC 4791 CalDAV March 2007 - - - When such time range filtering is used, special consideration must be - given to recurring calendar components, such as VEVENT and VTODO. - The server MUST expand recurring components to determine whether any - recurrence instances overlap the specified time range. If one or - more recurrence instances overlap the time range, then the calendar - object resource matches the filter element. - -7.5. Searching Text: Collations - - Some of the reports defined in this section do text matches of - character strings provided by the client and are compared to stored - calendar data. Since iCalendar data is, by default, encoded in the - UTF-8 charset and may include characters outside the US-ASCII charset - range in some property and parameter values, there is a need to - ensure that text matching follows well-defined rules. - - To deal with this, this specification makes use of the IANA Collation - Registry defined in [RFC4790] to specify collations that may be used - to carry out the text comparison operations with a well-defined rule. - - The comparisons used in CalDAV are all "substring" matches, as per - [RFC4790], Section 4.2. Collations supported by the server MUST - support "substring" match operations. - - CalDAV servers are REQUIRED to support the "i;ascii-casemap" and - "i;octet" collations, as described in [RFC4790], and MAY support - other collations. - - Servers MUST advertise the set of collations that they support via - the CALDAV:supported-collation-set property defined on any resource - that supports reports that use collations. - - Clients MUST only use collations from the list advertised by the - server. - - In the absence of a collation explicitly specified by the client, or - if the client specifies the "default" collation identifier (as - defined in [RFC4790], Section 3.1), the server MUST default to using - "i;ascii-casemap" as the collation. - - Wildcards (as defined in [RFC4790], Section 3.2) MUST NOT be used in - the collation identifier. - - If the client chooses a collation not supported by the server, the - server MUST respond with a CALDAV:supported-collation precondition - error response. - - - - - -Daboo, et al. Standards Track [Page 33] - -RFC 4791 CalDAV March 2007 - - -7.5.1. CALDAV:supported-collation-set Property - - Name: supported-collation-set - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Identifies the set of collations supported by the server - for text matching operations. - - Conformance: This property MUST be defined on any resource that - supports a report that does text matching. If defined, it MUST be - protected and SHOULD NOT be returned by a PROPFIND DAV:allprop - request (as defined in Section 12.14.1 of [RFC2518]). - - Description: The CALDAV:supported-collation-set property contains - zero or more CALDAV:supported-collation elements, which specify - the collection identifiers of the collations supported by the - server. - - Definition: - - <!ELEMENT supported-collation-set (supported-collation*)> - - <!ELEMENT supported-collation (#PCDATA)> - - Example: - - <C:supported-collation-set - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <C:supported-collation>i;ascii-casemap</C:supported-collation> - <C:supported-collation>i;octet</C:supported-collation> - </C:supported-collation-set> - -7.6. Partial Retrieval - - Some calendaring reports defined in this document allow partial - retrieval of calendar object resources. A CalDAV client can specify - what information to return in the body of a calendaring REPORT - request. - - A CalDAV client can request particular WebDAV property values, all - WebDAV property values, or a list of the names of the resource's - WebDAV properties. A CalDAV client can also request calendar data to - be returned and specify whether all calendar components and - properties should be returned, or only particular ones. See CALDAV: - calendar-data in Section 9.6. - - - - - -Daboo, et al. Standards Track [Page 34] - -RFC 4791 CalDAV March 2007 - - - By default, the returned calendar data will include the component - that defines the recurrence set, referred to as the "master - component", as well as the components that define exceptions to the - recurrence set, referred to as the "overridden components". - - A CalDAV client that is only interested in the recurrence instances - that overlap a specified time range can request to receive only the - "master component", along with the "overridden components" that - impact the specified time range, and thus, limit the data returned by - the server (see CALDAV:limit-recurrence-set in Section 9.6.6). An - overridden component impacts a time range if its current start and - end times overlap the time range, or if the original start and end - times -- the ones that would have been used if the instance were not - overridden -- overlap the time range, or if it affects other - instances that overlap the time range. - - A CalDAV client with no support for recurrence properties (i.e., - EXDATE, EXRULE, RDATE, and RRULE) and possibly VTIMEZONE components, - or a client unwilling to perform recurrence expansion because of - limited processing capability, can request to receive only the - recurrence instances that overlap a specified time range as separate - calendar components that each define exactly one recurrence instance - (see CALDAV:expand in Section 9.6.5.) - - Finally, in the case of VFREEBUSY components, a CalDAV client can - request to receive only the FREEBUSY property values that overlap a - specified time range (see CALDAV:limit-freebusy-set in - Section 9.6.7.) - -7.7. Non-Standard Components, Properties, and Parameters - - Servers MUST support the use of non-standard component, property, or - parameter names in the CALDAV:calendar-data XML element in - calendaring REPORT requests to allow clients to request that non- - standard components, properties, and parameters be returned in the - calendar data provided in the response. - - Servers MAY support the use of non-standard component, property, or - parameter names in the CALDAV:comp-filter, CALDAV:prop-filter, and - CALDAV:param-filter XML elements specified in the CALDAV:filter XML - element of calendaring REPORT requests. - - Servers MUST fail with the CALDAV:supported-filter precondition if a - calendaring REPORT request uses a CALDAV:comp-filter, CALDAV:prop- - filter, or CALDAV:param-filter XML element that makes reference to a - non-standard component, property, or parameter name on which the - server does not support queries. - - - - -Daboo, et al. Standards Track [Page 35] - -RFC 4791 CalDAV March 2007 - - -7.8. CALDAV:calendar-query REPORT - - The CALDAV:calendar-query REPORT performs a search for all calendar - object resources that match a specified filter. The response of this - report will contain all the WebDAV properties and calendar object - resource data specified in the request. In the case of the CALDAV: - calendar-data XML element, one can explicitly specify the calendar - components and properties that should be returned in the calendar - object resource data that matches the filter. - - The format of this report is modeled on the PROPFIND method. The - request and response bodies of the CALDAV:calendar-query REPORT use - XML elements that are also used by PROPFIND. In particular, the - request can include XML elements to request WebDAV properties to be - returned. When that occurs, the response should follow the same - behavior as PROPFIND with respect to the DAV:multistatus response - elements used to return specific property results. For instance, a - request to retrieve the value of a property that does not exist is an - error and MUST be noted with a response XML element that contains a - 404 (Not Found) status value. - - Support for the CALDAV:calendar-query REPORT is REQUIRED. - - Marshalling: - - The request body MUST be a CALDAV:calendar-query XML element, as - defined in Section 9.5. - - The request MAY include a Depth header. If no Depth header is - included, Depth:0 is assumed. - - The response body for a successful request MUST be a DAV: - multistatus XML element (i.e., the response uses the same format - as the response for PROPFIND). In the case where there are no - response elements, the returned DAV:multistatus XML element is - empty. - - The response body for a successful CALDAV:calendar-query REPORT - request MUST contain a DAV:response element for each iCalendar - object that matched the search filter. Calendar data is being - returned in the CALDAV:calendar-data XML element inside the DAV: - propstat XML element. - - Preconditions: - - (CALDAV:supported-calendar-data): The attributes "content-type" - and "version" of the CALDAV:calendar-data XML element (see - - - - -Daboo, et al. Standards Track [Page 36] - -RFC 4791 CalDAV March 2007 - - - Section 9.6) specify a media type supported by the server for - calendar object resources. - - (CALDAV:valid-filter): The CALDAV:filter XML element (see - Section 9.7) specified in the REPORT request MUST be valid. For - instance, a CALDAV:filter cannot nest a <C:comp name="VEVENT"> - element in a <C:comp name="VTODO"> element, and a CALDAV:filter - cannot nest a <C:time-range start="..." end="..."> element in a - <C:prop name="SUMMARY"> element. - - (CALDAV:supported-filter): The CALDAV:comp-filter (see - Section 9.7.1), CALDAV:prop-filter (see Section 9.7.2), and - CALDAV:param-filter (see Section 9.7.3) XML elements used in the - CALDAV:filter XML element (see Section 9.7) in the REPORT request - only make reference to components, properties, and parameters for - which queries are supported by the server, i.e., if the CALDAV: - filter element attempts to reference an unsupported component, - property, or parameter, this precondition is violated. Servers - SHOULD report the CALDAV:comp-filter, CALDAV:prop-filter, or - CALDAV:param-filter for which it does not provide support. - - <!ELEMENT supported-filter (comp-filter*, - prop-filter*, - param-filter*)> - - (CALDAV:valid-calendar-data): The time zone specified in the - REPORT request MUST be a valid iCalendar object containing a - single valid VTIMEZONE component. - - (CALDAV:min-date-time): Any XML element specifying a range of time - MUST have its start or end DATE or DATE-TIME values greater than - or equal to the value of the CALDAV:min-date-time property value - (Section 5.2.6) on the calendar collections being targeted by the - REPORT request; - - (CALDAV:max-date-time): Any XML element specifying a range of time - MUST have its start or end DATE or DATE-TIME values less than or - equal to the value of the CALDAV:max-date-time property value - (Section 5.2.7) on the calendar collections being targeted by the - REPORT request; - - (CALDAV:supported-collation): Any XML attribute specifying a - collation MUST specify a collation supported by the server as - described in Section 7.5. - - - - - - - -Daboo, et al. Standards Track [Page 37] - -RFC 4791 CalDAV March 2007 - - - Postconditions: - - (DAV:number-of-matches-within-limits): The number of matching - calendar object resources must fall within server-specific, - predefined limits. For example, this condition might be triggered - if a search specification would cause the return of an extremely - large number of responses. - -7.8.1. Example: Partial Retrieval of Events by Time Range - - In this example, the client requests the server to return specific - components and properties of the VEVENT components that overlap the - time range from January 4, 2006, at 00:00:00 A.M. UTC to January 5, - 2006, at 00:00:00 A.M. UTC. In addition, the DAV:getetag property is - also requested and returned as part of the response. Note that the - first calendar object returned is a recurring event whose first - instance lies outside the requested time range, but whose third - instance does overlap the time range. Note that due to the CALDAV: - calendar-data element restrictions, the DTSTAMP property in VEVENT - components has not been returned, and the only property returned in - the VCALENDAR object is VERSION. - - See Appendix B for the calendar data being targeted by this example. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 38] - -RFC 4791 CalDAV March 2007 - - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop> - <D:getetag/> - <C:calendar-data> - <C:comp name="VCALENDAR"> - <C:prop name="VERSION"/> - <C:comp name="VEVENT"> - <C:prop name="SUMMARY"/> - <C:prop name="UID"/> - <C:prop name="DTSTART"/> - <C:prop name="DTEND"/> - <C:prop name="DURATION"/> - <C:prop name="RRULE"/> - <C:prop name="RDATE"/> - <C:prop name="EXRULE"/> - <C:prop name="EXDATE"/> - <C:prop name="RECURRENCE-ID"/> - </C:comp> - <C:comp name="VTIMEZONE"/> - </C:comp> - </C:calendar-data> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VEVENT"> - <C:time-range start="20060104T000000Z" - end="20060105T000000Z"/> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - - -Daboo, et al. Standards Track [Page 39] - -RFC 4791 CalDAV March 2007 - - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd2.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd2"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - DTSTART;TZID=US/Eastern:20060102T120000 - DURATION:PT1H - RRULE:FREQ=DAILY;COUNT=5 - SUMMARY:Event #2 - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - BEGIN:VEVENT - DTSTART;TZID=US/Eastern:20060104T140000 - DURATION:PT1H - RECURRENCE-ID;TZID=US/Eastern:20060104T120000 - SUMMARY:Event #2 bis - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - BEGIN:VEVENT - DTSTART;TZID=US/Eastern:20060106T140000 - DURATION:PT1H - RECURRENCE-ID;TZID=US/Eastern:20060106T120000 - SUMMARY:Event #2 bis bis - UID:00959BC664CA650E933C892C@example.com - - - -Daboo, et al. Standards Track [Page 40] - -RFC 4791 CalDAV March 2007 - - - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd3"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - DTSTART;TZID=US/Eastern:20060104T100000 - DURATION:PT1H - SUMMARY:Event #3 - UID:DC6C50A017428C5216A2F1CD@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - - - - - -Daboo, et al. Standards Track [Page 41] - -RFC 4791 CalDAV March 2007 - - -7.8.2. Example: Partial Retrieval of Recurring Events - - In this example, the client requests the server to return VEVENT - components that overlap the time range from January 3, 2006, at 00: - 00:00 A.M. UTC to January 5, 2006, at 00:00:00 A.M. UTC. Use of the - CALDAV:limit-recurrence-set element causes the server to only return - overridden recurrence components that overlap the time range - specified in that element or that affect other instances that overlap - the time range (e.g., in the case of a THISANDFUTURE behavior). In - this example, the first overridden component in the matching resource - is returned, but the second one is not. - - See Appendix B for the calendar data being targeted by this example. - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop> - <C:calendar-data> - <C:limit-recurrence-set start="20060103T000000Z" - end="20060105T000000Z"/> - </C:calendar-data> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VEVENT"> - <C:time-range start="20060103T000000Z" - end="20060105T000000Z"/> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - - - -Daboo, et al. Standards Track [Page 42] - -RFC 4791 CalDAV March 2007 - - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd2.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd2"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART;TZID=US/Eastern:20060102T120000 - DURATION:PT1H - RRULE:FREQ=DAILY;COUNT=5 - SUMMARY:Event #2 - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART;TZID=US/Eastern:20060104T140000 - DURATION:PT1H - RECURRENCE-ID;TZID=US/Eastern:20060104T120000 - SUMMARY:Event #2 bis - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - - - -Daboo, et al. Standards Track [Page 43] - -RFC 4791 CalDAV March 2007 - - - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd3"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - ATTENDEE;PARTSTAT=ACCEPTED;ROLE=CHAIR:mailto:cyrus@example.com - ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:lisa@example.com - DTSTAMP:20060206T001220Z - DTSTART;TZID=US/Eastern:20060104T100000 - DURATION:PT1H - LAST-MODIFIED:20060206T001330Z - ORGANIZER:mailto:cyrus@example.com - SEQUENCE:1 - STATUS:TENTATIVE - SUMMARY:Event #3 - UID:DC6C50A017428C5216A2F1CD@example.com - X-ABC-GUID:E1CX5Dr-0007ym-Hz@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - - - -Daboo, et al. Standards Track [Page 44] - -RFC 4791 CalDAV March 2007 - - - </D:response> - </D:multistatus> - -7.8.3. Example: Expanded Retrieval of Recurring Events - - In this example, the client requests the server to return VEVENT - components that overlap the time range from January 2, 2006, at 00: - 00:00 A.M. UTC to January 5, 2006, at 00:00:00 A.M. UTC and to return - recurring calendar components expanded into individual recurrence - instance calendar components. Use of the CALDAV:expand element - causes the server to only return overridden recurrence instances that - overlap the time range specified in that element. - - See Appendix B for the calendar data being targeted by this example. - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop> - <C:calendar-data> - <C:expand start="20060103T000000Z" - end="20060105T000000Z"/> - </C:calendar-data> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VEVENT"> - <C:time-range start="20060103T000000Z" - end="20060105T000000Z"/> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - - -Daboo, et al. Standards Track [Page 45] - -RFC 4791 CalDAV March 2007 - - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd2.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd2"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART:20060103T170000 - DURATION:PT1H - RECURRENCE-ID:20060103T170000 - SUMMARY:Event #2 - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART:20060104T190000 - DURATION:PT1H - RECURRENCE-ID:20060104T170000 - SUMMARY:Event #2 bis - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd3"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VEVENT - ATTENDEE;PARTSTAT=ACCEPTED;ROLE=CHAIR:mailto:cyrus@example.com - ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:lisa@example.com - DTSTAMP:20060206T001220Z - DTSTART:20060104T150000 - DURATION:PT1H - LAST-MODIFIED:20060206T001330Z - - - -Daboo, et al. Standards Track [Page 46] - -RFC 4791 CalDAV March 2007 - - - ORGANIZER:mailto:cyrus@example.com - SEQUENCE:1 - STATUS:TENTATIVE - SUMMARY:Event #3 - UID:DC6C50A017428C5216A2F1CD@example.com - X-ABC-GUID:E1CX5Dr-0007ym-Hz@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 47] - -RFC 4791 CalDAV March 2007 - - -7.8.4. Example: Partial Retrieval of Stored Free Busy Components - - In this example, the client requests the server to return the - VFREEBUSY components that have free busy information that overlap the - time range from January 2, 2006, at 00:00:00 A.M. UTC (inclusively) - to January 3, 2006, at 00:00:00 A.M. UTC (exclusively). Use of the - CALDAV:limit-freebusy-set element causes the server to only return - the FREEBUSY property values that overlap the time range specified in - that element. Note that this is not an example of discovering when - the calendar owner is busy. - - See Appendix B for the calendar data being targeted by this example. - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop> - <C:calendar-data> - <C:limit-freebusy-set start="20060102T000000Z" - end="20060103T000000Z"/> - </C:calendar-data> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VFREEBUSY"> - <C:time-range start="20060102T000000Z" - end="20060103T000000Z"/> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 48] - -RFC 4791 CalDAV March 2007 - - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd8.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd8"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VFREEBUSY - ORGANIZER;CN="Bernard Desruisseaux":mailto:bernard@example.com - UID:76ef34-54a3d2@example.com - DTSTAMP:20050530T123421Z - DTSTART:20060101T100000Z - DTEND:20060108T100000Z - FREEBUSY;FBTYPE=BUSY-TENTATIVE:20060102T100000Z/20060102T120000Z - END:VFREEBUSY - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 49] - -RFC 4791 CalDAV March 2007 - - -7.8.5. Example: Retrieval of To-Dos by Alarm Time Range - - In this example, the client requests the server to return the VTODO - components that have an alarm trigger scheduled in the specified time - range. - - See Appendix B for the calendar data being targeted by this example. - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop xmlns:D="DAV:"> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VTODO"> - <C:comp-filter name="VALARM"> - <C:time-range start="20060106T100000Z" - end="20060107T100000Z"/> - </C:comp-filter> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 50] - -RFC 4791 CalDAV March 2007 - - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd4.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd4"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTODO - DTSTAMP:20060205T235300Z - DUE;TZID=US/Eastern:20060106T120000 - LAST-MODIFIED:20060205T235308Z - SEQUENCE:1 - STATUS:NEEDS-ACTION - SUMMARY:Task #2 - UID:E10BA47467C5C69BB74E8720@example.com - BEGIN:VALARM - ACTION:AUDIO - TRIGGER;RELATED=START:-PT10M - END:VALARM - END:VTODO - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - -7.8.6. Example: Retrieval of Event by UID - - In this example, the client requests the server to return the VEVENT - component that has the UID property set to - "DC6C50A017428C5216A2F1CD@example.com". - - See Appendix B for the calendar data being targeted by this example. - - - - - -Daboo, et al. Standards Track [Page 51] - -RFC 4791 CalDAV March 2007 - - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop xmlns:D="DAV:"> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VEVENT"> - <C:prop-filter name="UID"> - <C:text-match collation="i;octet" - >DC6C50A017428C5216A2F1CD@example.com</C:text-match> - </C:prop-filter> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd3"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - - - -Daboo, et al. Standards Track [Page 52] - -RFC 4791 CalDAV March 2007 - - - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - ATTENDEE;PARTSTAT=ACCEPTED;ROLE=CHAIR:mailto:cyrus@example.com - ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:lisa@example.com - DTSTAMP:20060206T001220Z - DTSTART;TZID=US/Eastern:20060104T100000 - DURATION:PT1H - LAST-MODIFIED:20060206T001330Z - ORGANIZER:mailto:cyrus@example.com - SEQUENCE:1 - STATUS:TENTATIVE - SUMMARY:Event #3 - UID:DC6C50A017428C5216A2F1CD@example.com - X-ABC-GUID:E1CX5Dr-0007ym-Hz@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - -7.8.7. Example: Retrieval of Events by PARTSTAT - - In this example, the client requests the server to return the VEVENT - components that have the ATTENDEE property with the value - "mailto:lisa@example.com" and for which the PARTSTAT parameter is set - to NEEDS-ACTION. - - See Appendix B for the calendar data being targeted by this example. - - - - - - - -Daboo, et al. Standards Track [Page 53] - -RFC 4791 CalDAV March 2007 - - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop xmlns:D="DAV:"> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VEVENT"> - <C:prop-filter name="ATTENDEE"> - <C:text-match collation="i;ascii-casemap" - >mailto:lisa@example.com</C:text-match> - <C:param-filter name="PARTSTAT"> - <C:text-match collation="i;ascii-casemap" - >NEEDS-ACTION</C:text-match> - </C:param-filter> - </C:prop-filter> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd3"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - - - -Daboo, et al. Standards Track [Page 54] - -RFC 4791 CalDAV March 2007 - - - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - ATTENDEE;PARTSTAT=ACCEPTED;ROLE=CHAIR:mailto:cyrus@example.com - ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:lisa@example.com - DTSTAMP:20060206T001220Z - DTSTART;TZID=US/Eastern:20060104T100000 - DURATION:PT1H - LAST-MODIFIED:20060206T001330Z - ORGANIZER:mailto:cyrus@example.com - SEQUENCE:1 - STATUS:TENTATIVE - SUMMARY:Event #3 - UID:DC6C50A017428C5216A2F1CD@example.com - X-ABC-GUID:E1CX5Dr-0007ym-Hz@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - -7.8.8. Example: Retrieval of Events Only - - In this example, the client requests the server to return all VEVENT - components. - - See Appendix B for the calendar data being targeted by this example. - - - - - -Daboo, et al. Standards Track [Page 55] - -RFC 4791 CalDAV March 2007 - - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop xmlns:D="DAV:"> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VEVENT"/> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd1.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd1"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - - - -Daboo, et al. Standards Track [Page 56] - -RFC 4791 CalDAV March 2007 - - - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - DTSTAMP:20060206T001102Z - DTSTART;TZID=US/Eastern:20060102T100000 - DURATION:PT1H - SUMMARY:Event #1 - Description:Go Steelers! - UID:74855313FA803DA593CD579A@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd2.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd2"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - - - -Daboo, et al. Standards Track [Page 57] - -RFC 4791 CalDAV March 2007 - - - END:VTIMEZONE - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART;TZID=US/Eastern:20060102T120000 - DURATION:PT1H - RRULE:FREQ=DAILY;COUNT=5 - SUMMARY:Event #2 - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART;TZID=US/Eastern:20060104T140000 - DURATION:PT1H - RECURRENCE-ID;TZID=US/Eastern:20060104T120000 - SUMMARY:Event #2 bis - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART;TZID=US/Eastern:20060106T140000 - DURATION:PT1H - RECURRENCE-ID;TZID=US/Eastern:20060106T120000 - SUMMARY:Event #2 bis bis - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd3"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - - - -Daboo, et al. Standards Track [Page 58] - -RFC 4791 CalDAV March 2007 - - - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - ATTENDEE;PARTSTAT=ACCEPTED;ROLE=CHAIR:mailto:cyrus@example.com - ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:lisa@example.com - DTSTAMP:20060206T001220Z - DTSTART;TZID=US/Eastern:20060104T100000 - DURATION:PT1H - LAST-MODIFIED:20060206T001330Z - ORGANIZER:mailto:cyrus@example.com - SEQUENCE:1 - STATUS:TENTATIVE - SUMMARY:Event #3 - UID:DC6C50A017428C5216A2F1CD@example.com - X-ABC-GUID:E1CX5Dr-0007ym-Hz@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - -7.8.9. Example: Retrieval of All Pending To-Dos - - In this example, the client requests the server to return all VTODO - components that do not include a COMPLETED property and do not have a - STATUS property value matching CANCELLED, i.e., VTODOs that still - need to be worked on. - - See Appendix B for the calendar data being targeted by this example. - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 59] - -RFC 4791 CalDAV March 2007 - - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop xmlns:D="DAV:"> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VTODO"> - <C:prop-filter name="COMPLETED"> - <C:is-not-defined/> - </C:prop-filter> - <C:prop-filter name="STATUS"> - <C:text-match - negate-condition="yes">CANCELLED</C:text-match> - </C:prop-filter> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd4.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd4"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTODO - - - -Daboo, et al. Standards Track [Page 60] - -RFC 4791 CalDAV March 2007 - - - DTSTAMP:20060205T235335Z - DUE;VALUE=DATE:20060104 - STATUS:NEEDS-ACTION - SUMMARY:Task #1 - UID:DDDEEB7915FA61233B861457@example.com - BEGIN:VALARM - ACTION:AUDIO - TRIGGER;RELATED=START:-PT10M - END:VALARM - END:VTODO - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd5.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd5"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTODO - DTSTAMP:20060205T235300Z - DUE;VALUE=DATE:20060106 - LAST-MODIFIED:20060205T235308Z - SEQUENCE:1 - STATUS:NEEDS-ACTION - SUMMARY:Task #2 - UID:E10BA47467C5C69BB74E8720@example.com - BEGIN:VALARM - ACTION:AUDIO - TRIGGER;RELATED=START:-PT10M - END:VALARM - END:VTODO - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - - - - - - -Daboo, et al. Standards Track [Page 61] - -RFC 4791 CalDAV March 2007 - - -7.8.10. Example: Attempt to Query Unsupported Property - - In this example, the client requests the server to return all VEVENT - components that include an X-ABC-GUID property with a value matching - "ABC". However, the server does not support querying that non- - standard property, and instead returns an error response. - - See Appendix B for the calendar data being targeted by this example. - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop xmlns:D="DAV:"> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VEVENT"> - <C:prop-filter name="X-ABC-GUID"> - <C:text-match>ABC</C:text-match> - </C:prop-filter> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 403 Forbidden - Date: Sat, 11 Nov 2005 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:error> - <C:supported-filter> - <C:prop-filter name="X-ABC-GUID"/> - </C:supported-filter> - </D:error> - - - - -Daboo, et al. Standards Track [Page 62] - -RFC 4791 CalDAV March 2007 - - -7.9. CALDAV:calendar-multiget REPORT - - The CALDAV:calendar-multiget REPORT is used to retrieve specific - calendar object resources from within a collection, if the Request- - URI is a collection, or to retrieve a specific calendar object - resource, if the Request-URI is a calendar object resource. This - report is similar to the CALDAV:calendar-query REPORT (see - Section 7.8), except that it takes a list of DAV:href elements, - instead of a CALDAV:filter element, to determine which calendar - object resources to return. - - Support for the CALDAV:calendar-multiget REPORT is REQUIRED. - - Marshalling: - - The request body MUST be a CALDAV:calendar-multiget XML element - (see Section 9.10). If the Request-URI is a collection resource, - then the DAV:href elements MUST refer to calendar object resources - within that collection, and they MAY refer to calendar object - resources at any depth within the collection. As a result, the - "Depth" header MUST be ignored by the server and SHOULD NOT be - sent by the client. If the Request-URI refers to a non-collection - resource, then there MUST be a single DAV:href element that is - equivalent to the Request-URI. - - The response body for a successful request MUST be a DAV: - multistatus XML element. - - The response body for a successful CALDAV:calendar-multiget REPORT - request MUST contain a DAV:response element for each calendar - object resource referenced by the provided set of DAV:href - elements. Calendar data is being returned in the CALDAV:calendar- - data element inside the DAV:prop element. - - In the case of an error accessing any of the provided DAV:href - resources, the server MUST return the appropriate error status - code in the DAV:status element of the corresponding DAV:response - element. - - Preconditions: - - (CALDAV:supported-calendar-data): The attributes "content-type" - and "version" of the CALDAV:calendar-data XML elements (see - Section 9.6) specify a media type supported by the server for - calendar object resources. - - (CALDAV:min-date-time): Any XML element specifying a range of time - MUST have its start or end DATE or DATE-TIME values greater than - - - -Daboo, et al. Standards Track [Page 63] - -RFC 4791 CalDAV March 2007 - - - or equal to the value of the CALDAV:min-date-time property value - (Section 5.2.6) on the calendar collections being targeted by the - REPORT request; - - (CALDAV:max-date-time): Any XML element specifying a range of time - MUST have its start or end DATE or DATE-TIME values less than or - equal to the value of the CALDAV:max-date-time property value - (Section 5.2.7) on the calendar collections being targeted by the - REPORT request; - - Postconditions: - - None. - -7.9.1. Example: Successful CALDAV:calendar-multiget REPORT - - In this example, the client requests the server to return specific - properties of the VEVENT components referenced by specific URIs. In - addition, the DAV:getetag property is also requested and returned as - part of the response. Note that in this example, the resource at - http://cal.example.com/bernard/work/mtg1.ics does not exist, - resulting in an error status response. - - See Appendix B for the calendar data being targeted by this example. - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-multiget xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <D:href>/bernard/work/abcd1.ics</D:href> - <D:href>/bernard/work/mtg1.ics</D:href> - </C:calendar-multiget> - - >> Response << - - HTTP/1.1 207 Multi-Status - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: application/xml; charset="utf-8" - - - -Daboo, et al. Standards Track [Page 64] - -RFC 4791 CalDAV March 2007 - - - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd1.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd1"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - DTSTAMP:20060206T001102Z - DTSTART;TZID=US/Eastern:20060102T100000 - DURATION:PT1H - SUMMARY:Event #1 - Description:Go Steelers! - UID:74855313FA803DA593CD579A@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - <D:response> - <D:href>http://cal.example.com/bernard/work/mtg1.ics</D:href> - <D:status>HTTP/1.1 404 Not Found</D:status> - - - -Daboo, et al. Standards Track [Page 65] - -RFC 4791 CalDAV March 2007 - - - </D:response> - </D:multistatus> - -7.10. CALDAV:free-busy-query REPORT - - The CALDAV:free-busy-query REPORT generates a VFREEBUSY component - containing free busy information for all the calendar object - resources targeted by the request and that have the CALDAV:read-free- - busy or DAV:read privilege granted to the current user. - - Only VEVENT components without a TRANSP property or with the TRANSP - property set to OPAQUE, and VFREEBUSY components SHOULD be considered - in generating the free busy time information. - - In the case of VEVENT components, the free or busy time type (FBTYPE) - of the FREEBUSY properties in the returned VFREEBUSY component SHOULD - be derived from the value of the TRANSP and STATUS properties, as - outlined in the table below: - - +---------------------------++------------------+ - | VEVENT || VFREEBUSY | - +-------------+-------------++------------------+ - | TRANSP | STATUS || FBTYPE | - +=============+=============++==================+ - | | CONFIRMED || BUSY | - | | (default) || | - | OPAQUE +-------------++------------------+ - | (default) | CANCELLED || FREE | - | +-------------++------------------+ - | | TENTATIVE || BUSY-TENTATIVE | - | +-------------++------------------+ - | | x-name || BUSY or | - | | || x-name | - +-------------+-------------++------------------+ - | | CONFIRMED || | - | TRANSPARENT | CANCELLED || FREE | - | | TENTATIVE || | - | | x-name || | - +-------------+-------------++------------------+ - - Duplicate busy time periods with the same FBTYPE parameter value - SHOULD NOT be specified in the returned VFREEBUSY component. Servers - SHOULD coalesce consecutive or overlapping busy time periods of the - same type. Busy time periods with different FBTYPE parameter values - MAY overlap. - - Support for the CALDAV:free-busy-query REPORT is REQUIRED. - - - - -Daboo, et al. Standards Track [Page 66] - -RFC 4791 CalDAV March 2007 - - - Marshalling: - - The request body MUST be a CALDAV:free-busy-query XML element (see - Section 9.11), which MUST contain exactly one CALDAV:time-range - XML element, as defined in Section 9.9. - - The request MAY include a Depth header. If no Depth header is - included, Depth:0 is assumed. - - The response body for a successful request MUST be an iCalendar - object that contains exactly one VFREEBUSY component that - describes the busy time intervals for the calendar object - resources containing VEVENT, or VFREEBUSY components that satisfy - the Depth value and for which the current user is at least granted - the CALDAV:read-free-busy privilege. If no calendar object - resources are found to satisfy these conditions, a VFREEBUSY - component with no FREEBUSY property MUST be returned. This report - only returns busy time information. Free time information can be - inferred from the returned busy time information. - - If the current user is not granted the CALDAV:read-free-busy or - DAV:read privileges on the Request-URI, the CALDAV:free-busy-query - REPORT request MUST fail and return a 404 (Not Found) status - value. This restriction will prevent users from discovering URLs - of resources for which they are only granted the CALDAV:read-free- - busy privilege. - - The CALDAV:free-busy-query REPORT request can only be run against - a collection (either a regular collection or a calendar - collection). An attempt to run the report on a calendar object - resource MUST fail and return a 403 (Forbidden) status value. - - Preconditions: - - None. - - Postconditions: - - (DAV:number-of-matches-within-limits): The number of matching - calendar object resources must fall within server-specific, - predefined limits. For example, this postcondition might fail if - the specified CALDAV:time-range would cause an extremely large - number of calendar object resources to be considered in computing - the response. - - - - - - - -Daboo, et al. Standards Track [Page 67] - -RFC 4791 CalDAV March 2007 - - -7.10.1. Example: Successful CALDAV:free-busy-query REPORT - - In this example, the client requests the server to return free busy - information on the calendar collection /bernard/work/, between 9:00 - A.M. and 5:00 P.M. EST (2:00 P.M. and 10:00 P.M. UTC) on the January - 4, 2006. The server responds, indicating two busy time intervals of - one hour, one of which is tentative. - - See Appendix B for the calendar data being targeted by this example. - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:free-busy-query xmlns:C="urn:ietf:params:xml:ns:caldav"> - <C:time-range start="20060104T140000Z" - end="20060105T220000Z"/> - </C:free-busy-query> - - >> Response << - - HTTP/1.1 200 OK - Date: Sat, 11 Nov 2006 09:32:12 GMT - Content-Type: text/calendar - Content-Length: xxxx - - BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Server//EN - BEGIN:VFREEBUSY - DTSTAMP:20050125T090000Z - DTSTART:20060104T140000Z - DTEND:20060105T220000Z - FREEBUSY;FBTYPE=BUSY-TENTATIVE:20060104T150000Z/PT1H - FREEBUSY:20060104T190000Z/PT1H - END:VFREEBUSY - END:VCALENDAR - - - - - - - - - -Daboo, et al. Standards Track [Page 68] - -RFC 4791 CalDAV March 2007 - - -8. Guidelines - -8.1. Client-to-Client Interoperability - - There are a number of actions clients can take that will be legal - (the server will not return errors), but that can degrade - interoperability with other client implementations accessing the same - data. For example, a recurrence rule could be replaced with a set of - recurrence dates, a single recurring event could be replaced with a - set of independent resources to represent each recurrence, or the - start/end time values can be translated from the original time zone - to another time zone. Although this advice amounts to iCalendar - interoperability best practices and is not limited only to CalDAV - usage, interoperability problems are likely to be more evident in - CalDAV use cases. - -8.2. Synchronization Operations - - WebDAV already provides functionality required to synchronize a - collection or set of collections, to make changes offline, and - provides a simple way to resolve conflicts when reconnected. ETags - are the key to making this work, but these are not required of all - WebDAV servers. Since offline functionality is more important to - calendar applications than to some other WebDAV applications, CalDAV - servers MUST support ETags, as specified in Section 5.3.4. - -8.2.1. Use of Reports - -8.2.1.1. Restrict the Time Range - - The reports provided in CalDAV can be used by clients to optimize - their performance in terms of network bandwidth usage and resource - consumption on the local client machine. Both are certainly major - considerations for mobile or handheld devices with limited capacity, - but they are also relevant to desktop client applications in cases - where the calendar collections contain large amounts of data. - - Typically, clients present calendar data to users in views that span - a finite time interval, so whenever possible, clients should only - retrieve calendar components from the server using CALDAV:calendar- - query REPORT, combined with a CALDAV:time-range element, to limit the - set of returned components to just those needed to populate the - current view. - - - - - - - - -Daboo, et al. Standards Track [Page 69] - -RFC 4791 CalDAV March 2007 - - -8.2.1.2. Synchronize by Time Range - - Typically in a calendar, historical data (events, to-dos, etc. that - have completed prior to the current date) do not change, though they - may be deleted. As a result, a client can speed up the - synchronization process by only considering data for the present time - and the future up to a reasonable limit (e.g., one week, one month). - If the user then tries to examine a portion of the calendar outside - the range that has been synchronized, the client can perform another - synchronization operation on the new time interval being examined. - This "just-in-time" synchronization can minimize bandwidth for common - user interaction behaviors. - -8.2.1.3. Synchronization Process - - If a client wants to support calendar data synchronization, as - opposed to downloading calendar data each time it is needed, the - client needs to cache the calendar object resource's URI and ETag, - along with the actual calendar data. While the URI remains static - for the lifetime of the calendar object resource, the ETag will - change with each successive change to the calendar object resource. - Thus, to synchronize a local data cache with the server, the client - can first fetch the URI/ETag pairs for the time interval being - considered, and compare those results with the cached data. Any - cached component whose ETag differs from that on the server needs to - be refreshed. - - In order to properly detect the changes between the server and client - data, the client will need to keep a record of which calendar object - resources have been created, changed, or deleted since the last - synchronization operation so that it can reconcile those changes with - the data on the server. - - Here's an example of how to do that: - - The client issues a CALDAV:calendar-query REPORT request for a - specific time range and asks for only the DAV:getetag property to be - returned: - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 70] - -RFC 4791 CalDAV March 2007 - - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop> - <D:getetag/> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"> - <C:comp-filter name="VEVENT"> - <C:time-range start="20040902T000000Z" - end="20040903T000000Z"/> - </C:comp-filter> - </C:comp-filter> - </C:filter> - </C:calendar-query> - - The client then uses the results to determine which calendar object - resources have changed, been created, or deleted on the server, and - how those relate to locally cached calendar object resources that may - have changed, been created, or deleted. If the client determines - that there are calendar object resources on the server that need to - be fetched, the client issues a CALDAV:calendar-multiget REPORT - request to fetch its calendar data: - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-multiget xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <D:href>/bernard/work/abcd1.ics</D:href> - <D:href>/bernard/work/mtg1.ics</D:href> - </C:calendar-multiget> - - - - - - -Daboo, et al. Standards Track [Page 71] - -RFC 4791 CalDAV March 2007 - - -8.2.2. Restrict the Properties Returned - - A client may not need all the calendar properties of a calendar - object resource when presenting information to the user. Since some - calendar property values can be large (e.g., ATTACH or ATTENDEE), a - client can choose to restrict the calendar properties to be returned - in a calendaring REPORT request to those it knows it will use. - - However, if a client needs to make a change to a calendar object - resource, it can only change the entire calendar object resource via - a PUT request. There is currently no way to incrementally make a - change to a set of calendar properties of a calendar object resource. - As a result, the client will have to get the entire calendar object - resource that is being changed. - -8.3. Use of Locking - - WebDAV locks can be used to prevent two clients that are modifying - the same resource from either overwriting each others' changes - (though that problem can also be solved by using ETags) or wasting - time making changes that will conflict with another set of changes. - In a multi-user calendar system, an interactive calendar client could - lock an event while the user is editing the event, and unlock the - event when the user finishes or cancels. Locks can also be used to - prevent changes while data is being reorganized. For example, a - calendar client might lock two calendar collections prior to moving a - bunch of calendar resources from one to another. - - Clients are responsible for requesting a lock timeout period that is - appropriate to the use case. When the user explicitly decides to - reserve a resource and prevent other changes, a long timeout might be - appropriate, but in cases where the client automatically decides to - lock the resource, the timeout should be short (and the client can - always refresh the lock should it need to). A short lock timeout - means that if the client is unable to remove the lock, the other - calendar users aren't prevented from making changes. - -8.4. Finding Calendars - - Much of the time, a calendar client (or agent) will discover a new - calendar's location by being provided directly with the URL. For - example, a user will type his or her own calendar location into - client configuration information or copy and paste a URL from email - into the calendar application. The client need only confirm that the - URL points to a resource that is a calendar collection. The client - may also be able to browse WebDAV collections to find calendar - collections. - - - - -Daboo, et al. Standards Track [Page 72] - -RFC 4791 CalDAV March 2007 - - - The choice of HTTP URLs means that calendar object resources are - backward compatible with existing software, but does have the - disadvantage that existing software does not usually know to look at - the OPTIONS response to that URL to determine what can be done with - it. This is somewhat of a barrier for WebDAV usage as well as with - CalDAV usage. This specification does not offer a way through this - other than making the information available in the OPTIONS response - should this be requested. - - For calendar sharing and scheduling use cases, one might wish to find - the calendar belonging to another user. If the other user has a - calendar in the same repository, that calendar can be found by using - the principal namespace required by WebDAV ACL support. For other - cases, the authors have no universal solution, but implementers can - consider whether to use vCard [RFC2426] or LDAP [RFC4511] standards - together with calendar attributes [RFC2739]. - - Because CalDAV requires servers to support WebDAV ACL [RFC3744], - including principal namespaces, and with the addition of the CALDAV: - calendar-home-set property, there are a couple options for CalDAV - clients to find one's own calendar or another user's calendar. - - In this case, a DAV:principal-match REPORT is used to find a named - property (the CALDAV:calendar-home-set) on the Principal-URL of the - current user. Using this, a WebDAV client can learn "who am I" and - "where are my calendars". The REPORT request body looks like this: - - <?xml version="1.0" encoding="utf-8" ?> - <D:principal-match xmlns:D="DAV:"> - <D:self/> - <D:prop> - <C:calendar-home-set - xmlns:C="urn:ietf:params:xml:ns:caldav"/> - </D:prop> - </D:principal-match> - - To find other users' calendars, the DAV:principal-property-search - REPORT can be used to filter on some properties and return others. - To search for a calendar owned by a user named "Laurie", the REPORT - request body would look like this: - - - - - - - - - - - -Daboo, et al. Standards Track [Page 73] - -RFC 4791 CalDAV March 2007 - - - <?xml version="1.0" encoding="utf-8" ?> - <D:principal-property-search xmlns:D="DAV:"> - <D:property-search> - <D:prop> - <D:displayname/> - </D:prop> - <D:match>Laurie</D:match> - </D:property-search> - <D:prop> - <C:calendar-home-set - xmlns:C="urn:ietf:params:xml:ns:caldav"/> - <D:displayname/> - </D:prop> - </D:principal-property-search> - - The server performs a case-sensitive or caseless search for a - matching string subset of "Laurie" within the DAV:displayname - property. Thus, the server might return "Laurie Dusseault", "Laurier - Desruisseaux", or "Wilfrid Laurier" as matching DAV:displayname - values, and return the calendars for each of these. - -8.5. Storing and Using Attachments - - CalDAV clients MAY create attachments in calendar components either - as inline or external. This section contains some guidelines for - creating and managing attachments. - -8.5.1. Inline Attachments - - CalDAV clients MUST support inline attachments as specified in - iCalendar [RFC2445]. CalDAV servers MUST support inline attachments, - so clients can rely on being able to create attachments this way. On - the other hand, inline attachments have some drawbacks: - - o Servers MAY impose limitations on the size of calendar object - resources (i.e., refusing PUT requests of very large iCalendar - objects). Servers that impose such limitations MUST use the - CALDAV:max-resource-size property on a calendar collection to - inform the client as to what the limitation is (see - Section 5.2.5). - - o Servers MAY impose storage quota limitations on calendar - collections (See [RFC4331]). - - o Any change to a calendar object resource containing an inline - attachment requires the entire inline attachment to be re- - uploaded. - - - - -Daboo, et al. Standards Track [Page 74] - -RFC 4791 CalDAV March 2007 - - - o Clients synchronizing a changed calendar object resource have to - download the entire calendar object resource, even if the - attachment is unchanged. - -8.5.2. External Attachments - - CalDAV clients SHOULD support downloading of external attachments - referenced by arbitrary URI schemes, by either processing them - directly, or by passing the attachment URI to a suitable "helper - application" for processing, if such an application exists. CalDAV - clients MUST support downloading of external attachments referenced - by the "http" or "https" URI schemes. An external attachment could - be: - - o In a collection in the calendar collection containing the calendar - object resource; - - o Somewhere else in the same repository that hosts the calendar - collection; or - - o On an HTTP or FTP server elsewhere. - - CalDAV servers MAY provide support for child collections in calendar - collections. CalDAV servers MAY allow the MKCOL method to create - child collections in calendar collections. Child collections of - calendar collections MAY contain any type of resource except calendar - collections that they MUST NOT contain. Some CalDAV servers won't - allow child collections in calendar collections, and it may be - possible on such a server to discover other locations where - attachments can be stored. - - Clients are entirely responsible for maintaining reference - consistency with calendar components that link to external - attachments. A client deleting a calendar component with an external - attachment might therefore also delete the attachment if that's - appropriate; however, appropriateness can be very hard to determine. - A new component might easily reference some pre-existing Web resource - that is intended to have independent existence from the calendar - component (the "attachment" could be a major proposal to be discussed - in a meeting, for instance). Best practices will probably emerge and - should probably be documented, but for now, clients should be wary of - engaging in aggressive "cleanup" of external attachments. A client - could involve the user in making decisions about removing - unreferenced documents, or a client could be conservative in only - deleting attachments it had created. - - Also, clients are responsible for consistency of permissions when - using external attachments. One reason for servers to support the - - - -Daboo, et al. Standards Track [Page 75] - -RFC 4791 CalDAV March 2007 - - - storage of attachments within child collections of calendar - collections is that ACL inheritance might make it easier to grant the - same permissions to attachments that are granted on the calendar - collection. Otherwise, it can be very difficult to keep permissions - synchronized. With attachments stored on separate repositories, it - can be impossible to keep permissions consistent -- the two - repositories may not support the same permissions or have the same - set of principals. Some systems have used tickets or other anonymous - access control mechanisms to provide partially satisfactory solutions - to these kinds of problems. - -8.6. Storing and Using Alarms - - Note that all CalDAV calendar collections (including those the user - might treat as public or group calendars) can contain alarm - information on events and to-dos. Users can synchronize a calendar - between multiple devices and decide to have alarms execute on a - different device than the device that created the alarm. Not all - alarm action types are completely interoperable (e.g., those that - name a sound file to play). - - When the action is AUDIO and the client is configured to execute - the alarm, the client SHOULD play the suggested sound if it's - available or play another sound, but SHOULD NOT rewrite the alarm - just to replace the suggested sound with a sound that's locally - available. - - When the action is DISPLAY and the client is configured to execute - the alarm, the client SHOULD execute a display alarm by displaying - according to the suggested description or some reasonable - replacement, but SHOULD NOT rewrite the alarm for its own - convenience. - - When the action is EMAIL and the client is incapable of sending - email, it SHOULD ignore the alarm, but it MUST continue to - synchronize the alarm itself. - - This specification makes no recommendations about executing alarms - of type PROCEDURE, except to note that clients are advised to take - care to avoid creating security holes by executing these. - - Non-interoperable alarm information (e.g., should somebody define a - color to be used in a display alarm) should be put in non-standard - properties inside the VALARM component in order to keep the basic - alarm usable on all devices. - - Clients that allow changes to calendar object resources MUST - synchronize the alarm data that already exists in the resources. - - - -Daboo, et al. Standards Track [Page 76] - -RFC 4791 CalDAV March 2007 - - - Clients MAY execute alarms that are downloaded in this fashion, - possibly based on user preference. If a client is only doing read - operations on a calendar and there is no risk of losing alarm - information, then the client MAY discard alarm information. - - This specification makes no attempt to provide multi-user alarms on - group calendars or to find out for whom an alarm is intended. - Addressing those issues might require extensions to iCalendar; for - example, to store alarms per-user, or to indicate for which user a - VALARM was intended. In the meantime, clients might maximize - interoperability by generally not uploading alarm information to - public, group, or resource calendars. - -9. XML Element Definitions - -9.1. CALDAV:calendar XML Element - - Name: calendar - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies the resource type of a calendar collection. - - Description: See Section 4.2. - - Definition: - - <!ELEMENT calendar EMPTY> - -9.2. CALDAV:mkcalendar XML Element - - Name: mkcalendar - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies a request that includes the WebDAV property - values to be set for a calendar collection resource when it is - created. - - Description: See Section 5.3.1. - - Definition: - - <!ELEMENT mkcalendar (DAV:set)> - - - - - - - -Daboo, et al. Standards Track [Page 77] - -RFC 4791 CalDAV March 2007 - - -9.3. CALDAV:mkcalendar-response XML Element - - Name: mkcalendar-response - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies a response body for a successful MKCALENDAR - request. - - Description: See Section 5.3.1. - - Definition: - - <!ELEMENT mkcalendar-response ANY> - -9.4. CALDAV:supported-collation XML Element - - Name: supported-collation - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Identifies a single collation via its collation identifier, - as defined by [RFC4790]. - - Description: The CALDAV:supported-collation contains the text of a - collation identifier, as described in Section 7.5.1. - - Definition: - - <!ELEMENT supported-collation (#PCDATA)> - PCDATA value: collation identifier - -9.5. CALDAV:calendar-query XML Element - - Name: calendar-query - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Defines a report for querying calendar object resources. - - Description: See Section 7.8. - - Definition: - - <!ELEMENT calendar-query ((DAV:allprop | - DAV:propname | - DAV:prop)?, filter, timezone?)> - - - - -Daboo, et al. Standards Track [Page 78] - -RFC 4791 CalDAV March 2007 - - -9.6. CALDAV:calendar-data XML Element - - Name: calendar-data - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specified one of the following: - - 1. A supported media type for calendar object resources when - nested in the CALDAV:supported-calendar-data property; - - 2. The parts of a calendar object resource should be returned by - a calendaring report; - - 3. The content of a calendar object resource in a response to a - calendaring report. - - Description: When nested in the CALDAV:supported-calendar-data - property, the CALDAV:calendar-data XML element specifies a media - type supported by the CalDAV server for calendar object resources. - - When used in a calendaring REPORT request, the CALDAV:calendar- - data XML element specifies which parts of calendar object - resources need to be returned in the response. If the CALDAV: - calendar-data XML element doesn't contain any CALDAV:comp element, - calendar object resources will be returned in their entirety. - - Finally, when used in a calendaring REPORT response, the CALDAV: - calendar-data XML element specifies the content of a calendar - object resource. Given that XML parsers normalize the two- - character sequence CRLF (US-ASCII decimal 13 and US-ASCII decimal - 10) to a single LF character (US-ASCII decimal 10), the CR - character (US-ASCII decimal 13) MAY be omitted in calendar object - resources specified in the CALDAV:calendar-data XML element. - Furthermore, calendar object resources specified in the CALDAV: - calendar-data XML element MAY be invalid per their media type - specification if the CALDAV:calendar-data XML element part of the - calendaring REPORT request did not specify required properties - (e.g., UID, DTSTAMP, etc.), or specified a CALDAV:prop XML element - with the "novalue" attribute set to "yes". - - Note: The CALDAV:calendar-data XML element is specified in requests - and responses inside the DAV:prop XML element as if it were a - WebDAV property. However, the CALDAV:calendar-data XML element is - not a WebDAV property and, as such, is not returned in PROPFIND - responses, nor used in PROPPATCH requests. - - - - - -Daboo, et al. Standards Track [Page 79] - -RFC 4791 CalDAV March 2007 - - - Note: The iCalendar data embedded within the CALDAV:calendar-data - XML element MUST follow the standard XML character data encoding - rules, including use of <, >, & etc. entity encoding or - the use of a <![CDATA[ ... ]]> construct. In the later case, the - iCalendar data cannot contain the character sequence "]]>", which - is the end delimiter for the CDATA section. - - Definition: - - <!ELEMENT calendar-data EMPTY> - - when nested in the CALDAV:supported-calendar-data property - to specify a supported media type for calendar object - resources; - - <!ELEMENT calendar-data (comp?, - (expand | limit-recurrence-set)?, - limit-freebusy-set?)> - - when nested in the DAV:prop XML element in a calendaring - REPORT request to specify which parts of calendar object - resources should be returned in the response; - - <!ELEMENT calendar-data (#PCDATA)> - PCDATA value: iCalendar object - - when nested in the DAV:prop XML element in a calendaring - REPORT response to specify the content of a returned - calendar object resource. - - <!ATTLIST calendar-data content-type CDATA "text/calendar" - version CDATA "2.0"> - content-type value: a MIME media type - version value: a version string - - attributes can be used on all three variants of the - CALDAV:calendar-data XML element. - -9.6.1. CALDAV:comp XML Element - - Name: comp - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Defines which component types to return. - - - - - - -Daboo, et al. Standards Track [Page 80] - -RFC 4791 CalDAV March 2007 - - - Description: The name value is a calendar component name (e.g., - VEVENT). - - Definition: - - <!ELEMENT comp ((allprop | prop*), (allcomp | comp*))> - - <!ATTLIST comp name CDATA #REQUIRED> - name value: a calendar component name - - Note: The CALDAV:prop and CALDAV:allprop elements have the same name - as the DAV:prop and DAV:allprop elements defined in [RFC2518]. - However, the CALDAV:prop and CALDAV:allprop elements are defined - in the "urn:ietf:params:xml:ns:caldav" namespace instead of the - "DAV:" namespace. - -9.6.2. CALDAV:allcomp XML Element - - Name: allcomp - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies that all components shall be returned. - - Description: The CALDAV:allcomp XML element can be used when the - client wants all types of components returned by a calendaring - REPORT request. - - Definition: - - <!ELEMENT allcomp EMPTY> - -9.6.3. CALDAV:allprop XML Element - - Name: allprop - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies that all properties shall be returned. - - Description: The CALDAV:allprop XML element can be used when the - client wants all properties of components returned by a - calendaring REPORT request. - - Definition: - - <!ELEMENT allprop EMPTY> - - - - -Daboo, et al. Standards Track [Page 81] - -RFC 4791 CalDAV March 2007 - - - Note: The CALDAV:allprop element has the same name as the DAV: - allprop element defined in [RFC2518]. However, the CALDAV:allprop - element is defined in the "urn:ietf:params:xml:ns:caldav" - namespace instead of the "DAV:" namespace. - -9.6.4. CALDAV:prop XML Element - - Name: prop - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Defines which properties to return in the response. - - Description: The "name" attribute specifies the name of the calendar - property to return (e.g., ATTENDEE). The "novalue" attribute can - be used by clients to request that the actual value of the - property not be returned (if the "novalue" attribute is set to - "yes"). In that case, the server will return just the iCalendar - property name and any iCalendar parameters and a trailing ":" - without the subsequent value data. - - Definition: - - <!ELEMENT prop EMPTY> - - <!ATTLIST prop name CDATA #REQUIRED - novalue (yes | no) "no"> - name value: a calendar property name - novalue value: "yes" or "no" - - Note: The CALDAV:prop element has the same name as the DAV:prop - element defined in [RFC2518]. However, the CALDAV:prop element is - defined in the "urn:ietf:params:xml:ns:caldav" namespace instead - of the "DAV:" namespace. - -9.6.5. CALDAV:expand XML Element - - Name: expand - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Forces the server to expand recurring components into - individual recurrence instances. - - Description: The CALDAV:expand XML element specifies that for a - given calendaring REPORT request, the server MUST expand the - recurrence set into calendar components that define exactly one - - - - -Daboo, et al. Standards Track [Page 82] - -RFC 4791 CalDAV March 2007 - - - recurrence instance, and MUST return only those whose scheduled - time intersect a specified time range. - - The "start" attribute specifies the inclusive start of the time - range, and the "end" attribute specifies the non-inclusive end of - the time range. Both attributes are specified as date with UTC - time value. The value of the "end" attribute MUST be greater than - the value of the "start" attribute. - - The server MUST use the same logic as defined for CALDAV:time- - range to determine if a recurrence instance intersects the - specified time range. - - Recurring components, other than the initial instance, MUST - include a RECURRENCE-ID property indicating which instance they - refer to. - - The returned calendar components MUST NOT use recurrence - properties (i.e., EXDATE, EXRULE, RDATE, and RRULE) and MUST NOT - have reference to or include VTIMEZONE components. Date and local - time with reference to time zone information MUST be converted - into date with UTC time. - - Definition: - - <!ELEMENT expand EMPTY> - - <!ATTLIST expand start CDATA #REQUIRED - end CDATA #REQUIRED> - start value: an iCalendar "date with UTC time" - end value: an iCalendar "date with UTC time" - -9.6.6. CALDAV:limit-recurrence-set XML Element - - Name: limit-recurrence-set - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies a time range to limit the set of "overridden - components" returned by the server. - - Description: The CALDAV:limit-recurrence-set XML element specifies - that for a given calendaring REPORT request, the server MUST - return, in addition to the "master component", only the - "overridden components" that impact a specified time range. An - overridden component impacts a time range if its current start and - end times overlap the time range, or if the original start and end - - - - -Daboo, et al. Standards Track [Page 83] - -RFC 4791 CalDAV March 2007 - - - times -- the ones that would have been used if the instance were - not overridden -- overlap the time range. - - The "start" attribute specifies the inclusive start of the time - range, and the "end" attribute specifies the non-inclusive end of - the time range. Both attributes are specified as date with UTC - time value. The value of the "end" attribute MUST be greater than - the value of the "start" attribute. - - The server MUST use the same logic as defined for CALDAV:time- - range to determine if the current or original scheduled time of an - "overridden" recurrence instance intersects the specified time - range. - - Overridden components that have a RANGE parameter on their - RECURRENCE-ID property may specify one or more instances in the - recurrence set, and some of those instances may fall within the - specified time range or may have originally fallen within the - specified time range prior to being overridden. If that is the - case, the overridden component MUST be included in the results, as - it has a direct impact on the interpretation of instances within - the specified time range. - - Definition: - - <!ELEMENT limit-recurrence-set EMPTY> - - <!ATTLIST limit-recurrence-set start CDATA #REQUIRED - end CDATA #REQUIRED> - start value: an iCalendar "date with UTC time" - end value: an iCalendar "date with UTC time" - -9.6.7. CALDAV:limit-freebusy-set XML Element - - Name: limit-freebusy-set - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies a time range to limit the set of FREEBUSY values - returned by the server. - - Description: The CALDAV:limit-freebusy-set XML element specifies - that for a given calendaring REPORT request, the server MUST only - return the FREEBUSY property values of a VFREEBUSY component that - intersects a specified time range. - - The "start" attribute specifies the inclusive start of the time - range, and the "end" attribute specifies the non-inclusive end of - - - -Daboo, et al. Standards Track [Page 84] - -RFC 4791 CalDAV March 2007 - - - the time range. Both attributes are specified as "date with UTC - time" value. The value of the "end" attribute MUST be greater - than the value of the "start" attribute. - - The server MUST use the same logic as defined for CALDAV:time- - range to determine if a FREEBUSY property value intersects the - specified time range. - - Definition: - - <!ELEMENT limit-freebusy-set EMPTY> - - <!ATTLIST limit-freebusy-set start CDATA #REQUIRED - end CDATA #REQUIRED> - start value: an iCalendar "date with UTC time" - end value: an iCalendar "date with UTC time" - -9.7. CALDAV:filter XML Element - - Name: filter - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies a filter to limit the set of calendar components - returned by the server. - - Description: The CALDAV:filter XML element specifies the search - filter used to limit the calendar components returned by a - calendaring REPORT request. - - Definition: - - <!ELEMENT filter (comp-filter)> - -9.7.1. CALDAV:comp-filter XML Element - - Name: comp-filter - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies search criteria on calendar components. - - Description: The CALDAV:comp-filter XML element specifies a query - targeted at the calendar object (i.e., VCALENDAR) or at a specific - calendar component type (e.g., VEVENT). The scope of the - CALDAV:comp-filter XML element is the calendar object when used as - a child of the CALDAV:filter XML element. The scope of the - CALDAV:comp-filter XML element is the enclosing calendar component - - - -Daboo, et al. Standards Track [Page 85] - -RFC 4791 CalDAV March 2007 - - - when used as a child of another CALDAV:comp-filter XML element. A - CALDAV:comp-filter is said to match if: - - * The CALDAV:comp-filter XML element is empty and the calendar - object or calendar component type specified by the "name" - attribute exists in the current scope; - - or: - - * The CALDAV:comp-filter XML element contains a CALDAV:is-not- - defined XML element and the calendar object or calendar - component type specified by the "name" attribute does not exist - in the current scope; - - or: - - * The CALDAV:comp-filter XML element contains a CALDAV:time-range - XML element and at least one recurrence instance in the - targeted calendar component is scheduled to overlap the - specified time range, and all specified CALDAV:prop-filter and - CALDAV:comp-filter child XML elements also match the targeted - calendar component; - - or: - - * The CALDAV:comp-filter XML element only contains CALDAV:prop- - filter and CALDAV:comp-filter child XML elements that all match - the targeted calendar component. - - Definition: - - <!ELEMENT comp-filter (is-not-defined | (time-range?, - prop-filter*, comp-filter*))> - - <!ATTLIST comp-filter name CDATA #REQUIRED> - name value: a calendar object or calendar component - type (e.g., VEVENT) - -9.7.2. CALDAV:prop-filter XML Element - - Name: prop-filter - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies search criteria on calendar properties. - - Description: The CALDAV:prop-filter XML element specifies a query - targeted at a specific calendar property (e.g., CATEGORIES) in the - - - -Daboo, et al. Standards Track [Page 86] - -RFC 4791 CalDAV March 2007 - - - scope of the enclosing calendar component. A calendar property is - said to match a CALDAV:prop-filter if: - - * The CALDAV:prop-filter XML element is empty and a property of - the type specified by the "name" attribute exists in the - enclosing calendar component; - - or: - - * The CALDAV:prop-filter XML element contains a CALDAV:is-not- - defined XML element and no property of the type specified by - the "name" attribute exists in the enclosing calendar - component; - - or: - - * The CALDAV:prop-filter XML element contains a CALDAV:time-range - XML element and the property value overlaps the specified time - range, and all specified CALDAV:param-filter child XML elements - also match the targeted property; - - or: - - * The CALDAV:prop-filter XML element contains a CALDAV:text-match - XML element and the property value matches it, and all - specified CALDAV:param-filter child XML elements also match the - targeted property; - - Definition: - - <!ELEMENT prop-filter (is-not-defined | - ((time-range | text-match)?, - param-filter*))> - - <!ATTLIST prop-filter name CDATA #REQUIRED> - name value: a calendar property name (e.g., ATTENDEE) - -9.7.3. CALDAV:param-filter XML Element - - Name: param-filter - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Limits the search to specific parameter values. - - Description: The CALDAV:param-filter XML element specifies a query - targeted at a specific calendar property parameter (e.g., - PARTSTAT) in the scope of the calendar property on which it is - - - -Daboo, et al. Standards Track [Page 87] - -RFC 4791 CalDAV March 2007 - - - defined. A calendar property parameter is said to match a CALDAV: - param-filter if: - - * The CALDAV:param-filter XML element is empty and a parameter of - the type specified by the "name" attribute exists on the - calendar property being examined; - - or: - - * The CALDAV:param-filter XML element contains a CALDAV:is-not- - defined XML element and no parameter of the type specified by - the "name" attribute exists on the calendar property being - examined; - - Definition: - - <!ELEMENT param-filter (is-not-defined | text-match?)> - - <!ATTLIST param-filter name CDATA #REQUIRED> - name value: a property parameter name (e.g., PARTSTAT) - -9.7.4. CALDAV:is-not-defined XML Element - - Name: is-not-defined - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies that a match should occur if the enclosing - component, property, or parameter does not exist. - - Description: The CALDAV:is-not-defined XML element specifies that a - match occurs if the enclosing component, property, or parameter - value specified in a calendaring REPORT request does not exist in - the calendar data being tested. - - Definition: - - <!ELEMENT is-not-defined EMPTY> - -9.7.5. CALDAV:text-match XML Element - - Name: text-match - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies a substring match on a property or parameter - value. - - - - -Daboo, et al. Standards Track [Page 88] - -RFC 4791 CalDAV March 2007 - - - Description: The CALDAV:text-match XML element specifies text used - for a substring match against the property or parameter value - specified in a calendaring REPORT request. - - The "collation" attribute is used to select the collation that the - server MUST use for character string matching. In the absence of - this attribute, the server MUST use the "i;ascii-casemap" - collation. - - The "negate-condition" attribute is used to indicate that this - test returns a match if the text matches when the attribute value - is set to "no", or return a match if the text does not match, if - the attribute value is set to "yes". For example, this can be - used to match components with a STATUS property not set to - CANCELLED. - - Definition: - - <!ELEMENT text-match (#PCDATA)> - PCDATA value: string - - <!ATTLIST text-match collation CDATA "i;ascii-casemap" - negate-condition (yes | no) "no"> - -9.8. CALDAV:timezone XML Element - - Name: timezone - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies the time zone component to use when determining - the results of a report. - - Description: The CALDAV:timezone XML element specifies that for a - given calendaring REPORT request, the server MUST rely on the - specified VTIMEZONE component instead of the CALDAV:calendar- - timezone property of the calendar collection, in which the - calendar object resource is contained to resolve "date" values and - "date with local time" values (i.e., floating time) to "date with - UTC time" values. The server will require this information to - determine if a calendar component scheduled with "date" values or - "date with local time" values intersects a CALDAV:time-range - specified in a CALDAV:calendar-query REPORT. - - Note: The iCalendar data embedded within the CALDAV:timezone XML - element MUST follow the standard XML character data encoding - rules, including use of <, >, & etc. entity encoding or - the use of a <![CDATA[ ... ]]> construct. In the later case, the - - - -Daboo, et al. Standards Track [Page 89] - -RFC 4791 CalDAV March 2007 - - - iCalendar data cannot contain the character sequence "]]>", which - is the end delimiter for the CDATA section. - - Definition: - - <!ELEMENT timezone (#PCDATA)> - PCDATA value: an iCalendar object with exactly one VTIMEZONE - -9.9. CALDAV:time-range XML Element - - Name: time-range - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: Specifies a time range to limit the set of calendar - components returned by the server. - - Description: The CALDAV:time-range XML element specifies that for a - given calendaring REPORT request, the server MUST only return the - calendar object resources that, depending on the context, have a - component or property whose value intersects a specified time - range. - - The "start" attribute specifies the inclusive start of the time - range, and the "end" attribute specifies the non-inclusive end of - the time range. Both attributes MUST be specified as "date with - UTC time" value. Time ranges open at one end can be specified by - including only one attribute; however, at least one attribute MUST - always be present in the CALDAV:time-range element. If either the - "start" or "end" attribute is not specified in the CALDAV:time- - range XML element, assume "-infinity" and "+infinity" as their - value, respectively. If both "start" and "end" are present, the - value of the "end" attribute MUST be greater than the value of the - "start" attribute. - - Time range tests MUST consider every recurrence instance when - testing the time range condition; if any one instance matches, - then the test returns true. Testing recurrence instances requires - the server to infer an effective value for DTSTART, DTEND, - DURATION, and DUE properties for an instance based on the - recurrence patterns and any overrides. - - A VEVENT component overlaps a given time range if the condition - for the corresponding component state specified in the table below - is satisfied. Note that, as specified in [RFC2445], the DTSTART - property is REQUIRED in the VEVENT component. The conditions - depend on the presence of the DTEND and DURATION properties in the - VEVENT component. Furthermore, the value of the DTEND property - - - -Daboo, et al. Standards Track [Page 90] - -RFC 4791 CalDAV March 2007 - - - MUST be later in time than the value of the DTSTART property. The - duration of a VEVENT component with no DTEND and DURATION - properties is 1 day (+P1D) when the DTSTART is a DATE value, and 0 - seconds when the DTSTART is a DATE-TIME value. - - +---------------------------------------------------------------+ - | VEVENT has the DTEND property? | - | +-----------------------------------------------------------+ - | | VEVENT has the DURATION property? | - | | +-------------------------------------------------------+ - | | | DURATION property value is greater than 0 seconds? | - | | | +---------------------------------------------------+ - | | | | DTSTART property is a DATE-TIME value? | - | | | | +-----------------------------------------------+ - | | | | | Condition to evaluate | - +---+---+---+---+-----------------------------------------------+ - | Y | N | N | * | (start < DTEND AND end > DTSTART) | - +---+---+---+---+-----------------------------------------------+ - | N | Y | Y | * | (start < DTSTART+DURATION AND end > DTSTART) | - | | +---+---+-----------------------------------------------+ - | | | N | * | (start <= DTSTART AND end > DTSTART) | - +---+---+---+---+-----------------------------------------------+ - | N | N | N | Y | (start <= DTSTART AND end > DTSTART) | - +---+---+---+---+-----------------------------------------------+ - | N | N | N | N | (start < DTSTART+P1D AND end > DTSTART) | - +---+---+---+---+-----------------------------------------------+ - - A VTODO component is said to overlap a given time range if the - condition for the corresponding component state specified in the - table below is satisfied. The conditions depend on the presence - of the DTSTART, DURATION, DUE, COMPLETED, and CREATED properties - in the VTODO component. Note that, as specified in [RFC2445], the - DUE value MUST be a DATE-TIME value equal to or after the DTSTART - value if specified. - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 91] - -RFC 4791 CalDAV March 2007 - - - +-------------------------------------------------------------------+ - | VTODO has the DTSTART property? | - | +---------------------------------------------------------------+ - | | VTODO has the DURATION property? | - | | +-----------------------------------------------------------+ - | | | VTODO has the DUE property? | - | | | +-------------------------------------------------------+ - | | | | VTODO has the COMPLETED property? | - | | | | +---------------------------------------------------+ - | | | | | VTODO has the CREATED property? | - | | | | | +-----------------------------------------------+ - | | | | | | Condition to evaluate | - +---+---+---+---+---+-----------------------------------------------+ - | Y | Y | N | * | * | (start <= DTSTART+DURATION) AND | - | | | | | | ((end > DTSTART) OR | - | | | | | | (end >= DTSTART+DURATION)) | - +---+---+---+---+---+-----------------------------------------------+ - | Y | N | Y | * | * | ((start < DUE) OR (start <= DTSTART)) | - | | | | | | AND | - | | | | | | ((end > DTSTART) OR (end >= DUE)) | - +---+---+---+---+---+-----------------------------------------------+ - | Y | N | N | * | * | (start <= DTSTART) AND (end > DTSTART) | - +---+---+---+---+---+-----------------------------------------------+ - | N | N | Y | * | * | (start < DUE) AND (end >= DUE) | - +---+---+---+---+---+-----------------------------------------------+ - | N | N | N | Y | Y | ((start <= CREATED) OR (start <= COMPLETED))| - | | | | | | AND | - | | | | | | ((end >= CREATED) OR (end >= COMPLETED))| - +---+---+---+---+---+-----------------------------------------------+ - | N | N | N | Y | N | (start <= COMPLETED) AND (end >= COMPLETED) | - +---+---+---+---+---+-----------------------------------------------+ - | N | N | N | N | Y | (end > CREATED) | - +---+---+---+---+---+-----------------------------------------------+ - | N | N | N | N | N | TRUE | - +---+---+---+---+---+-----------------------------------------------+ - - A VJOURNAL component overlaps a given time range if the condition - for the corresponding component state specified in the table below - is satisfied. The conditions depend on the presence of the - DTSTART property in the VJOURNAL component and on whether the - DTSTART is a DATE-TIME or DATE value. The effective "duration" of - a VJOURNAL component is 1 day (+P1D) when the DTSTART is a DATE - value, and 0 seconds when the DTSTART is a DATE-TIME value. - - - - - - - - -Daboo, et al. Standards Track [Page 92] - -RFC 4791 CalDAV March 2007 - - - +----------------------------------------------------+ - | VJOURNAL has the DTSTART property? | - | +------------------------------------------------+ - | | DTSTART property is a DATE-TIME value? | - | | +--------------------------------------------+ - | | | Condition to evaluate | - +---+---+--------------------------------------------+ - | Y | Y | (start <= DTSTART) AND (end > DTSTART) | - +---+---+--------------------------------------------+ - | Y | N | (start < DTSTART+P1D) AND (end > DTSTART) | - +---+---+--------------------------------------------+ - | N | * | FALSE | - +---+---+--------------------------------------------+ - - A VFREEBUSY component overlaps a given time range if the condition - for the corresponding component state specified in the table below - is satisfied. The conditions depend on the presence in the - VFREEBUSY component of the DTSTART and DTEND properties, and any - FREEBUSY properties in the absence of DTSTART and DTEND. Any - DURATION property is ignored, as it has a special meaning when - used in a VFREEBUSY component. - - When only FREEBUSY properties are used, each period in each - FREEBUSY property is compared against the time range, irrespective - of the type of free busy information (free, busy, busy-tentative, - busy-unavailable) represented by the property. - - - +------------------------------------------------------+ - | VFREEBUSY has both the DTSTART and DTEND properties? | - | +--------------------------------------------------+ - | | VFREEBUSY has the FREEBUSY property? | - | | +----------------------------------------------+ - | | | Condition to evaluate | - +---+---+----------------------------------------------+ - | Y | * | (start <= DTEND) AND (end > DTSTART) | - +---+---+----------------------------------------------+ - | N | Y | (start < freebusy-period-end) AND | - | | | (end > freebusy-period-start) | - +---+---+----------------------------------------------+ - | N | N | FALSE | - +---+---+----------------------------------------------+ - - A VALARM component is said to overlap a given time range if the - following condition holds: - - (start <= trigger-time) AND (end > trigger-time) - - - - -Daboo, et al. Standards Track [Page 93] - -RFC 4791 CalDAV March 2007 - - - A VALARM component can be defined such that it triggers repeatedly. - Such a VALARM component is said to overlap a given time range if at - least one of its triggers overlaps the time range. - - The calendar properties COMPLETED, CREATED, DTEND, DTSTAMP, - DTSTART, DUE, and LAST-MODIFIED overlap a given time range if the - following condition holds: - - (start <= date-time) AND (end > date-time) - - Note that if DTEND is not present in a VEVENT, but DURATION is, then - the test should instead operate on the 'effective' DTEND, i.e., - DTSTART+DURATION. Similarly, if DUE is not present in a VTODO, but - DTSTART and DURATION are, then the test should instead operate on the - 'effective' DUE, i.e., DTSTART+DURATION. - - The semantic of CALDAV:time-range is not defined for any other - calendar components and properties. - - Definition: - - <!ELEMENT time-range EMPTY> - - <!ATTLIST time-range start CDATA #IMPLIED - end CDATA #IMPLIED> - start value: an iCalendar "date with UTC time" - end value: an iCalendar "date with UTC time" - -9.10. CALDAV:calendar-multiget XML Element - - Name: calendar-multiget - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: CalDAV report used to retrieve specific calendar object - resources. - - Description: See Section 7.9. - - Definition: - - <!ELEMENT calendar-multiget ((DAV:allprop | - DAV:propname | - DAV:prop)?, DAV:href+)> - - - - - - - -Daboo, et al. Standards Track [Page 94] - -RFC 4791 CalDAV March 2007 - - -9.11. CALDAV:free-busy-query XML Element - - Name: free-busy-query - - Namespace: urn:ietf:params:xml:ns:caldav - - Purpose: CalDAV report used to generate a VFREEBUSY to determine - busy time over a specific time range. - - Description: See Section 7.10. - - Definition: - - <!ELEMENT free-busy-query (time-range)> - -10. Internationalization Considerations - - CalDAV allows internationalized strings to be stored and retrieved - for the description of calendar collections (see Section 5.2.1). - - The CALDAV:calendar-query REPORT (Section 7.8) includes a text - searching option controlled by the CALDAV:text-match element, and - details of character handling are covered in the description of that - element (see Section 9.7.5). - -11. Security Considerations - - HTTP protocol transactions are sent in the clear over the network - unless protection from snooping is negotiated. This can be - accomplished by use of TLS, as defined in [RFC2818]. In particular, - HTTP Basic authentication MUST NOT be used unless TLS is in effect. - - Servers MUST take adequate precautions to ensure that malicious - clients cannot consume excessive server resources (CPU, memory, disk, - etc.) through carefully crafted reports. For example, a client could - upload an event with a recurrence rule that specifies a recurring - event occurring every second for the next 100 years, which would - result in approximately 3 x 10^9 instances! A report that asks for - recurrences to be expanded over that range would likely constitute a - denial-of-service attack on the server. - - When creating new resources (including calendar collections), clients - MUST ensure that the resource name (the last path segment of the - resource URI) assigned to the new resource does not expose any data - from within the iCalendar resource itself or information about the - nature of a calendar collection. This is required to ensure that the - presence of a specific iCalendar component or nature of components in - a collection cannot be inferred based on the name of a resource. - - - -Daboo, et al. Standards Track [Page 95] - -RFC 4791 CalDAV March 2007 - - - When rolling up free-busy information, more information about a - user's events is exposed if busy periods overlap or are adjacent - (this tells the client requesting the free-busy information that the - calendar owner has at least two events, rather than knowing only that - the calendar owner has one or more events during the busy period). - Thus, a conservative approach to calendar data privacy would have - servers always coalesce such busy periods when they are the same - type. - - Procedure alarms are a known security risk for either clients or - servers to handle, particularly when the alarm was created by another - agent. Clients and servers are not required to execute such - procedure alarms. - - Security considerations described in iCalendar [RFC2445] and iTIP - [RFC2446] are also applicable to CalDAV. - - Beyond these, CalDAV does not raise any security considerations that - are not present in HTTP [RFC2616] and WebDAV [RFC2518], [RFC3253], - [RFC3744]. - -12. IANA Considerations - - This document uses one new URN to identify a new XML namespace. The - URN conforms to a registry mechanism described in [RFC3688]. - -12.1. Namespace Registration - - Registration request for the CalDAV namespace: - - URI: urn:ietf:params:xml:ns:caldav - - Registrant Contact: See the "Authors' Addresses" section of this - document. - - XML: None. Namespace URIs do not represent an XML specification. - -13. Acknowledgements - - The authors would like to thank the following individuals for - contributing their ideas and support for writing this specification: - Michael Arick, Mario Bonin, Chris Bryant, Scott Carr, Andre - Courtemanche, Mike Douglass, Ted Hardie, Marten den Haring, Jeffrey - Harris, Sam Hartman, Helge Hess, Jeff McCullough, Alexey Melnikov, - Dan Mosedale, Brian Moseley, Francois Perrault, Kervin L. Pierre, - Julian F. Reschke, Wilfredo Sanchez Vega, Mike Shaver, Jari - Urpalainen, Simon Vaillancourt, and Jim Whitehead. - - - - -Daboo, et al. Standards Track [Page 96] - -RFC 4791 CalDAV March 2007 - - - The authors would also like to thank the Calendaring and Scheduling - Consortium for advice with this specification, and for organizing - interoperability testing events to help refine it. - -14. References - -14.1. Normative References - - [RFC2119] Bradner, S., "Key words for use in RFCs to - Indicate Requirement Levels", BCP 14, - RFC 2119, March 1997. - - [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol - Version 1.0", RFC 2246, January 1999. - - [RFC2445] Dawson, F. and Stenerson, D., "Internet - Calendaring and Scheduling Core Object - Specification (iCalendar)", RFC 2445, - November 1998. - - [RFC2446] Silverberg, S., Mansour, S., Dawson, F., and - R. Hopson, "iCalendar Transport-Independent - Interoperability Protocol (iTIP) Scheduling - Events, BusyTime, To-dos and Journal - Entries", RFC 2446, November 1998. - - [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, - S., and D. Jensen, "HTTP Extensions for - Distributed Authoring -- WEBDAV", RFC 2518, - February 1999. - - [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, - H., Masinter, L., Leach, P., and T. Berners- - Lee, "Hypertext Transfer Protocol -- - HTTP/1.1", RFC 2616, June 1999. - - [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, - May 2000. - - [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, - C., and J. Whitehead, "Versioning Extensions - to WebDAV (Web Distributed Authoring and - Versioning)", RFC 3253, March 2002. - - [RFC3688] Mealling, M., "The IETF XML Registry", - BCP 81, RFC 3688, January 2004. - - - - - -Daboo, et al. Standards Track [Page 97] - -RFC 4791 CalDAV March 2007 - - - [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. - Whitehead, "Web Distributed Authoring and - Versioning (WebDAV) Access Control Protocol", - RFC 3744, May 2004. - - [RFC4346] Dierks, T. and E. Rescorla, "The Transport - Layer Security (TLS) Protocol Version 1.1", - RFC 4346, April 2006. - - [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, - "Internet Application Protocol Collation - Registry", RFC 4790, March 2007. - - [W3C.REC-xml-20060816] Paoli, J., Maler, E., Yergeau, F., Sperberg- - McQueen, C., and T. Bray, "Extensible Markup - Language (XML) 1.0 (Fourth Edition)", World - Wide Web Consortium Recommendation REC-xml- - 20060816, August 2006, - <http://www.w3.org/TR/2006/REC-xml-20060816>. - -14.2. Informative References - - [RFC2426] Dawson, F. and T. Howes, "vCard MIME - Directory Profile", RFC 2426, September 1998. - - [RFC2739] Small, T., Hennessy, D., and F. Dawson, - "Calendar Attributes for vCard and LDAP", - RFC 2739, January 2000. - - [RFC4331] Korver, B. and L. Dusseault, "Quota and Size - Properties for Distributed Authoring and - Versioning (DAV) Collections", RFC 4331, - February 2006. - - [RFC4511] Sermersheim, J., "Lightweight Directory - Access Protocol (LDAP): The Protocol", - RFC 4511, June 2006. - - [rfc2518bis] Dusseault, L., "HTTP Extensions for - Distributed Authoring - WebDAV", Work - in Progress, December 2006. - - - - - - - - - - -Daboo, et al. Standards Track [Page 98] - -RFC 4791 CalDAV March 2007 - - -Appendix A. CalDAV Method Privilege Table (Normative) - - The following table extends the WebDAV Method Privilege Table - specified in Appendix B of [RFC3744]. - - +------------+------------------------------------------------------+ - | METHOD | PRIVILEGES | - +------------+------------------------------------------------------+ - | MKCALENDAR | DAV:bind | - | REPORT | DAV:read or CALDAV:read-free-busy (on all referenced | - | | resources) | - +------------+------------------------------------------------------+ - -Appendix B. Calendar Collections Used in the Examples - - This appendix shows the calendar object resources contained in the - calendar collection queried in the examples throughout this document. - - The content of the calendar collection is being shown as if it were - returned by a CALDAV:calendar-query REPORT request designed to return - all the calendar data in the collection: - - >> Request << - - REPORT /bernard/work/ HTTP/1.1 - Host: cal.example.com - Depth: 1 - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <C:calendar-query xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - <D:prop> - <D:getetag/> - <C:calendar-data/> - </D:prop> - <C:filter> - <C:comp-filter name="VCALENDAR"/> - </C:filter> - </C:calendar-query> - - >> Response << - - HTTP/1.1 207 Multi-Status - Content-Type: application/xml; charset="utf-8" - Content-Length: xxxx - - - - -Daboo, et al. Standards Track [Page 99] - -RFC 4791 CalDAV March 2007 - - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:caldav"> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd1.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd1"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - DTSTAMP:20060206T001102Z - DTSTART;TZID=US/Eastern:20060102T100000 - DURATION:PT1H - SUMMARY:Event #1 - Description:Go Steelers! - UID:74855313FA803DA593CD579A@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd2.ics</D:href> - <D:propstat> - - - -Daboo, et al. Standards Track [Page 100] - -RFC 4791 CalDAV March 2007 - - - <D:prop> - <D:getetag>"fffff-abcd2"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART;TZID=US/Eastern:20060102T120000 - DURATION:PT1H - RRULE:FREQ=DAILY;COUNT=5 - SUMMARY:Event #2 - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - BEGIN:VEVENT - DTSTAMP:20060206T001121Z - DTSTART;TZID=US/Eastern:20060104T140000 - DURATION:PT1H - RECURRENCE-ID;TZID=US/Eastern:20060104T120000 - SUMMARY:Event #2 bis - UID:00959BC664CA650E933C892C@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href> - - - -Daboo, et al. Standards Track [Page 101] - -RFC 4791 CalDAV March 2007 - - - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd3"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTIMEZONE - LAST-MODIFIED:20040110T032845Z - TZID:US/Eastern - BEGIN:DAYLIGHT - DTSTART:20000404T020000 - RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 - TZNAME:EDT - TZOFFSETFROM:-0500 - TZOFFSETTO:-0400 - END:DAYLIGHT - BEGIN:STANDARD - DTSTART:20001026T020000 - RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 - TZNAME:EST - TZOFFSETFROM:-0400 - TZOFFSETTO:-0500 - END:STANDARD - END:VTIMEZONE - BEGIN:VEVENT - ATTENDEE;PARTSTAT=ACCEPTED;ROLE=CHAIR:mailto:cyrus@example.com - ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:lisa@example.com - DTSTAMP:20060206T001220Z - DTSTART;TZID=US/Eastern:20060104T100000 - DURATION:PT1H - LAST-MODIFIED:20060206T001330Z - ORGANIZER:mailto:cyrus@example.com - SEQUENCE:1 - STATUS:TENTATIVE - SUMMARY:Event #3 - UID:DC6C50A017428C5216A2F1CD@example.com - END:VEVENT - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd4.ics</D:href> - <D:propstat> - <D:prop> - - - -Daboo, et al. Standards Track [Page 102] - -RFC 4791 CalDAV March 2007 - - - <D:getetag>"fffff-abcd4"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTODO - DTSTAMP:20060205T235335Z - DUE;VALUE=DATE:20060104 - STATUS:NEEDS-ACTION - SUMMARY:Task #1 - UID:DDDEEB7915FA61233B861457@example.com - BEGIN:VALARM - ACTION:AUDIO - TRIGGER;RELATED=START:-PT10M - END:VALARM - END:VTODO - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd5.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd5"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTODO - DTSTAMP:20060205T235300Z - DUE;VALUE=DATE:20060106 - LAST-MODIFIED:20060205T235308Z - SEQUENCE:1 - STATUS:NEEDS-ACTION - SUMMARY:Task #2 - UID:E10BA47467C5C69BB74E8720@example.com - BEGIN:VALARM - ACTION:AUDIO - TRIGGER;RELATED=START:-PT10M - END:VALARM - END:VTODO - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - - - -Daboo, et al. Standards Track [Page 103] - -RFC 4791 CalDAV March 2007 - - - </D:response> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd6.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd6"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTODO - COMPLETED:20051223T122322Z - DTSTAMP:20060205T235400Z - DUE;VALUE=DATE:20051225 - LAST-MODIFIED:20060205T235308Z - SEQUENCE:1 - STATUS:COMPLETED - SUMMARY:Task #3 - UID:E10BA47467C5C69BB74E8722@example.com - END:VTODO - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd7.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd7"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VTODO - DTSTAMP:20060205T235600Z - DUE;VALUE=DATE:20060101 - LAST-MODIFIED:20060205T235308Z - SEQUENCE:1 - STATUS:CANCELLED - SUMMARY:Task #4 - UID:E10BA47467C5C69BB74E8725@example.com - END:VTODO - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - - - -Daboo, et al. Standards Track [Page 104] - -RFC 4791 CalDAV March 2007 - - - </D:propstat> - </D:response> - - <D:response> - <D:href>http://cal.example.com/bernard/work/abcd8.ics</D:href> - <D:propstat> - <D:prop> - <D:getetag>"fffff-abcd8"</D:getetag> - <C:calendar-data>BEGIN:VCALENDAR - VERSION:2.0 - PRODID:-//Example Corp.//CalDAV Client//EN - BEGIN:VFREEBUSY - ORGANIZER;CN="Bernard Desruisseaux":mailto:bernard@example.com - UID:76ef34-54a3d2@example.com - DTSTAMP:20050530T123421Z - DTSTART:20060101T000000Z - DTEND:20060108T000000Z - FREEBUSY:20050531T230000Z/20050601T010000Z - FREEBUSY;FBTYPE=BUSY-TENTATIVE:20060102T100000Z/20060102T120000Z - FREEBUSY:20060103T100000Z/20060103T120000Z - FREEBUSY:20060104T100000Z/20060104T120000Z - FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:20060105T100000Z/20060105T120000Z - FREEBUSY:20060106T100000Z/20060106T120000Z - END:VFREEBUSY - END:VCALENDAR - </C:calendar-data> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - - </D:multistatus> - - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 105] - -RFC 4791 CalDAV March 2007 - - -Authors' Addresses - - Cyrus Daboo - Apple Inc. - 1 Infinite Loop - Cupertino, CA 95014 - USA - - EMail: cyrus@daboo.name - URI: http://www.apple.com/ - - - Bernard Desruisseaux - Oracle Corporation - 600 Blvd. de Maisonneuve West - Suite 1900 - Montreal, QC H3A 3J2 - CANADA - - EMail: bernard.desruisseaux@oracle.com - URI: http://www.oracle.com/ - - - Lisa Dusseault - CommerceNet - 169 University Ave. - Palo Alto, CA 94301 - USA - - EMail: ldusseault@commerce.net - URI: http://commerce.net/ - - - - - - - - - - - - - - - - - - - - -Daboo, et al. Standards Track [Page 106] - -RFC 4791 CalDAV March 2007 - - -Full Copyright Statement - - Copyright (C) The IETF Trust (2007). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND - THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS - OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF - THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - -Daboo, et al. Standards Track [Page 107] - |