9.9. CALDAV:time-range XML Element

Name

time-range

Namespace

urn

Purpose

Specifies a time range to limit the set of calendar components returned by the server.

Description

The CALDAV 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 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.

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

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

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

   
   start value: an iCalendar "date with UTC time"
   end value: an iCalendar "date with UTC time"