| Calendering Extensions | C. Daboo |
| Internet-Draft | Apple |
| Intended status: Informational | A. Quillaud |
| Expires: September 6, 2019 | Oracle |
| K. Murchison, Ed. | |
| FastMail | |
| March 5, 2019 |
CalDAV Managed Attachments
draft-ietf-calext-caldav-attachments-04
This specification defines an extension to the calendar access protocol (CalDAV) to allow attachments associated with iCalendar data to be stored and managed on the server.
This specification documents existing code deployed by multiple vendors. It is published as an Informational specification rather than Standards Track due to its noncompliance with multiple best current practices of HTTP.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 6, 2019.
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The iCalendar data format is used to represent calendar data and is used with iCalendar Transport-independent Interoperability Protocol (iTIP) to handle scheduling operations between calendar users.
[RFC4791] defines the Calendaring Extensions to WebDAV (CalDAV), based on HTTP, for accessing calendar data stored on a server.
Calendar users often want to include attachments with their calendar data events or tasks (for example a copy of a presentation, or the meeting agenda). iCalendar provides an "ATTACH" property whose value is either the inline Base64 encoded attachment data, or a URL specifying the location of the attachment data.
Use of inline attachment data is not ideal with CalDAV because the data would need to be uploaded to the server each time a change to the calendar data is done - even minor changes such as a change to the summary. Whilst a client could choose to use a URL value instead, the problem then becomes where and how the client discovers an appropriate URL to use and how it ensures that only those attendees listed in the event or task are able to access it.
This specification solves this problem by having the client send the attachment to the server, separately from the iCalendar data, and the server takes care of adding appropriate "ATTACH" properties in the iCalendar data as well as managing access privileges. The server can also provide additional information to the client about each attachment in the iCalendar data, such as the size and an identifier.
Although this extension to CalDAV has wide deployment, its design does not comply with some of the best current practices of HTTP, namely:
Additionally, this extension misuses the Content-Disposition header field as a request header field to convey a filename for an attachment rather than using an existing request header field suitable for that purpose, such as "Slug" (see Section 9.7 of [RFC5023]).
Rather than creating interoperability problems with deployed code by updating the design of this extension to be compliant with best current practices and to allow this specification to be placed on the Standards Track, it was decided to simply document how existing implementations interoperate and to publish the document as Informational.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The notation used in this memo is the ABNF notation of [RFC5234] as used by iCalendar. Any syntax elements shown below that are not explicitly defined in this specification come from iCalendar.
There are four main operations a client needs to do with attachments for calendar data: add, update, remove, and retrieve. The first three operations are carried out by the client issuing an HTTP POST request on the calendar object resource to which the attachment is associated and specifying the appropriate "action" query parameter (see Section 3.3). In the case of the remove operation, the client can alternatively directly update the calendar object resource and remove the relevant "ATTACH" properties (see Section 3.9). The retrieve operation is accomplished by simply issuing an HTTP GET request targeting the attachment URI specified by the calendar resource's "ATTACH" property (see Section 3.10).
iCalendar data stored in a CalDAV calendar object resource can contain multiple components when recurrences are involved. In such a situation, the client needs to be able to target a specific recurrence instance or multiple instances when adding or deleting attachments. As a result, the POST request needs to provide a way for the client to specify which recurrence instances should be targeted for the attachment operation. This is accomplished through use of additional query parameters on the POST request-URI.
A server that supports the features described in this specification is REQUIRED to support the CalDAV "calendar-access" [RFC4791] features.
In addition, such a server SHOULD support the "return=representation" Prefer header field preference on successful HTTP PUT and POST requests targeting existing calendar object resources, by returning the new representation of that calendar resource (including its new ETag header field value) in the response.
A server supporting the features described in this specification MUST include "calendar-managed-attachments" as a token in the DAV response header field (as defined in Section 10.1 of [RFC4918]) from an OPTIONS request on a calendar home collection.
A server might choose to not support storing managed attachments on a per-recurrence instance basis (i.e., they can only be added to all instances as a whole). If that is the case, the server MUST also include "calendar-managed-attachments-no-recurrence" as a token in the DAV response header field from an OPTIONS request on a calendar home collection. When that field is present, clients MUST NOT attempt any managed attachment operations that target specific recurrence instances.
An HTTP POST request is used to add, update, or remove attachments. These requests are subject to the preconditions listed in Section 3.11. The request-URI will contain various query parameters to specify the behavior.
The "action" query parameter is used to identify which attachment operation the client is requesting. This parameter MUST be present once on each POST request used to manage attachments. One of these three values MUST be used:
Example:
https://calendar.example.com/events/1.ics?action=attachment-add
The "rid" query parameter is used to identify which recurrence instances are being targeted by the client for the attachment operation. This query parameter MUST contain one or more items, separated by commas (0x2C). The item values can be in one of two forms:
If the "rid" query parameter is not present, all recurrence instances in the calendar object resource are targeted.
The "rid" query parameter MUST NOT be present in the case of an update operation, or if the server chooses not to support per-recurrence instance managed attachments (see Section 3.1).
Example (targeting the master instance and a specific overridden instance):
https://calendar.example.com/events/1.ics? action=attachment-add&rid=M,20111022T160000
The "managed-id" query parameter is used to identify which "ATTACH" property is being updated or removed. The value of this query parameter MUST match the "MANAGED-ID" property parameter value on the "ATTACH" property in the calendar object resource instance(s) targeted by the request.
The "managed-id" query parameter MUST NOT be present in the case of an add operation.
Example:
https://calendar.example.com/events/1.ics? action=attachment-update&managed-id=aUNhbGVuZGFy
To add an attachment to an existing calendar object resource, the following occurs:
In the following example, the client adds a new attachment to a non recurring event and asks the server (via the Prefer header field) to return the modified version of that event in the response.
>> Request <<
POST /events/64.ics?action=attachment-add HTTP/1.1
Host: cal.example.com
Content-Type: text/html; charset="utf-8"
Content-Disposition:attachment;filename=agenda.html
Content-Length: xxxx
Prefer: return=representation
<html>
<body>
<h1>Agenda</h1>
</body>
</html>
>> Response <<
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: yyyy Content-Location: https://cal.example.com/events/64.ics ETag: "123456789-000-111" Cal-Managed-ID: 97S BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Server//EN BEGIN:VEVENT UID:20010712T182145Z-123401@example.com DTSTAMP:20120201T203412Z DTSTART:20120714T170000Z DTEND:20120715T040000Z SUMMARY:One-off meeting ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R END:VEVENT END:VCALENDAR
When an attachment is updated the server MUST change the associated "MANAGED-ID" parameter and MAY change the "ATTACH" property value. With this approach, clients are able to determine when an attachment has been updated by some other client by looking for a change to either the "ATTACH" property value, or the "MANAGED-ID" parameter value.
To change the data of an existing managed attachment in a calendar object resource, the following occurs:
The update operation does not take a "rid" parameter and does not add, or remove, any "ATTACH" property in the targeted calendar object resource. To link an existing attachment to a new instance, the client simply does a PUT on the calendar object resource, adding an "ATTACH" property which duplicates the existing one (see Section 3.7).
In the following example, the client updates an existing attachment and asks the server (via the Prefer header field) to return the updated version of that event in the response.
>> Request <<
POST /events/64.ics?action=attachment-update&managed-id=97S HTTP/1.1
Host: cal.example.com
Content-Type: text/html; charset="utf-8"
Content-Disposition:attachment;filename=agenda.html
Content-Length: xxxx
Prefer: return=representation
<html>
<body>
<h1>Agenda</h1>
<p>Discuss attachment draft</p>
</body>
</html>
>> Response <<
HTTP/1.1 200 OK Content-Type: text/calendar; charset="utf-8" Content-Length: yyyz Content-Location: https://cal.example.com/events/64.ics Cal-Managed-ID: 98S ETag: "123456789-000-222" BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Server//EN BEGIN:VEVENT UID:20010712T182145Z-123401@example.com DTSTAMP:20120201T203412Z DTSTART:20120714T170000Z DTEND:20120715T040000Z SUMMARY:One-off meeting ATTACH;MANAGED-ID=98S;FMTTYPE=text/html;SIZE=xxxy; FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R END:VEVENT END:VCALENDAR
To remove an existing attachment from a calendar object, the following occurs:
In the following example, the client deletes an existing attachment by passing its managed-id in the request. The Prefer header field is not set in the request so the calendar object resource data is not returned in the response.
>> Request <<
POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1 Host: cal.example.com Content-Length: 0
>> Response <<
HTTP/1.1 204 No Content
Content-Length: 0
Clients can make use of existing managed attachments by adding the corresponding "ATTACH" property to calendar object resources (subject to the restrictions described in Section 3.12.2)
If a managed attachment is used in more than calendar resource, servers SHOULD NOT change either the "MANAGED-ID" parameter value or the "ATTACH" property value for these attachments - this ensures that clients do not have to download the attachment data again if they already have it cached. Additionally, servers SHOULD validate "SIZE" parameter values and replace incorrect values with the actual sizes of existing attachments.
These PUT requests are subject to the preconditions listed in Section 3.11.
Servers MUST NOT allow clients to update attachment data directly via a PUT on the attachment URI (or via any other HTTP method that modifies content). Instead, attachments can only be updated via use of POST requests on the calendar data.
Clients can remove attachments by simply re-writing the calendar object resource data to remove the appropriate "ATTACH" properties. Servers MUST NOT allow clients to delete attachments directly via a DELETE request on the attachment URI.
Clients retrieve attachments by issuing an HTTP GET request using the value of the corresponding "ATTACH" property as the request-URI, taking into account the substitution mechanism associated with the "CALDAV:managed-attachments-server-URL" property (see Section 6.1).
This specification creates additional preconditions for the POST method.
The new preconditions are:
A POST request to add, modify, or delete a managed attachment results in an implicit modification of the targeted calendar resource (equivalent of a PUT). As a consequence, clients should also be prepared to handle preconditions associated with this implicit PUT. This includes (but is not limited to):
A PUT request to add or modify and existing calendar object resource can make reference to an existing managed attachment. The following new preconditions is defined:
If a precondition for a request is not satisfied:
The WebDAV Quotas specification defines two live WebDAV properties (DAV:quota-available-bytes and DAV:quota-used-bytes) to communicate storage quota information to clients. Server implementations MAY choose to include managed attachments sizes when calculating the amount of storage used by a particular resource.
Access to the managed attachments store in a calendar object resource SHOULD be restricted to only those calendar users who have access to that calendar object either directly, or indirectly (via being an attendee who would receive a scheduling message).
When accessing a managed attachment, clients SHOULD be prepared to authenticate with the server storing the attachment resource. The credentials required to access the managed attachment store could be different from the ones used to access the CalDAV server.
This specification only allows organizers of scheduled events to add managed attachments. Servers MUST prevent attendees of scheduled events from adding, updating or removing managed attachments. In addition, the server MUST prevent a calendar user from re-using a managed attachment (based on its managed-id value), unless that user is the one who originally created the managed attachment.
For POST requests that add or update attachment data, the server MAY issue a 307 (Temporary Redirect) or 308 (Permanent Redirect) response to require the client to re-issue the POST request using a different request-URI. As a result, clients SHOULD use the "100-continue" expectation defined in Section 5.1.1 of [RFC7231]. Using this mechanism ensures that, if a redirect does occur, the client does not needlessly send the attachment data.
Clients can expect servers to take a while to respond to POST requests that include large attachment bodies. Servers SHOULD use the "102 (Processing)" interim response defined in Section 10.1 of [RFC2518] to keep the client connection alive if the POST request will take significant time to complete.
Servers MAY automatically remove attachment data, for example to regain the storage taken by unused attachments, or as the result of a virus scanning. When doing so they SHOULD NOT modify calendar data referencing those attachments. Instead they SHOULD respond with "410 (Gone)" to any request on the removed attachment URI.
When a managed attachment is added, updated or removed from a calendar object resource, the server MUST ensure that a scheduling message is sent to update any attendees with the changes, as per [RFC6638].
When exporting calendar data from a CalDAV server supporting managed attachments, clients SHOULD remove all "MANAGED-ID" property parameters from "ATTACH" properties in the calendar data. Similarly when importing calendar data from another source, clients SHOULD remove any "MANAGED-ID" property parameters on "ATTACH" properties (failure to do so will likely result in the server removing those properties automatically).
sizeparam = "SIZE" "=" paramtext ; positive integers
ATTACH;SIZE=1234:https://attachments.example.com/abcd.txt
filenameparam = "FILENAME" "=" paramtext
ATTACH;FILENAME=agenda.html:https://attachments.example.c om/rt452S
managedidparam = "MANAGED-ID" "=" paramtext
ATTACH;MANAGED-ID=aUNhbGVuZGFy:https://attachments.example.c om/abcd.txt
The Cal-Managed-ID response header field provides the value of the MANAGED-ID parameter corresponding to a newly added ATTACH property.
ABNF:
Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext ; "paramtext" is defined in Section 3.1 of [RFC5545]
Example:
Cal-Managed-ID:aUNhbGVuZGFy
The Cal-Managed-ID header field MUST only be sent by an origin server in response to a successful POST request with an action set to attachment-add or attachment-update. It MUST only appear once in a response and MUST NOT appear in trailers.
The Cal-Managed-ID header field is end to end and MUST be forwarded by intermediaries. Intermediaries MUST NOT insert, delete, or modify a Cal-Managed-ID header field.
<!ELEMENT managed-attachments-server-URL (DAV:href?)>
<C:managed-attachments-server-URL xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:href>https://attachstore.example.com</D:href>
</C:managed-attachments-server-URL>
<!ELEMENT max-attachment-size (#PCDATA)> <!-- PCDATA value: a numeric value (positive decimal integer) -->
<C:max-attachment-size xmlns:C="urn:ietf:params:xml:ns:caldav"
>102400000</C:max-attachment-size>
<!ELEMENT max-attachments-per-resource (#PCDATA)> <!-- PCDATA value: a numeric value (positive decimal integer) -->
<C:max-attachments-per-resource
xmlns:C="urn:ietf:params:xml:ns:caldav"
>12</C:max-attachments-per-resource>
< RFC Editor: before publication please remove this section, the reference to [RFC7942], and any resulting "URIs" references sub-section. >
This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in [RFC7942]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist.
According to [RFC7942], "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".
The open source Calendar and Contacts Server project is a standards-compliant server implementing the CalDAV protocol. This production level implementation supports all of the requirements described in this document and successfully interoperates with the Apple Calendar, BusyCal, 2Do, and CalDAVTester client implementations described below. This implementation is freely distributable under the terms of the Apache License, Version 2.0.
The open source Cyrus Server project is a highly scalable enterprise mail system which also supports calendaring. This production level CalDAV implementation supports all of the requirements described in this document and successfully interoperates with the Apple Calendar and CalDAVTester client implementations described below. This implementation is freely distributable under a BSD style license from Computing Services at Carnegie Mellon University.
The Oracle Communications Calendar Server project is a standards-compliant, scalable, enterprise-ready calendaring solution. This production level CalDAV implementation supports all of the requirements described in this document and successfully interoperates with the Apple Calendar and CalDAVTester client implementations described below. This implementation is proprietary and available for a free trial and/or purchase from the vendor.
The widely used Apple Calendar client is a standards-compliant client implementing the CalDAV protocol. This production level implementation supports all the requirements described in this document and successfully interoperates with the Calendar and Contacts Server, Cyrus Server, and Oracle Communications Calendar Server implementations described above. This client implementation is proprietary and is distributed as part of Apple's desktop operating systems.
BusyCal is a standards-compliant calendar client for MacOS implementing the CalDAV protocol. This implementation supports all of the requirements described in this document and successfully interoperates with the Calendar and Contacts Server and Cyrus Server implementations described above. This implementation is proprietary and available for a free trial and/or purchase from the vendor.
CalDAVTester is an open source test and performance application designed to work with CalDAV servers and tests various aspects of their protocol handling as well as performance. This widely used implementation supports all of the requirements described in this document and successfully interoperates with the server implementations described above. This implementation is freely distributable under the terms of the Apache License, Version 2.0.
2Do is a standards-complient calendar client for iOS which uses the CalDAV standard for communication. This implementation supports all of the requirements described in this document and successfully interoperates with the Calendar and Contacts Server implementation described above. This implementation is proprietary and available for purchase from the vendor.
The security considerations in [RFC4791] and [RFC4918] apply to this extension. Additionally, servers need to be aware that a client could attack underlying storage by POSTing extremely large attachments and could attack processing time by uploading a recurring event with a large number of overrides and then repeatedly adding, updating, and deleting attachments.
Malicious content could be introduced into the calendar server by way of a managed attachment, and propagated to many end users via scheduling. Servers SHOULD check managed attachments for malicious or inappropriate content. Upon detecting of such content, servers SHOULD remove the attachment, following the rules described in Section 3.12.5.
This specification defines the following new iCalendar property parameters to be added to the registry defined in Section 8.2.3 of [RFC5545]:
| Property Parameter | Status | Reference |
|---|---|---|
| SIZE | Current | RFCXXXX, Section 4.1 |
| FILENAME | Current | RFCXXXX, Section 4.2 |
| MANAGED-ID | Current | RFCXXXX, Section 4.3 |
The message header fields below should be added to the Permanent Message Header Field Registry (see [RFC3864]).
Header field name: Cal-Managed-ID
Applicable protocol: http
Status: standard
Author/Change controller: IETF
Specification document(s): this specification (Section 5.1)
Related information: none
This specification came about via discussions at the Calendaring and Scheduling Consortium. Thanks in particular to Mike Douglass and Eric York.
| [RFC5023] | Gregorio, J. and B. de hOra, "The Atom Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023, October 2007. |
| [RFC5546] | Daboo, C., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, DOI 10.17487/RFC5546, December 2009. |
| [RFC7320] | Nottingham, M., "URI Design and Ownership", BCP 190, RFC 7320, DOI 10.17487/RFC7320, July 2014. |
| [RFC7942] | Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016. |
| [RFC8144] | Murchison, K., "Use of the Prefer Header Field in Web Distributed Authoring and Versioning (WebDAV)", RFC 8144, DOI 10.17487/RFC8144, April 2017. |
Changes in calext-04:
Changes in calext-03:
Changes in calext-02:
Changes in calext-01:
Changes in calext-00:
Changes in daboo-03:
Changes in daboo-02:
Changes in daboo-01:
In the following example, the organizer of a recurring meeting makes an unsuccessful attempt to add an agenda (HTML attachment) to the corresponding calendar resource with a conditional request. Note that the client includes both the Expect and Prefer header fields in the request, thereby preventing itself from needlessly sending the attachment data, and requesting that the current resource be returned in the failure response (see Section 3.2 of [RFC8144]).
>> Request <<
POST /events/65.ics?action=attachment-add HTTP/1.1 Host: cal.example.com Content-Type: text/html; charset="utf-8" Content-Disposition: attachment;filename=agenda.html Content-Length: xxxx If-Match: "abcdefg-000" Expect: 100-continue Prefer: return=representation
>> Final Response <<
HTTP/1.1 412 Precondition Failed Content-Type: text/calendar; charset="utf-8" Content-Length: yyyy Content-Location: https://cal.example.com/events/65.ics ETag: "123456789-000-000" BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Server//EN BEGIN:VTIMEZONE LAST-MODIFIED:20040110T032845Z TZID:America/Montreal 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 UID:20010712T182145Z-123401@example.com DTSTAMP:20120201T203412Z DTSTART;TZID=America/Montreal:20120206T100000 DURATION:PT1H RRULE:FREQ=WEEKLY SUMMARY:Planning Meeting ORGANIZER:mailto:cyrus@example.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl e.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam ple.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa mple.com END:VEVENT END:VCALENDAR
The organizer of a recurring meeting successfully adds an agenda (HTML attachment) to the corresponding calendar resource. Attendees of the meeting are granted read access to the newly created attachment resource. Their own copy of the meeting is updated to include the new ATTACH property pointing to the attachment resource and they are notified of the change via their scheduling inbox.
>> Request <<
POST /events/65.ics?action=attachment-add HTTP/1.1 Host: cal.example.com Content-Type: text/html; charset="utf-8" Content-Disposition: attachment;filename=agenda.html Content-Length: xxxx If-Match: "123456789-000-000" Expect: 100-continue Prefer: return=representation
>> Interim Response <<
HTTP/1.1 100 Continue
>> Request Body <<
<html>
<body>
<h1>Agenda</h1>
<p>As usual</p>
</body>
</html>
>> Final Response <<
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: yyyy Content-Location: https://cal.example.com/events/65.ics ETag: "123456789-000-111" Cal-Managed-ID: 97S BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Server//EN BEGIN:VTIMEZONE LAST-MODIFIED:20040110T032845Z TZID:America/Montreal 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 UID:20010712T182145Z-123401@example.com DTSTAMP:20120201T203412Z DTSTART;TZID=America/Montreal:20120206T100000 DURATION:PT1H RRULE:FREQ=WEEKLY SUMMARY:Planning Meeting ORGANIZER:mailto:cyrus@example.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl e.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam ple.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa mple.com ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R END:VEVENT END:VCALENDAR
The organizer has a more specific agenda for the 20th of February meeting. It is added to that particular instance of the meeting by specifying the rid parameter. Note that an overridden instance is created with the RECURRENCE-ID property value matching the value of the "rid" query parameter in the request. Also note that the server takes significant time to complete the request and notifies the client accordingly.
>> Request <<
POST /events/65.ics?action=attachment-add&rid=20120220T100000 HTTP/1.1 Host: cal.example.com Content-Type: text/html; charset="utf-8" Content-Disposition: attachment;filename=agenda0220.html Content-Length: xxxx If-Match: "123456789-000-111" Expect: 100-continue Prefer: return=representation
>> Interim Response <<
HTTP/1.1 100 Continue
>> Request Body <<
<html>
<body>
<h1>Agenda</h1>
<p>Something different, for a change</p>
</body>
</html>
>> Interim Response <<
HTTP/1.1 102 Processing
>> Final Response <<
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: yyyy Content-Location: https://cal.example.com/events/65.ics ETag: "123456789-000-222" Cal-Managed-ID: 33225 BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Server//EN BEGIN:VTIMEZONE LAST-MODIFIED:20040110T032845Z TZID:America/Montreal 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 UID:20010712T182145Z-123401@example.com DTSTAMP:20120201T203412Z DTSTART;TZID=America/Montreal:20120206T100000 DURATION:PT1H RRULE:FREQ=WEEKLY SUMMARY:Planning Meeting ORGANIZER:mailto:cyrus@example.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@exampl e.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exam ple.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@exa mple.com ATTACH;MANAGED-ID=97S;FMTTYPE=text/html;SIZE=xxxx; FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R END:VEVENT BEGIN:VEVENT UID:20010712T182145Z-123401@example.com RECURRENCE-ID;TZID=America/Montreal:20120220T100000 DTSTAMP:20120201T203412Z DTSTART;TZID=America/Montreal:20120220T100000 DURATION:PT1H SUMMARY:Planning Meeting ORGANIZER:mailto:cyrus@example.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:cyrus@example. com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:mailto:arnaudq@exampl e.com ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION:mailto:mike@examp le.com ATTACH;MANAGED-ID=33225;FMTTYPE=text/html;SIZE=xxxx; FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225 END:VEVENT END:VCALENDAR