tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 4791

 
 
 

Calendaring Extensions to WebDAV (CalDAV)

Part 4 of 5, p. 51 to 77
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 51 
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.

Top      Up      ToC       Page 52 
   >> 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

Top      Up      ToC       Page 53 
   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.

Top      Up      ToC       Page 54 
   >> 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

Top      Up      ToC       Page 55 
   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.

Top      Up      ToC       Page 56 
   >> 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

Top      Up      ToC       Page 57 
   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

Top      Up      ToC       Page 58 
   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

Top      Up      ToC       Page 59 
   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.

Top      Up      ToC       Page 60 
   >> 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

Top      Up      ToC       Page 61 
   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>

Top      Up      ToC       Page 62 
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>

Top      Up      ToC       Page 63 
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

Top      Up      ToC       Page 64 
      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"

Top      Up      ToC       Page 65 
   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>

Top      Up      ToC       Page 66 
     </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.

Top      Up      ToC       Page 67 
   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.

Top      Up      ToC       Page 68 
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

Top      Up      ToC       Page 69 
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.

Top      Up      ToC       Page 70 
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:

Top      Up      ToC       Page 71 
   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>

Top      Up      ToC       Page 72 
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.

Top      Up      ToC       Page 73 
   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:

Top      Up      ToC       Page 74 
   <?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.

Top      Up      ToC       Page 75 
   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

Top      Up      ToC       Page 76 
   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.

Top      Up      ToC       Page 77 
   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)

Next RFC Part