CalDAV Managed Attachments

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 for which the attachment is required. One exception to this is the delete operation, which additionally allows for attachment removal by the client simply updating the calendar object resource and removing any "ATTACH" properties. The retrieve operation is accomplished by simply issuing an HTTP GET request targeting the attachment URI. 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 updating 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 query parameters on the POST request-URI.

Servers advertise support for this extension by including the token "calendar-managed-attachments" in the DAV response header to an OPTIONS request on a calendar home collection. Clients MUST check for the presence of that token before using any of the features defined by this specification.

An HTTP POST request is used to add, update, or remove attachments. The request-URI will contain various query parameters to specify the behavior.

The "action" query parameter is used to identify which behavior the client is requesting. This parameter MUST be present once on each POST request used to manage attachments. One of three values MUST be used: Indicates an operation that is adding an attachment to a calendar object resource. See for more details. Indicates an operation that is updating an existing attachment on a calendar object resource. See for more details. Indicates an operation that is removing an attachment on a calendar object resource. See for more details.

Example: http://calendar.example.com/events/1.ics?action=attachment-add

The "rid" query parameter is used to identify which recurrence instance is being targeted by the client for the attachment operation. The query parameter MUST contain one or more items, separated by commas (0x2C). The item values can be in one of two forms: The value "M" (case-insensitive) refers to the "master" recurrence instance, i.e., the component that does not include a "RECURRENCE-ID" property. This item MUST only be present once. A specific iCalendar instance is targeted by using its "RECURRENCE-ID" value as the query parameter value. If multiple items of this form are used, they MUST be unique values. If the "rid" query parameter is not present, all recurrence instances in the calendar object resource are targeted.

Example: http://calendar.example.com/events/1.ics? action=attachment-add&rid=M,20111022T160000Z

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

Example: http://calendar.example.com/events/1.ics? action=attachment-update&id=aUNhbGVuZGFy

To add an attachment to an existing calendar object resource, the following occurs: The client issues a POST request targeted at the calendar object resource. The request-URI will include an "action" query parameter with the value "attachment-add" (see ). If all recurrence instances are having an attachment added, the "rid" query parameter is not present in the request-URI. If one or more specific recurrence instances are targeted, then the request-URI will include a "rid" query parameter containing the list of instances (see ). The body of the request contains the data for the attachment. The client MUST include a valid Content-Type HTTP header describing the media type of the attachment (as required by HTTP). The client SHOULD include a Content-Disposition HTTP header with a "type" of "attachment", and a "filename" parameter that indicates the name of the attachment. When the server receives the POST request it does the following: Validates that any recurrence instances referred to via the "rid" query parameter are valid for the calendar object resource being targeted. Stores the supplied attachment data into a resource and generates an appropriate URI for clients to access the resource. For each affected recurrence instance in the calendar object resource targeted by the request, the server adds an "ATTACH" property, whose value is the URI of the stored attachment. The "ATTACH" property MUST contain a "MANAGED-ID" property parameter whose value is a unique identifier (within the context of the server as a whole). The "ATTACH" property SHOULD contain an "FMTTYPE" property parameter whose value matches the Content-Type header value from the request. The "ATTACH" property SHOULD include a "SIZE" property parameter whose value represents the size in octets of the attachment. Note that if a specified recurrence instance does not have a matching component in the calendar object resource, then the server MUST modify the calendar object resource to include the overridden component with the appropriate "RECURRENCE-ID" property included. Upon successful creation of the attachment resource and modification of the targeted calendar object resource, the server MUST return a 200 HTTP status response and include a Location HTTP header containing the URI of the stored attachment. The client can use the Location header value to correlate the attachment with "ATTACH" properties added to the calendar object resource. It is expected that the client will immediately reload the calendar object resource to refresh any local cache.

To change the data of an existing managed attachment in a calendar object resource, the following occurs: The client issues a POST request targeted at the calendar object resource. The request-URI will include an "action" query parameter with the value "attachment-update" (see ). If all recurrence instances are having an attachment updated, the "rid" query parameter is not present in the request-URI. If one or more specific recurrence instances are targeted, then the request-URI will include a "rid" query parameter containing the list of instances (see ). The request-URI will include an "id" query parameter with the value matching that of the "MANAGED-ID" property parameter for the "ATTACH" property being updated (see ). The body of the request contains the updated data for the attachment. The client MUST include a valid Content-Type header describing the media type of the attachment (as required by HTTP). The client SHOULD include a Content-Disposition header with a "type" of "attachment", and a "filename" parameter that indicates the name of the attachment. When the server receives the POST request it does the following: Validates that any recurrence instances referred to via the "rid" query parameter are valid for the calendar object resource being targeted. Validates that the "id" query parameter is valid for the calendar object resource and specific instances being targeted. Stores the supplied attachment data into a resource and generates an appropriate URI for clients to access the resource. The URI for the updated attachment data MUST be different from the one for the attachment being updated. This allows clients to use the URI value as a "change token". For each affected recurrence instance in the calendar object resource targeted by the request, the server updates the "ATTACH" property, whose value is the URI of the updated attachment. The "MANAGED-ID" property parameter value MUST remain the same as it was for the attachment being updated. The "ATTACH" property SHOULD contain an "FMTTYPE" property parameter whose value matches the Content-Type header value from the request - this could differ from the original value if the media type of the updated attachment is different. The "ATTACH" property SHOULD include a "SIZE" property parameter whose value represents the size in octets of the updated attachment. Note that if a specified recurrence instance does not have a matching component in the calendar object resource, then the server MUST modify the calendar object resource to include the overridden component with the appropriate "RECURRENCE-ID" property included. Upon successful update of the attachment resource and modification of the targeted calendar object resource, the server MUST return a 200 HTTP status response and include a Location header containing the URI of the updated attachment. It is expected that the client will immediately reload the calendar object resource to refresh any local cache.

To remove an attachment on an existing calendar object resource, the following occurs: The client issues a POST request targeted at the calendar object resource. The request-URI will include an "action" query parameter with the value "attachment-remove" (see ). If all recurrence instances are having an attachment removed, the "rid" query parameter is not present in the request-URI. If one or more specific recurrence instances are targeted, then the request-URI will include a "rid" query parameter containing the list of instances (see ). The request-URI will include an "id" query parameter with the value matching that of the "MANAGED-ID" property parameter for the "ATTACH" property being removed (see ). The body of the request will be empty. When the server receives the POST request it does the following: Validates that any recurrence instances referred to via the "rid" query parameter are valid for the calendar object resource being targeted. Validates that the "id" query parameter is valid for the calendar object resource and specific instances being targeted. For each affected recurrence instance in the calendar object resource targeted by the request, the server removes the matching "ATTACH" property. Note that if a specified recurrence instance does not have a matching component in the calendar object resource, then the server MUST modify the calendar object resource to include the overridden component with the appropriate "RECURRENCE-ID" property included, and the matching "ATTACH" property removed. Upon successful removal of the attachment resource and modification of the targeted calendar object resource, the server MUST return a 200 HTTP status response. It is expected that the client will immediately reload the calendar object resource to refresh any local cache.

Clients can make use of existing managed attachments by adding the corresponding "ATTACH" property to calendar object resources (subject to the restrictions described in ).

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

Clients can remove attachments by simply re-writing the calendar object resource data to remove the appropriate "ATTACH" properties.

Clients retrieve attachments by simply issuing an HTTP GET request using the value of the corresponding "ATTACH" property as the request-URI.

TODO: error codes for each request.

TODO: talk about authentication for attachment URIs, access limited to attendees only, or token based, only organizer able to re-use "ATTACH" properties.

For POST requests that add or update attachment data, the server MAY issue an HTTP redirect to require the client to re-issue the POST request using a different request-URI. As a result, it is always best for clients to use the "100 Continue" behavior define in Section 8.2.3 of . That ensures that, if a redirect does occur, the client does not needless send the attachment data. When servers do redirect clients to a different request-URI, they SHOULD ensure that the authentication/authorization for the redirected URI falls within the same domain as that of the original URI, so that the client can re-use credentials without having to prompt the user.

TODO: describe reference counting of managed attachments - server can remove actual attachment data once there are no more references to the attachment URI. Also, servers can purge old attachment data - return a 404 or 410.

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 .

TODO: how do we do this? Organizer adds a property to calendar data to say attendees can add attachments, but how does scheduling happen?