Internet Engineering Task Force (IETF) C. Daboo Request for Comments: 8607 Apple Category: Informational A. Quillaud ISSN: 2070-1721 Oracle K. Murchison, Ed. FastMail June 2019
Internet Engineering Task Force (IETF) C. Daboo Request for Comments: 8607 Apple Category: Informational A. Quillaud ISSN: 2070-1721 Oracle K. Murchison, Ed. FastMail June 2019
Calendaring Extensions to WebDAV (CalDAV): Managed Attachments
WebDAV(CalDAV)日历扩展:托管附件
Abstract
摘要
This specification adds an extension to the Calendaring Extensions to WebDAV (CalDAV) to allow attachments associated with iCalendar data to be stored and managed on the server.
本规范为WebDAV日历扩展(CalDAV)添加了一个扩展,以允许在服务器上存储和管理与iCalendar数据关联的附件。
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.
本规范记录了由多个供应商部署的现有代码。它是作为一个信息规范而不是标准轨道发布的,因为它不符合HTTP的多个当前最佳实践。
Status of This Memo
关于下段备忘
This document is not an Internet Standards Track specification; it is published for informational purposes.
本文件不是互联网标准跟踪规范;它是为了提供信息而发布的。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are candidates for any level of Internet Standard; see Section 2 of RFC 7841.
本文件是互联网工程任务组(IETF)的产品。它代表了IETF社区的共识。它已经接受了公众审查,并已被互联网工程指导小组(IESG)批准出版。并非IESG批准的所有文件都适用于任何级别的互联网标准;见RFC 7841第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8607.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息,请访问https://www.rfc-editor.org/info/rfc8607.
Copyright Notice
版权公告
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
版权(c)2019 IETF信托基金和被确定为文件作者的人员。版权所有。
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.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(https://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件,因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本,并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Rationale for Informational Status . . . . . . . . . . . 4 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Discovering Support for Managed Attachments . . . . . . . 5 3.3. POST Request for Managing Attachments . . . . . . . . . . 6 3.3.1. action Query Parameter . . . . . . . . . . . . . . . 6 3.3.2. rid Query Parameter . . . . . . . . . . . . . . . . . 6 3.3.3. managed-id Query Parameter . . . . . . . . . . . . . 7 3.4. Adding Attachments . . . . . . . . . . . . . . . . . . . 7 3.5. Updating Attachments . . . . . . . . . . . . . . . . . . 10 3.6. Removing Attachments via POST . . . . . . . . . . . . . . 13 3.7. Adding Existing Managed Attachments via PUT . . . . . . . 15 3.8. Updating Attachments via PUT . . . . . . . . . . . . . . 15 3.9. Removing Attachments via PUT . . . . . . . . . . . . . . 15 3.10. Retrieving Attachments . . . . . . . . . . . . . . . . . 15 3.11. Error Handling . . . . . . . . . . . . . . . . . . . . . 16 3.12. Additional Considerations . . . . . . . . . . . . . . . . 17 3.12.1. Quotas . . . . . . . . . . . . . . . . . . . . . . . 17 3.12.2. Access Control . . . . . . . . . . . . . . . . . . . 17 3.12.3. Redirects . . . . . . . . . . . . . . . . . . . . . 18 3.12.4. Processing Time . . . . . . . . . . . . . . . . . . 18 3.12.5. Automatic Cleanup by Servers . . . . . . . . . . . . 18 3.12.6. Sending Scheduling Messages with Attachments . . . . 18 3.12.7. Migrating Calendar Data . . . . . . . . . . . . . . 18 4. Modifications to iCalendar Syntax . . . . . . . . . . . . . . 19 4.1. SIZE Property Parameter . . . . . . . . . . . . . . . . . 19 4.2. FILENAME Property Parameter . . . . . . . . . . . . . . . 19 4.3. MANAGED-ID Property Parameter . . . . . . . . . . . . . . 20 5. Additional Message Header Fields . . . . . . . . . . . . . . 20
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Rationale for Informational Status . . . . . . . . . . . 4 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Requirements . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Discovering Support for Managed Attachments . . . . . . . 5 3.3. POST Request for Managing Attachments . . . . . . . . . . 6 3.3.1. action Query Parameter . . . . . . . . . . . . . . . 6 3.3.2. rid Query Parameter . . . . . . . . . . . . . . . . . 6 3.3.3. managed-id Query Parameter . . . . . . . . . . . . . 7 3.4. Adding Attachments . . . . . . . . . . . . . . . . . . . 7 3.5. Updating Attachments . . . . . . . . . . . . . . . . . . 10 3.6. Removing Attachments via POST . . . . . . . . . . . . . . 13 3.7. Adding Existing Managed Attachments via PUT . . . . . . . 15 3.8. Updating Attachments via PUT . . . . . . . . . . . . . . 15 3.9. Removing Attachments via PUT . . . . . . . . . . . . . . 15 3.10. Retrieving Attachments . . . . . . . . . . . . . . . . . 15 3.11. Error Handling . . . . . . . . . . . . . . . . . . . . . 16 3.12. Additional Considerations . . . . . . . . . . . . . . . . 17 3.12.1. Quotas . . . . . . . . . . . . . . . . . . . . . . . 17 3.12.2. Access Control . . . . . . . . . . . . . . . . . . . 17 3.12.3. Redirects . . . . . . . . . . . . . . . . . . . . . 18 3.12.4. Processing Time . . . . . . . . . . . . . . . . . . 18 3.12.5. Automatic Cleanup by Servers . . . . . . . . . . . . 18 3.12.6. Sending Scheduling Messages with Attachments . . . . 18 3.12.7. Migrating Calendar Data . . . . . . . . . . . . . . 18 4. Modifications to iCalendar Syntax . . . . . . . . . . . . . . 19 4.1. SIZE Property Parameter . . . . . . . . . . . . . . . . . 19 4.2. FILENAME Property Parameter . . . . . . . . . . . . . . . 19 4.3. MANAGED-ID Property Parameter . . . . . . . . . . . . . . 20 5. Additional Message Header Fields . . . . . . . . . . . . . . 20
5.1. Cal-Managed-ID Response Header Field . . . . . . . . . . 20 6. Additional WebDAV Properties . . . . . . . . . . . . . . . . 21 6.1. CALDAV:managed-attachments-server-URL Property . . . . . 21 6.2. CALDAV:max-attachment-size Property . . . . . . . . . . . 22 6.3. CALDAV:max-attachments-per-resource Property . . . . . . 23 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 8.1. Parameter Registrations . . . . . . . . . . . . . . . . . 24 8.2. Message Header Field Registrations . . . . . . . . . . . 25 8.2.1. Cal-Managed-ID . . . . . . . . . . . . . . . . . . . 25 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 9.1. Normative References . . . . . . . . . . . . . . . . . . 25 9.2. Informative References . . . . . . . . . . . . . . . . . 27 Appendix A. Example Involving Recurring Events . . . . . . . . . 28 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34
5.1. Cal-Managed-ID Response Header Field . . . . . . . . . . 20 6. Additional WebDAV Properties . . . . . . . . . . . . . . . . 21 6.1. CALDAV:managed-attachments-server-URL Property . . . . . 21 6.2. CALDAV:max-attachment-size Property . . . . . . . . . . . 22 6.3. CALDAV:max-attachments-per-resource Property . . . . . . 23 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 8.1. Parameter Registrations . . . . . . . . . . . . . . . . . 24 8.2. Message Header Field Registrations . . . . . . . . . . . 25 8.2.1. Cal-Managed-ID . . . . . . . . . . . . . . . . . . . 25 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 9.1. Normative References . . . . . . . . . . . . . . . . . . 25 9.2. Informative References . . . . . . . . . . . . . . . . . 27 Appendix A. Example Involving Recurring Events . . . . . . . . . 28 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34
The iCalendar [RFC5545] data format is used to represent calendar data and is used with iCalendar Transport-independent Interoperability Protocol (iTIP) [RFC5546] to handle scheduling operations between calendar users.
iCalendar[RFC5545]数据格式用于表示日历数据,并与iCalendar传输独立互操作性协议(iTIP)[RFC5546]一起用于处理日历用户之间的调度操作。
[RFC4791] defines the Calendaring Extensions to WebDAV (CalDAV), based on HTTP [RFC7230], for accessing calendar data stored on a server.
[RFC4791]基于HTTP[RFC7230]定义WebDAV(CalDAV)的日历扩展,用于访问存储在服务器上的日历数据。
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.
日历用户通常希望在日历数据事件或任务中包含附件(例如,演示文稿或会议议程的副本)。iCalendar提供一个“ATTACH”属性,其值为内联Base64编码的附件数据或指定附件数据位置的URL。
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 made, 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.
在CalDAV中使用内联附件数据并不理想,因为每次更改日历数据时都需要将数据上载到服务器,即使是诸如更改摘要之类的小更改。虽然客户可以选择使用URL值,但问题在于客户在何处以及如何找到合适的URL以供使用,以及如何确保只有活动或任务中列出的与会者才能访问该URL。
This specification solves this problem by having the client send the attachment to the server, separately from the iCalendar data, and having the server add appropriate "ATTACH" properties in the iCalendar data as well as manage 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.
本规范通过让客户端将附件与iCalendar数据分开发送到服务器,并让服务器在iCalendar数据中添加适当的“ATTACH”属性以及管理访问权限来解决此问题。服务器还可以向客户端提供有关iCalendar数据中每个附件的附加信息,例如大小和标识符。
Although this extension to CalDAV has wide deployment, its design does not comply with some of the best current practices of HTTP, namely:
尽管CalDAV的此扩展具有广泛的部署,但其设计不符合HTTP的某些最佳当前实践,即:
o All operations on attachments are modeled as HTTP POST operations, where the actual type of operation is specified using a query parameter instead of using separate HTTP POST, PUT, and DELETE methods where appropriate.
o 附件上的所有操作都建模为HTTP POST操作,其中实际操作类型是使用查询参数指定的,而不是在适当的情况下使用单独的HTTP POST、PUT和DELETE方法。
o Specific query strings are hardwired into the protocol in violation of Section 2.4 of [RFC7320].
o 特定查询字符串硬连接到协议中,违反了[RFC7320]第2.4节。
Additionally, this extension misuses the Content-Disposition header field [RFC6266] 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]).
此外,该扩展错误地使用内容处理头字段[RFC6266]作为请求头字段来传递附件的文件名,而不是使用适合该目的的现有请求头字段,如“Slug”(请参阅[RFC5023]第9.7节)。
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.
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“建议”、“不建议”、“可”和“可选”在所有大写字母出现时(如图所示)应按照BCP 14[RFC2119][RFC8174]所述进行解释。
The notation used in this memo is the ABNF notation of [RFC5234] as used by iCalendar [RFC5545]. Any syntax elements shown below that are not explicitly defined in this specification come from iCalendar [RFC5545].
本备忘录中使用的符号是iCalendar[RFC5545]使用的[RFC5234]的ABNF符号。本规范中未明确定义的以下语法元素来自iCalendar[RFC5545]。
There are four main operations a client needs to perform 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
客户端需要对日历数据的附件执行四个主要操作:添加、更新、删除和检索。前三个操作由客户端对附件关联的日历对象资源发出HTTP POST请求并指定适当的“操作”查询参数来执行(请参见第3.3节)。如果是拆下
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).
操作时,客户端也可以直接更新日历对象资源并删除相关的“附加”属性(请参见第3.9节)。检索操作通过简单地发出HTTP GET请求来完成,该请求的目标是日历资源的“ATTACH”属性指定的附件URI(请参见第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.
当涉及重复时,存储在CalDAV日历对象资源中的iCalendar数据可以包含多个组件。在这种情况下,客户端需要能够在添加或删除附件时针对特定的重复实例或多个实例。因此,POST请求需要为客户端提供一种方法,以指定附件操作应以哪些重复实例为目标。这是通过对POST请求URI使用额外的查询参数来实现的。
A server that supports the features described in this specification is REQUIRED to support the CalDAV "calendar-access" [RFC4791] features.
支持本规范所述功能的服务器需要支持CalDAV“日历访问”[RFC4791]功能。
In addition, such a server SHOULD support the "return=representation" Prefer header field [RFC7240] 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.
此外,这样的服务器应该支持“return=representation”preference header field[RFC7240]首选项,通过在响应中返回该日历资源的新表示(包括其新的ETag header字段值),成功执行针对现有日历对象资源的HTTP PUT和POST请求。
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.
支持本规范所述功能的服务器必须在DAV响应头字段(如[RFC4918]第10.1节所定义)中包含“日历托管附件”,作为日历主集合上选项请求的令牌。
A server might choose not to support the storing of 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.
服务器可能选择不支持按每个重复实例存储托管附件(即,它们只能作为一个整体添加到所有实例)。如果是这种情况,服务器还必须在日历主集合上的选项请求的DAV响应标头字段中包含“日历管理的附件无重复”作为令牌。当该字段存在时,客户端不得尝试任何针对特定重复实例的托管附件操作。
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.
HTTP POST请求用于添加、更新或删除附件。这些请求须符合第3.11节所列的先决条件。请求URI将包含用于指定行为的各种查询参数。
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:
“action”查询参数用于标识客户端请求的附件操作。此参数必须在用于管理附件的每个POST请求中出现一次。必须使用以下三个值之一:
attachment-add: Indicates an operation that is adding an attachment to a calendar object resource. See Section 3.4 for more details.
附件添加:表示向日历对象资源添加附件的操作。详见第3.4节。
attachment-update: Indicates an operation that is updating an existing attachment on a calendar object resource. See Section 3.5 for more details.
附件更新:表示更新日历对象资源上现有附件的操作。详见第3.5节。
attachment-remove: Indicates an operation that is removing an attachment from a calendar object resource. See Section 3.6 for more details.
附件删除:表示从日历对象资源中删除附件的操作。详见第3.6节。
Example:
例子:
https://calendar.example.com/events/1.ics?action=attachment-add
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 (denoted in ASCII as "0x2C"). The item values can be in one of two forms:
“rid”查询参数用于标识客户端针对哪些重复实例执行附件操作。此查询参数必须包含一个或多个项目,以逗号分隔(在ASCII中表示为“0x2C”)。项目值可以采用以下两种形式之一:
Master instance: 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 be present only once.
主实例:值“M”(不区分大小写)指的是“主”重复实例,即不包含“recursion-ID”属性的组件。此项目只能出现一次。
Specific instance: A specific iCalendar instance is targeted by using its "RECURRENCE-ID" value as the item value. That value MUST correspond to the "RECURRENCE-ID" value as stored in the calendar object resource (i.e., without any conversion to UTC). If multiple items of this form are used, they MUST be unique values. For example, to target a recurrence defined by property
特定实例:通过使用特定iCalendar实例的“RECURRENCE-ID”值作为项值,将其作为目标。该值必须与存储在日历对象资源中的“RECURRENCE-ID”值相对应(即,不转换为UTC)。如果使用此表单的多个项目,则它们必须是唯一的值。例如,以属性定义的重复为目标
RECURRENCE-ID;TZID=America/Montreal:20111022T160000, the query parameter rid=20111022T160000 would be used.
复发性ID;TZID=America/Montreal:20111022T160000,将使用查询参数rid=20111022T160000。
If the "rid" query parameter is not present, all recurrence instances in the calendar object resource are targeted.
如果“rid”查询参数不存在,则日历对象资源中的所有重复实例都是目标。
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.2).
“rid”查询参数不得出现在更新操作的情况下,或者如果服务器选择不支持每个重复实例管理的附件(请参阅第3.2节)。
Example (targeting the master instance and a specific overridden instance):
示例(针对主实例和特定重写实例):
https://calendar.example.com/events/1.ics? action=attachment-add&rid=M,20111022T160000
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" (Section 4.3) property parameter value on the "ATTACH" property in the calendar object resource instance(s) targeted by the request.
“managed id”查询参数用于标识正在更新或删除的“ATTACH”属性。此查询参数的值必须与请求所针对的日历对象资源实例中“ATTACH”属性上的“MANAGED-ID”(第4.3节)属性参数值匹配。
The "managed-id" query parameter MUST NOT be present in the case of an add operation.
对于添加操作,“托管id”查询参数不得存在。
Example:
例子:
https://calendar.example.com/events/1.ics? action=attachment-update&managed-id=aUNhbGVuZGFy
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 needs to occur:
要向现有日历对象资源添加附件,需要执行以下操作:
1. The client issues a POST request targeted at the calendar object resource structured as follows:
1. 客户端针对日历对象资源发出POST请求,其结构如下:
A. The Request-URI will include an "action" query parameter with the value "attachment-add" (see Section 3.3.1).
A.请求URI将包括一个值为“附件添加”的“操作”查询参数(见第3.3.1节)。
B. 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 Section 3.3.2).
B.如果所有重复实例都添加了附件,则请求URI中不存在“rid”查询参数。如果目标是一个或多个特定的重复实例,那么请求URI将包括一个“rid”查询参数,其中包含实例列表(请参见第3.3.2节)。
C. The body of the request contains the data for the attachment.
C.请求正文包含附件的数据。
D. The client MUST include a valid Content-Type header field describing the media type of the attachment (as required by HTTP).
D.客户端必须包含一个有效的内容类型头字段,描述附件的媒体类型(根据HTTP的要求)。
E. The client SHOULD include a Content-Disposition header field [RFC6266] with a "type" parameter set to "attachment", and a "filename" parameter that indicates the name of the attachment. Note that the use of Content-Disposition as a request header field is nonstandard and specific to this protocol.
E.客户端应包括一个内容处置标题字段[RFC6266],其中“类型”参数设置为“附件”,以及一个指示附件名称的“文件名”参数。请注意,将内容处置用作请求头字段是非标准的,并且特定于此协议。
F. The client MAY include a Prefer header field [RFC7240] with the "return=representation" preference to request that the modified calendar object resource be returned as the body of a successful response to the POST request.
F.客户机可能会包括一个带有“return=representation”首选项的首选标头字段[RFC7240],以请求将修改后的日历对象资源作为POST请求的成功响应的主体返回。
2. When the server receives the POST request, it does the following:
2. 服务器收到POST请求时,将执行以下操作:
A. Validates that any recurrence instances referred to via the "rid" query parameter are valid for the calendar object resource being targeted.
A.验证通过“rid”查询参数引用的任何重复实例是否对目标日历对象资源有效。
B. Stores the supplied attachment data into a resource and generates an appropriate URI for clients to access the resource.
B.将提供的附件数据存储到资源中,并为客户端访问资源生成适当的URI。
C. For each affected recurrence instance in the calendar object resource targeted by the request, 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 field value from the request. The "ATTACH" property SHOULD contain a "FILENAME" property parameter whose value matches the value of the Content-Disposition header field "filename" parameter value from the request, taking into account the restrictions expressed in Section 4.2. The "ATTACH" property SHOULD include a "SIZE" property parameter whose value represents the size in octets of the attachment. 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 an overridden component with the appropriate "RECURRENCE-ID" property.
C.对于请求所针对的日历对象资源中每个受影响的重复实例,添加一个“ATTACH”属性,其值为存储的附件的URI。“ATTACH”属性必须包含一个“MANAGED-ID”属性参数,其值是唯一标识符(在整个服务器的上下文中)。“ATTACH”属性应包含一个“FMTTYPE”属性参数,其值与请求的内容类型标头字段值匹配。“ATTACH”属性应包含一个“FILENAME”属性参数,该参数的值与请求中内容处置标题字段“FILENAME”参数值的值相匹配,同时考虑到第4.2节中所述的限制。“ATTACH”属性应包括一个“SIZE”属性参数,其值表示附件的大小(以八位字节为单位)。如果指定的重复实例在日历对象资源中没有匹配的组件,则服务器必须修改日历对象资源,以包含具有适当“recurrence-ID”属性的重写组件。
D. Upon successful creation of the attachment resource, and modification of the targeted calendar object resource, it MUST return an appropriate HTTP success status response and include a "Cal-Managed-ID" header field containing the "MANAGED-ID" property parameter value of the newly created "ATTACH" property. The client can use the "Cal-Managed-ID" header field value to correlate the attachment with "ATTACH" properties added to the calendar object resource. If the client included a Prefer header field with the "return=representation" preference in the request, the server SHOULD return the modified calendar object resource as the body of the response. Otherwise, the server can expect that the client will reload the calendar object resource with a subsequent GET request to refresh any local cache.
D.成功创建附件资源并修改目标日历对象资源后,它必须返回适当的HTTP成功状态响应,并包含“Cal Managed ID”标题字段,其中包含新创建的“ATTACH”属性的“Managed-ID”属性参数值。客户端可以使用“Cal Managed ID”标题字段值将附件与添加到日历对象资源的“ATTACH”属性关联起来。如果客户端在请求中包含带有“return=representation”首选项的preference头字段,则服务器应将修改后的日历对象资源作为响应主体返回。否则,服务器可以预期客户端将使用后续GET请求重新加载日历对象资源,以刷新任何本地缓存。
In the following example, the client adds a new attachment to a nonrecurring event and asks the server (via the Prefer header field [RFC7240]) to return the modified version of that event in the response.
在下面的示例中,客户机向非重复事件添加新附件,并要求服务器(通过首选标头字段[RFC7240])在响应中返回该事件的修改版本。
>> Request <<
>> 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: 59 Prefer: return=representation
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: 59 Prefer: return=representation
<html> <body> <h1>Agenda</h1> </body> </html>
<html> <body> <h1>Agenda</h1> </body> </html>
>> Response <<
>> Response <<
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: 371 Content-Location: https://cal.example.com/events/64.ics ETag: "123456789-000-111" Cal-Managed-ID: 97S
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: 371 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=59; FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R END:VEVENT END:VCALENDAR
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=59; 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" property 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" property parameter value.
更新附件时,服务器必须更改关联的“MANAGED-ID”属性参数,并可能更改“ATTACH”属性值。使用这种方法,客户机可以通过查找对“ATTACH”属性值或“MANAGED-ID”属性参数值的更改来确定其他客户机何时更新了附件。
To change the data of an existing managed attachment in a calendar object resource, the following needs to occur:
要更改日历对象资源中现有托管附件的数据,需要执行以下操作:
1. The client issues a POST request targeted at the calendar object resource structured as follows:
1. 客户端针对日历对象资源发出POST请求,其结构如下:
A. The Request-URI will include an "action" query parameter with the value "attachment-update" (see Section 3.3.1).
A.请求URI将包括一个值为“附件更新”的“操作”查询参数(见第3.3.1节)。
B. The Request-URI will include a "managed-id" query parameter with the value matching that of the "MANAGED-ID" property parameter for the "ATTACH" property being updated (see Section 3.3.3).
B.请求URI将包括一个“托管id”查询参数,该参数的值与正在更新的“附加”属性的“托管id”属性参数的值相匹配(见第3.3.3节)。
C. The body of the request contains the updated data for the attachment.
C.请求正文包含附件的更新数据。
D. The client MUST include a valid Content-Type header field describing the media type of the attachment (as required by HTTP).
D.客户端必须包含一个有效的内容类型头字段,描述附件的媒体类型(根据HTTP的要求)。
E. The client SHOULD include a Content-Disposition header field [RFC6266] with a "type" parameter set to "attachment", and a "filename" parameter that indicates the name of the attachment.
E.客户端应包括一个内容处置标题字段[RFC6266],其中“类型”参数设置为“附件”,以及一个指示附件名称的“文件名”参数。
F. The client MAY include a Prefer header field [RFC7240] with the "return=representation" preference to request that the modified calendar object resource be returned as the body of a successful response to the POST request.
F.客户机可能会包括一个带有“return=representation”首选项的首选标头字段[RFC7240],以请求将修改后的日历对象资源作为POST请求的成功响应的主体返回。
2. When the server receives the POST request, it does the following:
2. 服务器收到POST请求时,将执行以下操作:
A. Validates that the "managed-id" query parameter is valid for the calendar object resource.
A.验证“托管id”查询参数是否对日历对象资源有效。
B. Updates the content of the attachment resource corresponding to that "managed-id" value with the supplied attachment data.
B.使用提供的附件数据更新与该“托管id”值对应的附件资源的内容。
C. For each affected recurrence instance in the calendar object resource targeted by the request, updates the "ATTACH" property whose "MANAGED-ID" property parameter value matches the "managed-id" query parameter. The "MANAGED-ID" property parameter value is changed to allow other clients to detect the update, and the property value (attachment URI) might also be changed. The "ATTACH" property SHOULD contain a "FMTTYPE" property parameter whose value matches the Content-Type header field 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 contain a "FILENAME" property parameter whose value matches the Content-Disposition header field "filename" parameter value from the request, taking into account the restrictions expressed in Section 4.2. The "ATTACH" property SHOULD include a "SIZE" property parameter whose value represents the size in octets of the updated attachment.
C.对于请求所针对的日历对象资源中每个受影响的重复实例,更新其“MANAGED-ID”属性参数值与“MANAGED-ID”查询参数匹配的“ATTACH”属性。更改“MANAGED-ID”属性参数值以允许其他客户端检测更新,并且还可能更改属性值(附件URI)。“ATTACH”属性应包含一个“FMTTYPE”属性参数,其值与请求的内容类型标头字段值匹配;如果更新附件的介质类型不同,则该值可能与原始值不同。“ATTACH”属性应包含一个“FILENAME”属性参数,其值与请求中的内容处置标题字段“FILENAME”参数值相匹配,并考虑到第4.2节中所述的限制。“ATTACH”属性应包括一个“SIZE”属性参数,其值表示更新附件的大小(以八位字节为单位)。
D. Upon successful update of the attachment resource, and modification of the targeted calendar object resource, it MUST return an appropriate HTTP success status response and include a "Cal-Managed-ID" header field containing the new value of the "MANAGED-ID" property parameter. The client can use the "Cal-Managed-ID" header field value to correlate the attachment with "ATTACH" properties added to the calendar
D.成功更新附件资源并修改目标日历对象资源后,它必须返回适当的HTTP成功状态响应,并包含一个“Cal Managed ID”标题字段,其中包含“Managed-ID”属性参数的新值。客户端可以使用“Cal Managed ID”标题字段值将附件与添加到日历中的“ATTACH”属性关联起来
object resource. If the client included a Prefer header field with the "return=representation" preference in the request, the server SHOULD return the modified calendar object resource as the body of the response. Otherwise, the server can expect that the client will reload the calendar object resource with a subsequent GET request to refresh any local cache.
对象资源。如果客户端在请求中包含带有“return=representation”首选项的preference头字段,则服务器应将修改后的日历对象资源作为响应主体返回。否则,服务器可以预期客户端将使用后续GET请求重新加载日历对象资源,以刷新任何本地缓存。
The update operation does not take a "rid" query 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 that duplicates the existing one (see Section 3.7).
更新操作不接受“rid”查询参数,也不在目标日历对象资源中添加或删除任何“ATTACH”属性。要将现有附件链接到新实例,客户端只需对日历对象资源执行PUT操作,添加一个与现有附件重复的“ATTACH”属性(请参见第3.7节)。
In the following example, the client updates an existing attachment and asks the server (via the Prefer header field [RFC7240]) to return the updated version of that event in the response.
在以下示例中,客户端更新现有附件,并要求服务器(通过首选标头字段[RFC7240])在响应中返回该事件的更新版本。
>> Request <<
>> 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: 96 Prefer: return=representation
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: 96 Prefer: return=representation
<html> <body> <h1>Agenda</h1> <p>Discuss attachment draft</p> </body> </html>
<html> <body> <h1>Agenda</h1> <p>Discuss attachment draft</p> </body> </html>
>> Response <<
>> Response <<
HTTP/1.1 200 OK Content-Type: text/calendar; charset="utf-8" Content-Length: 371 Content-Location: https://cal.example.com/events/64.ics Cal-Managed-ID: 98S ETag: "123456789-000-222"
HTTP/1.1 200 OK Content-Type: text/calendar; charset="utf-8" Content-Length: 371 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=96; FILENAME=agenda.html:https://cal.example.com/attach/64/34X22R END:VEVENT END:VCALENDAR
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=96; 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 needs to occur:
要从日历对象中删除现有附件,需要执行以下操作:
1. The client issues a POST request targeted at the calendar object resource structured as follows:
1. 客户端针对日历对象资源发出POST请求,其结构如下:
A. The Request-URI will include an "action" query parameter with the value "attachment-remove" (see Section 3.3.1).
A.请求URI将包括一个值为“附件移除”的“操作”查询参数(见第3.3.1节)。
B. 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 Section 3.3.2).
B.如果所有重复实例都删除了附件,则请求URI中不存在“rid”查询参数。如果目标是一个或多个特定的重复实例,那么请求URI将包括一个“rid”查询参数,其中包含实例列表(请参见第3.3.2节)。
C. The Request-URI will include a "managed-id" query parameter with the value matching that of the "MANAGED-ID" property parameter for the "ATTACH" property being removed (see Section 3.3.3).
C.请求URI将包括一个“托管id”查询参数,该参数的值与被删除的“附加”属性的“托管id”属性参数的值相匹配(见第3.3.3节)。
D. The body of the request will be empty.
D.请求正文将为空。
E. The client MAY include a Prefer header field [RFC7240] with the "return=representation" preference to request that the modified calendar object resource be returned as the body of a successful response to the POST request.
E.客户机可以包括带有“return=representation”首选项的preference header字段[RFC7240],以请求将修改后的日历对象资源作为对POST请求的成功响应的主体返回。
2. When the server receives the POST request, it does the following:
2. 服务器收到POST请求时,将执行以下操作:
A. Validates that any recurrence instances referred to via the "rid" query parameter are valid for the calendar object resource being targeted.
A.验证通过“rid”查询参数引用的任何重复实例是否对目标日历对象资源有效。
B. Validates that the "managed-id" query parameter is valid for the calendar object resource and specific instances being targeted.
B.验证“托管id”查询参数对日历对象资源和目标特定实例是否有效。
C. For each affected recurrence instance in the calendar object resource targeted by the request, 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 an overridden component with the appropriate "RECURRENCE-ID" property and the matching "ATTACH" property removed. This latter case is actually valid only if the master component does include the referenced "ATTACH" property.
C.对于请求所针对的日历对象资源中每个受影响的重复实例,删除匹配的“ATTACH”属性。请注意,如果指定的定期实例在日历对象资源中没有匹配的组件,则服务器必须修改日历对象资源,以包括覆盖的组件,并删除相应的“recurrence-ID”属性和匹配的“ATTACH”属性。后一种情况实际上只有在主组件包含引用的“ATTACH”属性时才有效。
D. If the attachment resource is no longer referenced by any instance of the calendar object resource, it can delete the attachment resource to free up storage space.
D.如果附件资源不再被日历对象资源的任何实例引用,它可以删除附件资源以释放存储空间。
E. Upon successful removal of the attachment resource and modification of the targeted calendar object resource, it MUST return an appropriate HTTP success status response. If the client included a Prefer header field with the "return=representation" preference in the request, the server SHOULD return the modified calendar object resource as the body of the response. Otherwise, the server can expect that the client will reload the calendar object resource with a subsequent GET request to refresh any local cache.
E.成功删除附件资源并修改目标日历对象资源后,它必须返回适当的HTTP成功状态响应。如果客户端在请求中包含带有“return=representation”首选项的preference头字段,则服务器应将修改后的日历对象资源作为响应主体返回。否则,服务器可以预期客户端将使用后续GET请求重新加载日历对象资源,以刷新任何本地缓存。
In the following example, the client deletes an existing attachment by passing its "managed-id" value in the request. The Prefer header field [RFC7240] is not set in the request so the calendar object resource data is not returned in the response.
在下面的示例中,客户端通过在请求中传递其“托管id”值来删除现有附件。请求中未设置首选标头字段[RFC7240],因此响应中不会返回日历对象资源数据。
>> Request <<
>> Request <<
POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1 Host: cal.example.com Content-Length: 0
POST /events/64.ics?action=attachment-remove&managed-id=98S HTTP/1.1 Host: cal.example.com Content-Length: 0
>> Response <<
>> Response <<
HTTP/1.1 204 No Content Content-Length: 0
HTTP/1.1 204无内容长度: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).
客户端可以通过向日历对象资源添加相应的“ATTACH”属性来使用现有托管附件(受第3.12.2节所述限制的约束)。
If a managed attachment is used in more than calendar resource, servers SHOULD NOT change either the "MANAGED-ID" property 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" property parameter values and replace incorrect values with the actual sizes of existing attachments.
如果托管附件在多个日历资源中使用,服务器不应更改这些附件的“managed-ID”属性参数值或“ATTACH”属性值;这可以确保客户端不必再次下载已缓存的附件数据。此外,服务器应验证“大小”属性参数值,并用现有附件的实际大小替换不正确的值。
These PUT requests are subject to the preconditions listed in Section 3.11.
这些PUT请求受第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.
服务器不得允许客户端通过附件URI上的PUT(或通过修改内容的任何其他HTTP方法)直接更新附件数据。相反,只能通过使用日历数据上的POST请求来更新附件。
Clients can remove attachments by simply rewriting 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.
客户端只需重写日历对象资源数据以删除相应的“附加”属性,即可删除附件。服务器不得允许客户端通过附件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).
客户端通过发出HTTP GET请求来检索附件,该请求使用相应的“ATTACH”属性的值作为请求URI,同时考虑与“CALDAV:managed attachments server URL”属性相关联的替换机制(请参见第6.1节)。
This specification creates additional preconditions for the POST method.
本规范为POST方法创建了附加的先决条件。
The new preconditions are:
新的先决条件是:
(CALDAV:max-attachment-size): The attachment submitted in the POST request MUST have an octet size less than or equal to the value of the "CALDAV:max-attachment-size" property value (Section 6.2) on the calendar collection of the target calendar resource.
(CALDAV:max attachment size):POST请求中提交的附件的八位字节大小必须小于或等于目标日历资源的日历集合上“CALDAV:max attachment size”属性值(第6.2节)的值。
(CALDAV:max-attachments-per-resource): The addition of the attachment submitted in the POST request MUST result in the target calendar resource having a number of managed attachments less than or equal to the value of the "CALDAV:max-attachments-per-resource" property value (Section 6.3) on the calendar collection of the target calendar resource.
(CALDAV:max attachments per resource):添加POST请求中提交的附件必须导致目标日历资源的托管附件数量小于或等于目标日历资源的日历集合上“CALDAV:max attachments per resource”属性值(第6.3节)的值。
(CALDAV:valid-action): The "action" query parameter in the POST request MUST contain only one of the following three values: "attachment-add", "attachment-update", or "attachment-remove".
(CALDAV:valid action):POST请求中的“action”查询参数只能包含以下三个值之一:“附件添加”、“附件更新”或“附件删除”。
(CALDAV:valid-rid): The "rid" query parameter in the POST request MUST NOT be present with an "action=attachment-update" query parameter and MUST contain the value "M" and/or values corresponding to "RECURRENCE-ID" property values in the iCalendar data targeted by the request.
(CALDAV:有效rid):POST请求中的“rid”查询参数不得与“action=附件更新”查询参数一起出现,并且必须包含值“M”和/或与请求所针对的iCalendar数据中的“RECURRENCE-ID”属性值相对应的值。
(CALDAV:valid-managed-id): The "managed-id" query parameter in the POST request MUST NOT be present with an "action=attachment-add" query parameter and MUST contain a value corresponding to a "MANAGED-ID" property parameter value in the iCalendar data targeted by the request.
(CALDAV:有效的托管id):POST请求中的“托管id”查询参数不得与“action=attachment add”查询参数一起出现,并且必须包含与请求所针对的iCalendar数据中的“managed-id”属性参数值相对应的值。
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):
添加、修改或删除托管附件的POST请求会隐式修改目标日历资源(相当于PUT)。因此,客户还应该准备好处理与此隐式PUT相关的先决条件。这包括(但不限于):
(CALDAV:max-resource-size) (from Section 5.3.2.1 of [RFC4791])
(CALDAV:最大资源规模)(来自[RFC4791]第5.3.2.1节)
(DAV:quota-not-exceeded) (from Section 6 of [RFC4331])
(DAV:未超过配额)(来自[RFC4331]第6节)
(DAV:sufficient-disk-space) (from Section 6 of [RFC4331])
(DAV:足够的磁盘空间)(来自[RFC4331]的第6节)
A PUT request to add or modify an existing calendar object resource can make reference to an existing managed attachment. The following new precondition is defined:
添加或修改现有日历对象资源的PUT请求可以引用现有托管附件。定义了以下新的先决条件:
(CALDAV:valid-managed-id-parameter): a "MANAGED-ID" property parameter value in the iCalendar data in the PUT request is not valid (e.g., does not match any existing managed attachment).
(CALDAV:有效的托管id参数):PUT请求中iCalendar数据中的“托管id”属性参数值无效(例如,与任何现有托管附件不匹配)。
If a precondition for a request is not satisfied:
如果不满足请求的先决条件:
1. The response status of the request MUST either be 403 (Forbidden) if the request should not be repeated because it will always fail, or 409 (Conflict) if it is expected that the user might be able to resolve the conflict and resubmit the request.
1. 如果请求因总是失败而不应重复,则请求的响应状态必须为403(禁止);如果预期用户可能能够解决冲突并重新提交请求,则请求的响应状态必须为409(冲突)。
2. The appropriate XML element MUST be returned as the child of a top-level DAV:error element in the response body.
2. 相应的XML元素必须作为响应体中顶级DAV:error元素的子元素返回。
The WebDAV Quotas specification [RFC4331] 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 attachment sizes when calculating the amount of storage used by a particular resource.
WebDAV配额规范[RFC4331]定义了两个活动WebDAV属性(DAV:配额可用字节和DAV:配额使用字节),用于向客户端传递存储配额信息。在计算特定资源使用的存储量时,服务器实现可以选择包括托管附件大小。
Access to the managed attachments referenced 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.
访问托管附件时,客户端应准备好向存储附件资源的服务器进行身份验证。访问托管附件存储所需的凭据可能不同于用于访问CalDAV服务器的凭据。
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 reusing a managed attachment (based on its "managed-id" value), unless that user is the one who originally created the managed attachment.
此规范仅允许计划事件的组织者添加托管附件。服务器必须阻止计划活动的与会者添加、更新或删除托管附件。此外,服务器必须防止日历用户重用托管附件(基于其“托管id”值),除非该用户是最初创建托管附件的用户。
For POST requests that add or update attachment data, the server MAY issue a 307 (Temporary Redirect) [RFC7231] or 308 (Permanent Redirect) [RFC7538] response to require the client to reissue 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.
对于添加或更新附件数据的POST请求,服务器可以发出307(临时重定向)[RFC7231]或308(永久重定向)[RFC7538]响应,以要求客户端使用不同的请求URI重新发出POST请求。因此,客户应使用[RFC7231]第5.1.1节中定义的“100继续”预期。使用此机制可以确保,如果发生重定向,客户端不会不必要地发送附件数据。
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.
客户端可以期望服务器需要一段时间来响应包含大型附件主体的POST请求。如果POST请求需要很长时间才能完成,服务器应使用[RFC2518]第10.1节中定义的102(处理)临时响应来保持客户端连接处于活动状态。
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.
服务器可能会自动删除附件数据,例如,以恢复未使用的附件占用的存储空间或作为病毒扫描的结果。执行此操作时,他们不应修改引用这些附件的日历数据。相反,对于删除的附件URI上的任何请求,它们应该使用410(Gone)进行响应。
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].
根据[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).
从支持托管附件的CalDAV服务器导出日历数据时,客户端应从日历数据中的“附加”属性中删除所有“托管ID”属性参数。类似地,从另一个源导入日历数据时,客户端应删除“附加”属性上的任何“托管ID”属性参数(否则,服务器可能会自动删除这些属性)。
Parameter Name: SIZE
参数名称:大小
Purpose: To specify the size of an attachment.
目的:指定附件的大小。
Format Definition: This property parameter is defined by the following notation:
格式定义:此属性参数由以下符号定义:
sizeparam = "SIZE" "=" paramtext ; positive integers
sizeparam=“SIZE”“=”参数文本;正整数
Description: This property parameter MAY be specified on "ATTACH" properties. It indicates the size in octets of the corresponding attachment data. Since iCalendar integer values are restricted to a maximum value of 2147483647, the current property parameter is defined as text to allow an extended range to be used.
说明:此属性参数可以在“附加”属性上指定。它表示相应附件数据的大小(以八位字节为单位)。由于iCalendar整数值的最大值限制为2147483647,因此当前属性参数定义为文本,以允许使用扩展范围。
Example:
例子:
ATTACH;SIZE=1234:https://attachments.example.com/abcd.txt
ATTACH;SIZE=1234:https://attachments.example.com/abcd.txt
Parameter Name: FILENAME
参数名称:FILENAME
Purpose: To specify the filename of a managed attachment.
目的:指定托管附件的文件名。
Format Definition: This property parameter is defined by the following notation:
格式定义:此属性参数由以下符号定义:
filenameparam = "FILENAME" "=" paramtext
filenameparam=“FILENAME”“=”paramtext
Description: This property parameter MAY be specified on "ATTACH" properties corresponding to managed attachments. Its value provides information on how to construct a filename for storing the attachment data. This parameter is very similar in nature to the Content-Disposition header field "filename" parameter and exposes the same security risks. As a consequence, clients MUST follow the guidelines expressed in Section 4.3 of [RFC6266] when consuming this property parameter value. Similarly, servers MUST follow those same guidelines before storing a value.
描述:此属性参数可以在与托管附件对应的“附加”属性上指定。它的值提供有关如何构造用于存储附件数据的文件名的信息。此参数在性质上与内容处置标题字段“filename”参数非常相似,并且暴露了相同的安全风险。因此,客户在使用该属性参数值时必须遵循[RFC6266]第4.3节中所述的指导原则。类似地,服务器在存储值之前必须遵循相同的准则。
Example:
例子:
ATTACH;FILENAME=agenda.html: https://attachments.example.com/rt452S
ATTACH;FILENAME=agenda.html: https://attachments.example.com/rt452S
Parameter Name: MANAGED-ID
参数名称:MANAGED-ID
Purpose: To uniquely identify a managed attachment.
目的:唯一标识托管附件。
Format Definition: This property parameter is defined by the following notation:
格式定义:此属性参数由以下符号定义:
managedidparam = "MANAGED-ID" "=" paramtext
managedidparam=“MANAGED-ID”“=”paramtext
Description: This property parameter MUST be specified on "ATTACH" properties corresponding to managed attachments. Its value is generated by the server and uniquely identifies a managed attachment within the scope of the CalDAV server. This property parameter MUST NOT be present in the case of unmanaged attachments.
描述:必须在与托管附件对应的“附加”属性上指定此属性参数。其值由服务器生成,并唯一标识CalDAV服务器范围内的托管附件。对于非托管附件,此属性参数不得存在。
Example:
例子:
ATTACH;MANAGED-ID=aUNhbGVuZGFy: https://attachments.example.com/abcd.txt
ATTACH;MANAGED-ID=aUNhbGVuZGFy: https://attachments.example.com/abcd.txt
The Cal-Managed-ID response header field provides the value of the "MANAGED-ID" property parameter corresponding to a newly added "ATTACH" property.
Cal Managed ID响应标头字段提供与新添加的“ATTACH”属性相对应的“Managed-ID”属性参数的值。
ABNF:
荷兰银行:
Cal-Managed-ID = "Cal-Managed-ID" ":" paramtext ; "paramtext" is defined in Section 3.1 of [RFC5545]
Cal Managed ID=“Cal Managed ID”“:”paramtext;[RFC5545]第3.1节对“paramtext”进行了定义
Example:
例子:
Cal-Managed-ID:aUNhbGVuZGFy
Cal托管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" query parameter set to "attachment-add" or "attachment-update". It MUST only appear once in a response and MUST NOT appear in trailers.
Cal Managed ID标头字段只能由源服务器发送,以响应“操作”查询参数设置为“附件添加”或“附件更新”的成功POST请求。它只能在响应中出现一次,不得出现在拖车中。
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.
Cal Managed ID标头字段是端到端的,必须由中介转发。中介机构不得插入、删除或修改Cal托管ID标头字段。
Name: managed-attachments-server-URL
名称:托管附件服务器URL
Namespace: urn:ietf:params:xml:ns:caldav
Namespace: urn:ietf:params:xml:ns:caldav
Purpose: This property specifies the server base URI to use when retrieving managed attachments.
用途:此属性指定检索托管附件时要使用的服务器基URI。
Protected: This property MUST be protected as only the server can update the value.
受保护:必须保护此属性,因为只有服务器才能更新该值。
COPY/MOVE behavior: This property is only defined on a calendar home collection, which cannot be moved or copied.
复制/移动行为:此属性仅在日历主集合上定义,不能移动或复制。
allprop behavior: This property SHOULD NOT be returned by a PROPFIND DAV:allprop request.
allprop行为:PROPFIND DAV:allprop请求不应返回此属性。
Description: This property MAY be defined on a calendar home collection. If present, it contains either a single DAV:href XML element or none at all.
说明:此属性可以在日历主集合上定义。如果存在,则它包含单个DAV:href XML元素,或者根本不包含任何元素。
When one DAV:href element is present, its value MUST be an absolute HTTP URI containing only the scheme (i.e., "https") and authority (i.e., host and port) parts. Whenever a managed attachment is to be retrieved via an HTTP GET, the client MUST construct the actual URL of the attachment by substituting the scheme and authority parts of the attachment URI (as stored in the iCalendar "ATTACH" property) with the present WebDAV property value.
当存在一个DAV:href元素时,其值必须是仅包含方案(即“https”)和权限(即主机和端口)部分的绝对HTTP URI。每当通过HTTP GET检索托管附件时,客户端必须通过用当前WebDAV属性值替换附件URI(存储在iCalendar“ATTACH”属性中)的scheme和authority部分来构造附件的实际URL。
When no DAV:href element is present, the client MUST substitute the scheme and authority parts of the attachment URI with the scheme and authority part of the calendar home collection absolute URI.
当不存在DAV:href元素时,客户端必须用日历主集合绝对URI的方案和权限部分替换附件URI的方案和权限部分。
In the absence of this property, the client can consider the attachment URI as its actual URL.
在缺少此属性时,客户端可以将附件URI视为其实际URL。
Definition:
定义:
<!ELEMENT managed-attachments-server-URL (DAV:href?)>
<!ELEMENT managed-attachments-server-URL (DAV:href?)>
Example:
例子:
<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>
<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>
Name: max-attachment-size
名称:最大附件大小
Namespace: urn:ietf:params:xml:ns:caldav
Namespace: urn:ietf:params:xml:ns:caldav
Purpose: This property provides a numeric value indicating the maximum attachment size, in octets, that the server is willing to accept when a managed attachment is stored on the server.
用途:此属性提供一个数字值,指示在服务器上存储托管附件时服务器愿意接受的最大附件大小(以八位字节为单位)。
Protected: This property MUST be protected as it indicates limits provided by the server.
受保护:必须保护此属性,因为它指示服务器提供的限制。
COPY/MOVE behavior: This property value MUST be preserved in COPY and MOVE operations.
复制/移动行为:复制和移动操作中必须保留此属性值。
allprop behavior: This property SHOULD NOT be returned by a PROPFIND DAV:allprop request.
allprop行为:PROPFIND DAV:allprop请求不应返回此属性。
Description: The "CALDAV:max-attachment-size" property is used to specify a numeric value that represents the maximum attachment size, in octets, that the server is willing to accept when a managed attachment is stored on the server. The property is defined on the parent collection of the calendar object resource to which the attachment is associated. Any attempt to store a managed attachment exceeding this size MUST result in an error, with the CALDAV:max-attachment-size precondition (Section 3.11) being violated. In the absence of this property, the client can assume that the server will allow storing an attachment of any reasonable size.
描述:“CALDAV:max attachment size”属性用于指定一个数值,该数值表示在服务器上存储托管附件时服务器愿意接受的最大附件大小(以八位字节为单位)。属性是在附件关联的日历对象资源的父集合上定义的。任何存储超过此大小的托管附件的尝试都必须导致错误,并违反CALDAV:max attachment size前提条件(第3.11节)。如果没有此属性,客户端可以假定服务器将允许存储任何合理大小的附件。
Definition:
定义:
<!ELEMENT max-attachment-size (#PCDATA)> <!-- PCDATA value: a numeric value (positive decimal integer) -->
<!ELEMENT max-attachment-size (#PCDATA)> <!-- PCDATA value: a numeric value (positive decimal integer) -->
Example:
例子:
<C:max-attachment-size xmlns:C="urn:ietf:params:xml:ns:caldav" >102400000</C:max-attachment-size>
<C:max-attachment-size xmlns:C="urn:ietf:params:xml:ns:caldav" >102400000</C:max-attachment-size>
Name: max-attachments-per-resource
名称:每个资源的最大附件数
Namespace: urn:ietf:params:xml:ns:caldav
Namespace: urn:ietf:params:xml:ns:caldav
Purpose: This property provides a numeric value indicating the maximum number of managed attachments across all instances of a calendar object resource stored in a calendar collection.
用途:此属性提供一个数值,指示存储在日历集合中的日历对象资源的所有实例中托管附件的最大数量。
Protected: This property MUST be protected as it indicates limits provided by the server.
受保护:必须保护此属性,因为它指示服务器提供的限制。
COPY/MOVE behavior: This property value MUST be preserved in COPY and MOVE operations.
复制/移动行为:复制和移动操作中必须保留此属性值。
allprop behavior: This property SHOULD NOT be returned by a PROPFIND DAV:allprop request.
allprop行为:PROPFIND DAV:allprop请求不应返回此属性。
Description: The "CALDAV:max-attachments-per-resource" property is used to specify a numeric value that represents the maximum number of managed attachments across all instances of a calendar object resource stored in a calendar collection. Unmanaged attachments are not counted toward that limit. The property is defined on the parent collection of the calendar object resource to which the attachment is associated. Any attempt to add a managed attachment that would cause the calendar resource to exceed this limit MUST result in an error, with the CALDAV:max-attachments-per-resource precondition (Section 3.11) being violated. In the absence of this property, the client can assume that the server can handle any number of managed attachments per calendar resource.
描述:“CALDAV:max attachments per resource”属性用于指定一个数值,该数值表示存储在日历集合中的日历对象资源的所有实例中托管附件的最大数量。非托管附件不计入该限制。属性是在附件关联的日历对象资源的父集合上定义的。任何添加托管附件的尝试都会导致日历资源超过此限制,这将导致错误,违反CALDAV:max attachments per resource前提条件(第3.11节)。如果没有此属性,客户端可以假定服务器可以处理每个日历资源的任意数量的托管附件。
Definition:
定义:
<!ELEMENT max-attachments-per-resource (#PCDATA)> <!-- PCDATA value: a numeric value (positive decimal integer) -->
<!ELEMENT max-attachments-per-resource (#PCDATA)> <!-- PCDATA value: a numeric value (positive decimal integer) -->
Example:
例子:
<C:max-attachments-per-resource xmlns:C="urn:ietf:params:xml:ns:caldav" >12</C:max-attachments-per-resource>
<C:max-attachments-per-resource xmlns:C="urn:ietf:params:xml:ns:caldav" >12</C:max-attachments-per-resource>
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.
[RFC4791]和[RFC4918]中的安全注意事项适用于此扩展。此外,服务器需要意识到,客户端可能通过发布超大附件来攻击底层存储,也可能通过上载具有大量覆盖的重复事件,然后重复添加、更新和删除附件来攻击处理时间。
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 such content, servers SHOULD remove the attachment following the rules described in Section 3.12.5.
恶意内容可能通过托管附件引入日历服务器,并通过调度传播给许多最终用户。服务器应检查托管附件是否存在恶意或不适当的内容。一旦检测到此类内容,服务器应按照第3.12.5节中描述的规则删除附件。
This specification defines the following new iCalendar property parameters to be added to the "Parameters" registry defined in Section 8.2.4 of [RFC5545]:
本规范定义了要添加到[RFC5545]第8.2.4节中定义的“参数”注册表中的以下新iCalendar属性参数:
+------------+---------+-----------------------+ | Parameter | Status | Reference | +------------+---------+-----------------------+ | SIZE | Current | RFC 8607, Section 4.1 | | FILENAME | Current | RFC 8607, Section 4.2 | | MANAGED-ID | Current | RFC 8607, Section 4.3 | +------------+---------+-----------------------+
+------------+---------+-----------------------+ | Parameter | Status | Reference | +------------+---------+-----------------------+ | SIZE | Current | RFC 8607, Section 4.1 | | FILENAME | Current | RFC 8607, Section 4.2 | | MANAGED-ID | Current | RFC 8607, Section 4.3 | +------------+---------+-----------------------+
The message header fields below should be added to the "Permanent Message Header Field Names" registry (see [RFC3864]).
下面的消息头字段应添加到“永久消息头字段名称”注册表中(请参见[RFC3864])。
Header field name: Cal-Managed-ID
标题字段名称:Cal托管ID
Protocol: http
协议:http
Status: standard
状态:标准
Author/Change controller: IETF
作者/变更控制员:IETF
Reference: this specification (Section 5.1)
参考:本规范(第5.1节)
Related information: none
相关信息:无
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner,S.,“RFC中用于表示需求水平的关键词”,BCP 14,RFC 2119,DOI 10.17487/RFC2119,1997年3月<https://www.rfc-editor.org/info/rfc2119>.
[RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, "HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, DOI 10.17487/RFC2518, February 1999, <https://www.rfc-editor.org/info/rfc2518>.
[RFC2518]Goland,Y.,Whitehead,E.,Faizi,A.,Carter,S.,和D.Jensen,“分布式创作的HTTP扩展——WEBDAV”,RFC 2518,DOI 10.17487/RFC2518,1999年2月<https://www.rfc-editor.org/info/rfc2518>.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, DOI 10.17487/RFC3864, September 2004, <https://www.rfc-editor.org/info/rfc3864>.
[RFC3864]Klyne,G.,Nottingham,M.和J.Mogul,“消息头字段的注册程序”,BCP 90,RFC 3864,DOI 10.17487/RFC3864,2004年9月<https://www.rfc-editor.org/info/rfc3864>.
[RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties for Distributed Authoring and Versioning (DAV) Collections", RFC 4331, DOI 10.17487/RFC4331, February 2006, <https://www.rfc-editor.org/info/rfc4331>.
[RFC4331]Korver,B.和L.Dusseault,“分布式创作和版本控制(DAV)集合的配额和大小属性”,RFC 4331,DOI 10.17487/RFC4331,2006年2月<https://www.rfc-editor.org/info/rfc4331>.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, March 2007, <https://www.rfc-editor.org/info/rfc4791>.
[RFC4791]Daboo,C.,Desruisseaux,B.,和L.Dusseault,“WebDAV(CalDAV)日历扩展”,RFC 4791,DOI 10.17487/RFC47912007年3月<https://www.rfc-editor.org/info/rfc4791>.
[RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, June 2007, <https://www.rfc-editor.org/info/rfc4918>.
[RFC4918]Dusseault,L.,Ed.“Web分布式创作和版本控制(WebDAV)的HTTP扩展”,RFC 4918,DOI 10.17487/RFC4918,2007年6月<https://www.rfc-editor.org/info/rfc4918>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <https://www.rfc-editor.org/info/rfc5234>.
[RFC5234]Crocker,D.,Ed.和P.Overell,“语法规范的扩充BNF:ABNF”,STD 68,RFC 5234,DOI 10.17487/RFC5234,2008年1月<https://www.rfc-editor.org/info/rfc5234>.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, September 2009, <https://www.rfc-editor.org/info/rfc5545>.
[RFC5545]Desruisseaux,B.,Ed.“互联网日历和调度核心对象规范(iCalendar)”,RFC 5545,DOI 10.17487/RFC5545,2009年9月<https://www.rfc-editor.org/info/rfc5545>.
[RFC6266] Reschke, J., "Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)", RFC 6266, DOI 10.17487/RFC6266, June 2011, <https://www.rfc-editor.org/info/rfc6266>.
[RFC6266]Reschke,J.,“超文本传输协议(HTTP)中内容处置头字段的使用”,RFC 6266,DOI 10.17487/RFC6266,2011年6月<https://www.rfc-editor.org/info/rfc6266>.
[RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, <https://www.rfc-editor.org/info/rfc6638>.
[RFC6638]Daboo,C.和B.Desruisseaux,“CalDAV的计划扩展”,RFC 6638,DOI 10.17487/RFC6638,2012年6月<https://www.rfc-editor.org/info/rfc6638>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, <https://www.rfc-editor.org/info/rfc7230>.
[RFC7230]Fielding,R.,Ed.和J.Reschke,Ed.,“超文本传输协议(HTTP/1.1):消息语法和路由”,RFC 7230,DOI 10.17487/RFC7230,2014年6月<https://www.rfc-editor.org/info/rfc7230>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <https://www.rfc-editor.org/info/rfc7231>.
[RFC7231]Fielding,R.,Ed.和J.Reschke,Ed.,“超文本传输协议(HTTP/1.1):语义和内容”,RFC 7231,DOI 10.17487/RFC72312014年6月<https://www.rfc-editor.org/info/rfc7231>.
[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, DOI 10.17487/RFC7240, June 2014, <https://www.rfc-editor.org/info/rfc7240>.
[RFC7240]Snell,J.,“HTTP的首选标头”,RFC 7240,DOI 10.17487/RFC7240,2014年6月<https://www.rfc-editor.org/info/rfc7240>.
[RFC7538] Reschke, J., "The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)", RFC 7538, DOI 10.17487/RFC7538, April 2015, <https://www.rfc-editor.org/info/rfc7538>.
[RFC7538]Reschke,J.,“超文本传输协议状态代码308(永久重定向)”,RFC 7538,DOI 10.17487/RFC7538,2015年4月<https://www.rfc-editor.org/info/rfc7538>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8174]Leiba,B.,“RFC 2119关键词中大写与小写的歧义”,BCP 14,RFC 8174,DOI 10.17487/RFC8174,2017年5月<https://www.rfc-editor.org/info/rfc8174>.
[RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023, October 2007, <https://www.rfc-editor.org/info/rfc5023>.
[RFC5023]Gregorio,J.,Ed.和B.de hOra,Ed.,“原子出版协议”,RFC 5023,DOI 10.17487/RFC5023,2007年10月<https://www.rfc-editor.org/info/rfc5023>.
[RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, DOI 10.17487/RFC5546, December 2009, <https://www.rfc-editor.org/info/rfc5546>.
[RFC5546]Daboo,C.,Ed.“iCalendar传输独立互操作性协议(iTIP)”,RFC 5546,DOI 10.17487/RFC5546,2009年12月<https://www.rfc-editor.org/info/rfc5546>.
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 7320, DOI 10.17487/RFC7320, July 2014, <https://www.rfc-editor.org/info/rfc7320>.
[RFC7320]诺丁汉,M.,“URI设计和所有权”,BCP 190,RFC 7320,DOI 10.17487/RFC7320,2014年7月<https://www.rfc-editor.org/info/rfc7320>.
[RFC8144] Murchison, K., "Use of the Prefer Header Field in Web Distributed Authoring and Versioning (WebDAV)", RFC 8144, DOI 10.17487/RFC8144, April 2017, <https://www.rfc-editor.org/info/rfc8144>.
[RFC8144]Murchison,K.,“在Web分布式创作和版本控制(WebDAV)中使用首选标头字段”,RFC 8144,DOI 10.17487/RFC8144,2017年4月<https://www.rfc-editor.org/info/rfc8144>.
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]).
在下面的示例中,定期会议的组织者尝试使用条件请求将议程(HTML附件)添加到相应的日历资源,但未成功。请注意,客户端在请求中同时包含Expect和Preference标头字段,从而防止客户端不必要地发送附件数据并请求在故障响应中返回当前资源(请参阅[RFC8144]的第3.2节)。
>> Request <<
>> 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: 80 If-Match: "abcdefg-000" Expect: 100-continue Prefer: return=representation
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: 80 If-Match: "abcdefg-000" Expect: 100-continue Prefer: return=representation
>> Final Response <<
>> Final Response <<
HTTP/1.1 412 Precondition Failed Content-Type: text/calendar; charset="utf-8" Content-Length: 929 Content-Location: https://cal.example.com/events/65.ics ETag: "123456789-000-000"
HTTP/1.1 412 Precondition Failed Content-Type: text/calendar; charset="utf-8" Content-Length: 929 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
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.
定期会议的组织者成功地将议程(HTML附件)添加到相应的日历资源中。会议的与会者被授予对新创建的附件资源的读取权限。他们自己的会议副本将更新,以包括指向附件资源的新“ATTACH”属性,并通过他们的日程安排收件箱通知他们更改。
>> Request <<
>> 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: 80 If-Match: "123456789-000-000" Expect: 100-continue Prefer: return=representation
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: 80 If-Match: "123456789-000-000" Expect: 100-continue Prefer: return=representation
>> Interim Response <<
>> Interim Response <<
HTTP/1.1 100 Continue
HTTP/1.1 100继续
>> Request Body <<
>> Request Body <<
<html> <body> <h1>Agenda</h1> <p>As usual</p> </body> </html>
<html> <body> <h1>Agenda</h1> <p>As usual</p> </body> </html>
>> Final Response <<
>> Final Response <<
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: 1043 Content-Location: https://cal.example.com/events/65.ics ETag: "123456789-000-111" Cal-Managed-ID: 97S
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: 1043 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=80; FILENAME=agenda.html:https://cal.example.com/attach/65/34X22R END:VEVENT END:VCALENDAR
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=80; 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" query 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.
组织者对2月20日的会议有更具体的议程。它通过指定“rid”查询参数添加到会议的特定实例中。请注意,使用与请求中“rid”查询参数的值匹配的“RECURRENCE-ID”属性值创建重写的实例。另外,请注意,服务器需要花费大量时间来完成请求,并相应地通知客户机。
>> Request <<
>> 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: 105 If-Match: "123456789-000-111" Expect: 100-continue Prefer: return=representation
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: 105 If-Match: "123456789-000-111" Expect: 100-continue Prefer: return=representation
>> Interim Response <<
>> Interim Response <<
HTTP/1.1 100 Continue
HTTP/1.1 100继续
>> Request Body <<
>> Request Body <<
<html> <body> <h1>Agenda</h1> <p>Something different, for a change</p> </body> </html>
<html> <body> <h1>Agenda</h1> <p>Something different, for a change</p> </body> </html>
>> Interim Response <<
>> Interim Response <<
HTTP/1.1 102 Processing
HTTP/1.1 102处理
>> Final Response <<
>> Final Response <<
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: 1661 Content-Location: https://cal.example.com/events/65.ics ETag: "123456789-000-222" Cal-Managed-ID: 33225
HTTP/1.1 201 Created Content-Type: text/calendar; charset="utf-8" Content-Length: 1661 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=80; 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
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=80; 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=105; FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225 END:VEVENT END:VCALENDAR
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=105; FILENAME=agenda0220.html:https://cal.example.com/attach/65/FGZ225 END:VEVENT END:VCALENDAR
Acknowledgments
致谢
This specification came about via discussions at the Calendaring and Scheduling Consortium. Thanks in particular to Mike Douglass and Eric York.
该规范是通过日历和日程安排联盟的讨论制定的。特别感谢迈克·道格拉斯和埃里克·约克。
Authors' Addresses
作者地址
Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino, CA 95014 United States of America
Cyrus Daboo苹果公司,美国加利福尼亚州库比蒂诺市无限环1号,邮编95014
Email: cyrus@daboo.name URI: http://www.apple.com/
Email: cyrus@daboo.name URI: http://www.apple.com/
Arnaud Quillaud Oracle Corporation 180, Avenue de l'Europe Saint Ismier cedex 38334 France
Arnaud Quillaud Oracle Corporation 180,法国圣伊斯梅尔塞德克斯欧洲大道38334号
Email: arnaud.quillaud@oracle.com URI: http://www.oracle.com/
Email: arnaud.quillaud@oracle.com URI: http://www.oracle.com/
Kenneth Murchison (editor) FastMail US LLC 1429 Walnut St, Suite 1201 Philadephia, PA 19102 United States of America
Kenneth Murchison(编辑)FastMail美国有限责任公司美国宾夕法尼亚州费城胡桃街1429号1201室,邮编:19102
Email: murch@fastmailteam.com URI: http://www.fastmail.com/
Email: murch@fastmailteam.com URI: http://www.fastmail.com/