RFC 4791
Calendaring Extensions to WebDAV (CalDAV)
Pages: 107
Proposed Standard
→ Errata
Updated by: 5689 6638 6764 7809 7953 8996
Proposed Standard
→ Errata
Updated by: 5689 6638 6764 7809 7953 8996
Part 4 of 5 – Pages 51 to 77
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.
>> 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
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.
>> 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
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.
>> 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
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
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
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.
>> 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
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>
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>
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
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"
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>
</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.
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.
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
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.
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:
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>
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.
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:
<?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.
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
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.
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.
(page 77 continued on part 5)