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) 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.