Internet Engineering Task Force (IETF) K. Murchison
Request for Comments: 8144 CMU
Updates: 7240 April 2017
Category: Standards Track
ISSN: 2070-1721
Internet Engineering Task Force (IETF) K. Murchison
Request for Comments: 8144 CMU
Updates: 7240 April 2017
Category: Standards Track
ISSN: 2070-1721
Use of the Prefer Header Field in Web Distributed Authoring and Versioning (WebDAV)
在Web分布式创作和版本控制（WebDAV）中使用首选标题字段
Abstract
摘要
This document defines how the Prefer header field (RFC 7240) can be used by a Web Distributed Authoring and Versioning (WebDAV) client to request that certain behaviors be employed by a server while constructing a response to a request. Furthermore, it defines the new "depth-noroot" preference.
本文档定义了Web分布式创作和版本控制（WebDAV）客户端如何使用首选标头字段（RFC 7240）来请求服务器在构造请求响应时采用某些行为。此外，它还定义了新的“depth noroot”首选项。
This document updates RFC 7240.
本文档更新了RFC 7240。
Status of This Memo
关于下段备忘
This is an Internet Standards Track document.
这是一份互联网标准跟踪文件。
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). Further information on Internet Standards is available in Section 2 of RFC 7841.
本文件是互联网工程任务组（IETF）的产品。它代表了IETF社区的共识。它已经接受了公众审查，并已被互联网工程指导小组（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 http://www.rfc-editor.org/info/rfc8144.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc8144.
Copyright Notice
版权公告
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有（c）2017 IETF信托基金和确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://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文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件，因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本，并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Introduction ....................................................3
1.1. Notational Conventions .....................................3
2. Reducing WebDAV Response Verbosity with "return=minimal" ........3
2.1. Minimal PROPFIND and REPORT Responses ......................4
2.2. Minimal PROPPATCH Response .................................5
2.3. Minimal MKCALENDAR and MKCOL Responses .....................5
3. Reducing WebDAV Roundtrips with "return=representation" .........6
3.1. Successful State-Changing Requests .........................6
3.2. Unsuccessful Conditional State-Changing Requests ...........6
4. The "depth-noroot" Processing Preference ........................7
5. Security Considerations .........................................7
6. IANA Considerations .............................................8
6.1. Preference Registration ....................................8
6.2. Method References ..........................................8
6.3. Status Code References .....................................9
7. References ......................................................9
7.1. Normative References .......................................9
7.2. Informative References ....................................10
Appendix A. The Brief and Extended Depth Header Fields ...........12
Appendix B. Examples .............................................12
B.1. PROPFIND ..................................................12
B.2. REPORT ....................................................16
B.3. PROPPATCH .................................................21
B.4. MKCOL .....................................................22
B.5. POST ......................................................23
B.6. PUT .......................................................27
Acknowledgements ..................................................28
Author's Address ..................................................28
1. Introduction ....................................................3
1.1. Notational Conventions .....................................3
2. Reducing WebDAV Response Verbosity with "return=minimal" ........3
2.1. Minimal PROPFIND and REPORT Responses ......................4
2.2. Minimal PROPPATCH Response .................................5
2.3. Minimal MKCALENDAR and MKCOL Responses .....................5
3. Reducing WebDAV Roundtrips with "return=representation" .........6
3.1. Successful State-Changing Requests .........................6
3.2. Unsuccessful Conditional State-Changing Requests ...........6
4. The "depth-noroot" Processing Preference ........................7
5. Security Considerations .........................................7
6. IANA Considerations .............................................8
6.1. Preference Registration ....................................8
6.2. Method References ..........................................8
6.3. Status Code References .....................................9
7. References ......................................................9
7.1. Normative References .......................................9
7.2. Informative References ....................................10
Appendix A. The Brief and Extended Depth Header Fields ...........12
Appendix B. Examples .............................................12
B.1. PROPFIND ..................................................12
B.2. REPORT ....................................................16
B.3. PROPPATCH .................................................21
B.4. MKCOL .....................................................22
B.5. POST ......................................................23
B.6. PUT .......................................................27
Acknowledgements ..................................................28
Author's Address ..................................................28
[RFC7240] defines the Prefer header field and the "return=minimal" preference, which indicate that a client wishes for the server to return a minimal response to a successful request but states that what constitutes an appropriate minimal response is left solely to the discretion of the server. Section 2 of this specification defines precisely what is expected of a server when constructing minimal responses to successful WebDAV [RFC4918] requests.
[RFC7240]定义首选标头字段和“return=minimal”首选项，这表示客户端希望服务器对成功的请求返回最小响应，但表示构成适当最小响应的内容完全由服务器决定。本规范的第2节精确定义了在对成功的WebDAV[RFC4918]请求构造最小响应时，服务器的期望值。
[RFC7240] also defines the "return=representation" preference, which indicates that a client wishes for the server to include an entity representing the current state of the resource in the response to a successful request. Section 3 of this specification makes recommendations on when this preference should be used by clients and extends its applicability to 412 (Precondition Failed) [RFC7232] responses.
[RFC7240]还定义了“return=representation”首选项，该首选项表示客户端希望服务器在对成功请求的响应中包含表示资源当前状态的实体。本规范第3节就客户何时应使用此首选项提出了建议，并将其适用范围扩展到412（前提条件失败）[RFC7232]响应。
Finally, Section 4 of this specification defines the "depth-noroot" preference that can be used with HTTP methods that support the Depth header field.
最后，本规范的第4节定义了“depth noroot”首选项，该首选项可与支持depth头字段的HTTP方法一起使用。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照[RFC2119]中所述进行解释。
This document references XML element types in the "DAV:" [RFC4918], "urn:ietf:params:xml:ns:caldav" [RFC4791], and "urn:ietf:params:xml:ns:carddav" [RFC6352] namespaces outside of the context of an XML fragment. When doing so, the strings "DAV:", "CALDAV:", and "CARDDAV:" will be prepended to the XML element types, respectively.
本文档引用了XML片段上下文之外的“DAV:[RFC4918]、“urn:ietf:params:XML:ns:caldav”[RFC4791]和“urn:ietf:params:XML:ns:carddav”[RFC6352]命名空间中的XML元素类型。执行此操作时，字符串“DAV:”、“CALDAV:”和“CARDDAV:”将分别前置到XML元素类型。
Some payload bodies in responses to WebDAV requests, such as 207 (Multi-Status) [RFC4918] responses, can be quite verbose or even unnecessary at times. This specification defines how the Prefer header field, in conjunction with its "return=minimal" preference, can be used by clients to reduce the verbosity of such responses by requesting that the server omit those portions of the response that can be inferred by their absence.
响应WebDAV请求的一些有效负载体，例如207（多状态）[RFC4918]响应，有时可能非常冗长甚至不必要。此规范定义了客户端如何使用preference header字段及其“return=minimal”首选项，通过请求服务器忽略响应中可以通过缺少响应推断出来的部分，来减少此类响应的详细性。
When a PROPFIND [RFC4918] request, or a REPORT [RFC3253] request whose report type results in a 207 (Multi-Status) response, contains a Prefer header field with a preference of "return=minimal", the server SHOULD omit all DAV:propstat XML elements containing a DAV:status XML element of value 404 (Not Found) [RFC7231] from the 207 (Multi-Status) response. If the omission of such a DAV:propstat element would result in a DAV:response XML element containing zero DAV:propstat elements, the server MUST substitute one of the following in its place:
当PROPFIND[RFC4918]请求或报告类型导致207（多状态）响应的报告[RFC3253]请求包含首选项为“return=minimal”的首选标头字段时，服务器应忽略207（多状态）中包含值404（未找到）[RFC7231]的DAV:Status XML元素的所有DAV:propstat XML元素回答如果省略这样一个DAV:propstat元素会导致一个包含零个DAV:propstat元素的DAV:response XML元素，那么服务器必须替换以下元素之一：
o a DAV:propstat element consisting of an empty DAV:prop element and a DAV:status element of value 200 (OK) [RFC7231]
o 一个DAV:propstat元素，由一个空的DAV:prop元素和一个值为200（OK）的DAV:status元素组成[RFC7231]
o a DAV:status element of value 200 (OK)
o DAV：值为200（正常）的状态元素
The following report types are candidates that could benefit from use of the "return=minimal" preference. NOTE: This list is not intended to be normative or exhaustive.
以下报告类型是可能受益于使用“return=minimal”首选项的候选报告类型。注：本清单并非规范性或详尽无遗。
o DAV:expand-property [RFC3253]
o DAV:扩展属性[RFC3253]
o DAV:acl-principal-prop-set [RFC3744]
o DAV:acl主要道具集[RFC3744]
o DAV:principal-property-search [RFC3744]
o DAV：主要财产搜索[RFC3744]
o DAV:sync-collection [RFC6578]
o DAV:同步收集[RFC6578]
o CALDAV:calendar-query [RFC4791]
o CALDAV:日历查询[RFC4791]
o CALDAV:calendar-multiget [RFC4791]
o CALDAV:日历多重获取[RFC4791]
o CARDDAV:addressbook-query [RFC6352]
o CARDDAV:通讯簿查询[RFC6352]
o CARDDAV:addressbook-multiget [RFC6352]
o CARDDAV:addressbook multiget[RFC6352]
See Appendices B.1 and B.2 for examples.
示例见附录B.1和B.2。
When a PROPPATCH [RFC4918] request contains a Prefer header field with a preference of "return=minimal", and all instructions are processed successfully, the server SHOULD return one of the following responses rather than a 207 (Multi-Status) response:
当PROPPATCH[RFC4918]请求包含首选项为“return=minimal”的首选标头字段，并且所有指令都已成功处理时，服务器应返回以下响应之一，而不是207（多状态）响应：
o 204 (No Content) [RFC7231]
o 204（无内容）[RFC7231]
o 200 (OK) [RFC7231] (preferably with a zero-length message body)
o 200（正常）[RFC7231]（最好具有零长度消息正文）
See Appendix B.3 for examples.
示例见附录B.3。
Both the MKCALENDAR [RFC4791] and Extended MKCOL [RFC5689] specifications indicate that a server MAY return a message body in response to a successful request. This specification explicitly defines the intended behavior in the presence of the Prefer header field.
MKCALENDAR[RFC4791]和扩展MKCOL[RFC5689]规范都表明，服务器可以返回消息正文以响应成功的请求。此规范明确定义了存在首选标头字段时的预期行为。
When a MKCALENDAR or an extended MKCOL request contains a Prefer header field with a preference of "return=minimal", and the collection is created with all requested properties being set successfully, the server SHOULD return a 201 (Created) [RFC7231] response with an empty (zero-length) message body.
当MKCALENDAR或扩展MKCOL请求包含首选项为“return=minimal”的首选项标头字段，并且在成功设置所有请求属性的情况下创建集合时，服务器应返回201（已创建）[RFC7231]响应，其中消息正文为空（长度为零）。
Note that the rationale for requiring that a minimal success response have an empty body is twofold:
请注意，要求最小成功响应具有空体的理由有两个：
o [RFC4791], Section 5.3.1 states: "If a response body for a successful request is included, it MUST be a CALDAV:mkcalendar-response XML element."
o [RFC4791]，第5.3.1节规定：“如果包含成功请求的响应正文，则它必须是CALDAV:mkcalendar响应XML元素。”
o [RFC5689], Section 3 states: "When an empty response body is returned with a success request status code, the client can assume that all properties were set."
o [RFC5689]，第3节指出：“当返回一个空响应正文并带有成功请求状态代码时，客户机可以假定所有属性都已设置。”
See Appendix B.4 for examples.
示例见附录B.4。
[RFC7240] describes the "return=representation" preference as being intended to provide a means of optimizing communication between the client and server by eliminating the need for a subsequent GET request to retrieve the current representation of the resource following a modification. This preference is equally applicable to situations where the server itself modifies a resource, and where a resource has been modified by another client.
[RFC7240]将“return=representation”首选项描述为提供一种优化客户机和服务器之间通信的方法，通过消除在修改后检索资源当前表示的后续GET请求的需要。此首选项同样适用于服务器本身修改资源以及另一个客户端修改了资源的情况。
The state-changing methods PUT [RFC7231], COPY/MOVE [RFC4918], PATCH [RFC5789], and POST [RFC5995] can be used to create or update a resource. In some instances, such as with Calendaring Extensions to WebDAV (CalDAV) Scheduling [RFC6638], the created or updated resource representation may differ from the representation sent in the body of the request or from that referenced by the effective request URI. In cases where the client, upon receiving a 2xx (Successful) [RFC7231] response to its state-changing request, would normally issue a subsequent GET request to retrieve the current representation of the resource, the client can instead include a Prefer header field with the "return=representation" preference in the state-changing request.
状态更改方法PUT[RFC7231]、复制/移动[RFC4918]、修补[RFC5789]和POST[RFC5995]可用于创建或更新资源。在某些情况下，例如使用WebDAV（CalDAV）调度的日历扩展[RFC6638]，创建或更新的资源表示可能不同于请求正文中发送的表示或有效请求URI引用的表示。如果客户端在收到对其状态更改请求的2xx（成功）[RFC7231]响应后，通常会发出后续GET请求以检索资源的当前表示形式，则客户端可以在状态更改请求中包含带有“return=representation”首选项的preference标头字段。
When a state-changing request contains a Prefer header field with a preference of "return=representation", and the resource is created or updated successfully, the server SHOULD include an entity representing the current state of the resource in the resulting 201 (Created) or 200 (OK) [RFC7231] response. In addition to coalescing the create/update and retrieve operations into a single roundtrip, by returning the current representation of the resource in the response, the client will know that any changes to the resource were produced by the server rather than a concurrent client, thus providing a level of atomicity to the operation.
当状态更改请求包含首选项为“return=representation”的首选项标头字段，并且成功创建或更新资源时，服务器应在结果201（已创建）或200（确定）[RFC7231]响应中包含表示资源当前状态的实体。除了将创建/更新和检索操作合并到单个往返中之外，通过在响应中返回资源的当前表示形式，客户机将知道对资源的任何更改都是由服务器而不是并发客户机生成的，从而为操作提供了原子性级别。
See Appendix B.5 for examples.
示例见附录B.5。
Frequently, clients using a state-changing method such as those listed above will make them conditional by including either an If-Match or an If-None-Match [RFC7232] header field in the request. This is done to prevent the client from accidentally overwriting a resource whose current state has been modified by another client acting in parallel. In cases where the client, upon receiving a 412 (Precondition Failed) [RFC7232] response to its conditional state-changing request, would normally issue a subsequent GET request to retrieve the current representation of the resource, the client can
通常，使用上述状态更改方法的客户端会通过在请求中包含If-Match或If-None-Match[RFC7232]头字段使其具有条件。这样做是为了防止客户端意外覆盖其当前状态已被另一个并行操作的客户端修改的资源。如果客户机在收到对其条件状态更改请求的412（前提条件失败）[RFC7232]响应后，通常会发出后续GET请求以检索资源的当前表示形式，则客户机可以
instead include a Prefer header field with the "return=representation" preference in the conditional state-changing request.
相反，在条件状态更改请求中包含带有“return=representation”首选项的preference头字段。
When a conditional state-changing request contains a Prefer header field with a preference of "return=representation", and the specified condition evaluates to false, the server SHOULD include an entity representing the current state of the resource in the resulting 412 (Precondition Failed) [RFC7232] response.
当条件状态更改请求包含首选项为“return=representation”的首选标头字段，且指定的条件计算结果为false时，服务器应在结果412（前提条件失败）[RFC7232]响应中包含表示资源当前状态的实体。
See Appendix B.6 for examples.
示例见附录B.6。
The "depth-noroot" preference indicates that the client wishes for the server to exclude the target (root) resource from processing by the HTTP method and only apply the HTTP method to the target resource's subordinate resources.
“depth noroot”首选项表示客户端希望服务器将目标（根）资源从HTTP方法的处理中排除，并且仅将HTTP方法应用于目标资源的从属资源。
This preference is only intended to be used with HTTP methods whose definitions explicitly provide support for the Depth [RFC4918] header field. Furthermore, this preference only applies when the Depth header field has a value of "1" or "infinity" (either implicitly or explicitly).
此首选项仅用于HTTP方法，这些方法的定义明确支持深度[RFC4918]头字段。此外，此首选项仅在深度标头字段的值为“1”或“无穷大”（隐式或显式）时适用。
The "depth-noroot" preference MAY be used in conjunction with the "return=minimal" preference in a single request.
“depth noroot”首选项可以与单个请求中的“return=minimal”首选项结合使用。
See Appendix B.1 for examples.
示例见附录B.1。
No new security considerations are introduced by use of the Prefer header field with WebDAV requests, beyond those discussed in [RFC7240] and those already inherent in those requests.
除了[RFC7240]中讨论的内容和这些请求中固有的内容外，在WebDAV请求中使用Preference header字段不会引入新的安全注意事项。
The following preference has been added to the HTTP Preferences Registry defined in Section 5.1 of [RFC7240].
以下首选项已添加到[RFC7240]第5.1节中定义的HTTP首选项注册表中。
Preference: depth-noroot
首选项：深度noroot
Description: The "depth-noroot" preference indicates that the client wishes for the server to exclude the target (root) resource from processing by the HTTP method and only apply the HTTP method to the target resource's subordinate resources.
描述：“depth noroot”首选项表示客户端希望服务器通过HTTP方法将目标（根）资源排除在处理之外，并且仅将HTTP方法应用于目标资源的从属资源。
Reference: RFC 8144, Section 4
参考：RFC 8144，第4节
Notes: This preference is only intended to be used with HTTP methods whose definitions explicitly provide support for the Depth [RFC4918] header field. Furthermore, this preference only applies when the Depth header field has a value of "1" or "infinity" (either implicitly or explicitly).
注意：此首选项仅用于HTTP方法，这些方法的定义明确支持深度[RFC4918]头字段。此外，此首选项仅在深度标头字段的值为“1”或“无穷大”（隐式或显式）时适用。
The following methods have had their references updated in the "HTTP Method Registry" (http://www.iana.org/assignments/http-methods).
下列方法的引用已在“HTTP方法注册表”中更新(http://www.iana.org/assignments/http-methods).
+------------+------+------------+----------------------------------+
| Method | Safe | Idempotent | References |
| Name | | | |
+------------+------+------------+----------------------------------+
| MKCALENDAR | no | yes | RFC 4791, Section 5.3.1; RFC |
| | | | 8144, Section 2.3 |
| MKCOL | no | yes | RFC 4918, Section 9.3; RFC 5689, |
| | | | Section 3; RFC 8144, Section 2.3 |
| PROPFIND | yes | yes | RFC 4918, Section 9.1; RFC 8144, |
| | | | Section 2.1 |
| PROPPATCH | no | yes | RFC 4918, Section 9.2; RFC 8144, |
| | | | Section 2.2 |
| REPORT | yes | yes | RFC 3253, Section 3.6; RFC 8144, |
| | | | Section 2.1 |
+------------+------+------------+----------------------------------+
+------------+------+------------+----------------------------------+
| Method | Safe | Idempotent | References |
| Name | | | |
+------------+------+------------+----------------------------------+
| MKCALENDAR | no | yes | RFC 4791, Section 5.3.1; RFC |
| | | | 8144, Section 2.3 |
| MKCOL | no | yes | RFC 4918, Section 9.3; RFC 5689, |
| | | | Section 3; RFC 8144, Section 2.3 |
| PROPFIND | yes | yes | RFC 4918, Section 9.1; RFC 8144, |
| | | | Section 2.1 |
| PROPPATCH | no | yes | RFC 4918, Section 9.2; RFC 8144, |
| | | | Section 2.2 |
| REPORT | yes | yes | RFC 3253, Section 3.6; RFC 8144, |
| | | | Section 2.1 |
+------------+------+------------+----------------------------------+
The following status code has had its references updated in the "HTTP Status Codes" registry (http://www.iana.org/assignments/http-status-codes).
以下状态代码的引用已在“HTTP状态代码”注册表中更新(http://www.iana.org/assignments/http-status-codes).
+-------+-------------------+---------------------------------------+
| Value | Description | References |
+-------+-------------------+---------------------------------------+
| 412 | Precondition | RFC 7232, Section 4.2; RFC 8144, |
| | Failed | Section 3.2 |
+-------+-------------------+---------------------------------------+
+-------+-------------------+---------------------------------------+
| Value | Description | References |
+-------+-------------------+---------------------------------------+
| 412 | Precondition | RFC 7232, Section 4.2; RFC 8144, |
| | Failed | Section 3.2 |
+-------+-------------------+---------------------------------------+
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，DOI 10.17487/RFC2119，1997年3月<http://www.rfc-editor.org/info/rfc2119>.
[RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. Whitehead, "Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)", RFC 3253, DOI 10.17487/RFC3253, March 2002, <http://www.rfc-editor.org/info/rfc3253>.
[RFC3253]Clemm，G.，Amsden，J.，Ellison，T.，Kaler，C.，和J.Whitehead，“WebDAV的版本控制扩展（Web分布式创作和版本控制）”，RFC 3253，DOI 10.17487/RFC3253，2002年3月<http://www.rfc-editor.org/info/rfc3253>.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, March 2007, <http://www.rfc-editor.org/info/rfc4791>.
[RFC4791]Daboo，C.，Desruisseaux，B.，和L.Dusseault，“WebDAV（CalDAV）日历扩展”，RFC 4791，DOI 10.17487/RFC47912007年3月<http://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, <http://www.rfc-editor.org/info/rfc4918>.
[RFC4918]Dusseault，L.，Ed.“Web分布式创作和版本控制（WebDAV）的HTTP扩展”，RFC 4918，DOI 10.17487/RFC4918，2007年6月<http://www.rfc-editor.org/info/rfc4918>.
[RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring and Versioning (WebDAV)", RFC 5689, DOI 10.17487/RFC5689, September 2009, <http://www.rfc-editor.org/info/rfc5689>.
[RFC5689]Daboo，C.，“用于Web分布式创作和版本控制（WebDAV）的扩展MKCOL”，RFC 5689，DOI 10.17487/RFC5689，2009年9月<http://www.rfc-editor.org/info/rfc5689>.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, March 2010, <http://www.rfc-editor.org/info/rfc5789>.
[RFC5789]Dusseault，L.和J.Snell，“HTTP的补丁方法”，RFC 5789，DOI 10.17487/RFC5789，2010年3月<http://www.rfc-editor.org/info/rfc5789>.
[RFC5995] Reschke, J., "Using POST to Add Members to Web Distributed Authoring and Versioning (WebDAV) Collections", RFC 5995, DOI 10.17487/RFC5995, September 2010, <http://www.rfc-editor.org/info/rfc5995>.
[RFC5995]Reschke，J.，“使用POST向Web分布式创作和版本控制（WebDAV）集合添加成员”，RFC 5995，DOI 10.17487/RFC5995，2010年9月<http://www.rfc-editor.org/info/rfc5995>.
[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, <http://www.rfc-editor.org/info/rfc7231>.
[RFC7231]Fielding，R.，Ed.和J.Reschke，Ed.，“超文本传输协议（HTTP/1.1）：语义和内容”，RFC 7231，DOI 10.17487/RFC72312014年6月<http://www.rfc-editor.org/info/rfc7231>.
[RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests", RFC 7232, DOI 10.17487/RFC7232, June 2014, <http://www.rfc-editor.org/info/rfc7232>.
[RFC7232]Fielding，R.，Ed.和J.Reschke，Ed.，“超文本传输协议（HTTP/1.1）：有条件请求”，RFC 7232，DOI 10.17487/RFC72322014年6月<http://www.rfc-editor.org/info/rfc7232>.
[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, DOI 10.17487/RFC7240, June 2014, <http://www.rfc-editor.org/info/rfc7240>.
[RFC7240]Snell，J.，“HTTP的首选标头”，RFC 7240，DOI 10.17487/RFC7240，2014年6月<http://www.rfc-editor.org/info/rfc7240>.
[MSDN.aa493854] Microsoft Developer Network, "PROPPATCH Method", June 2006, <http://msdn.microsoft.com/en-us/library/aa493854.aspx>.
[MSDN.aa493854]微软开发者网络，“PROPPATCH方法”，2006年6月<http://msdn.microsoft.com/en-us/library/aa493854.aspx>.
[MSDN.aa563501] Microsoft Developer Network, "Brief Header", June 2006, <http://msdn.microsoft.com/en-us/library/aa563501.aspx>.
[MSDN.aa563501]微软开发者网络，“简要标题”，2006年6月<http://msdn.microsoft.com/en-us/library/aa563501.aspx>.
[MSDN.aa563950] Microsoft Developer Network, "Depth Header", June 2006, <http://msdn.microsoft.com/en-us/library/aa563950.aspx>.
[MSDN.aa563950]微软开发者网络，“深度标题”，2006年6月<http://msdn.microsoft.com/en-us/library/aa563950.aspx>.
[MSDN.aa580336] Microsoft Developer Network, "PROPFIND Method", June 2006, <http://msdn.microsoft.com/en-us/library/aa580336.aspx>.
[MSDN.aa580336]微软开发者网络，“PROPFIND方法”，2006年6月<http://msdn.microsoft.com/en-us/library/aa580336.aspx>.
[RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol", RFC 3744, DOI 10.17487/RFC3744, May 2004, <http://www.rfc-editor.org/info/rfc3744>.
[RFC3744]Clemm，G.，Reschke，J.，Sedlar，E.，和J.Whitehead，“Web分布式创作和版本控制（WebDAV）访问控制协议”，RFC 3744，DOI 10.17487/RFC3744，2004年5月<http://www.rfc-editor.org/info/rfc3744>.
[RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)", RFC 6352, DOI 10.17487/RFC6352, August 2011, <http://www.rfc-editor.org/info/rfc6352>.
[RFC6352]Daboo，C.，“CardDAV:vCard对Web分布式创作和版本控制（WebDAV）的扩展”，RFC 6352，DOI 10.17487/RFC6352，2011年8月<http://www.rfc-editor.org/info/rfc6352>.
[RFC6578] Daboo, C. and A. Quillaud, "Collection Synchronization for Web Distributed Authoring and Versioning (WebDAV)", RFC 6578, DOI 10.17487/RFC6578, March 2012, <http://www.rfc-editor.org/info/rfc6578>.
[RFC6578]Daboo，C.和A.Quillaud，“Web分布式创作和版本控制（WebDAV）的集合同步”，RFC 6578，DOI 10.17487/RFC6578，2012年3月<http://www.rfc-editor.org/info/rfc6578>.
[RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, <http://www.rfc-editor.org/info/rfc6638>.
[RFC6638]Daboo，C.和B.Desruisseaux，“CalDAV的计划扩展”，RFC 6638，DOI 10.17487/RFC6638，2012年6月<http://www.rfc-editor.org/info/rfc6638>.
This document is based heavily on the Brief [MSDN.aa563501] and extended Depth [MSDN.aa563950] header fields. The behaviors described in Sections 2.1 and 2.2 are identical to those provided by the Brief header field when used with the PROPFIND [MSDN.aa580336] and PROPPATCH [MSDN.aa493854] methods, respectively. The behavior described in Section 4 is identical to that provided by the "1,noroot" [MSDN.aa563950] and "infinity,noroot" [MSDN.aa563950] Depth header field values.
本文档主要基于简短[MSDN.aa563501]和扩展深度[MSDN.aa563950]标题字段。第2.1节和第2.2节中描述的行为与分别与PROPFIND[MSDN.aa580336]和PROPPATCH[MSDN.aa493854]方法一起使用时简短标题字段提供的行为相同。第4节中描述的行为与“1，noroot”[MSDN.aa563950]和“infinity，noroot”[MSDN.aa563950]深度标题字段值提供的行为相同。
Client and server implementations that already support the Brief header field can add support for the "return=minimal" preference with nominal effort.
已经支持“简短标题”字段的客户端和服务器实现可以添加对“return=minimal”首选项的支持，只需付出名义上的努力。
If a server supporting the Prefer header field receives both the Brief and Prefer header fields in a request, clients can expect the server to ignore the Brief header field and only use the Prefer header field preferences.
如果支持首选标头字段的服务器在请求中同时接收到简短和首选标头字段，则客户端可以期望服务器忽略简短标头字段，而只使用首选标头字段首选项。
This example tries to fetch one known and one unknown property from child resources.
此示例尝试从子资源中获取一个已知和一个未知属性。
>> Request <<
>> Request <<
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 189
Depth: 1
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 189
Depth: 1
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<D:resourcetype/>
<X:foobar/>
</D:prop>
</D:propfind>
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<D:resourcetype/>
<X:foobar/>
</D:prop>
</D:propfind>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
HTTP/1.1 207多状态
Content-Type: application/xml; charset=utf-8
Content-Length: 1722
Content-Type: application/xml; charset=utf-8
Content-Length: 1722
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:X="http://ns.example.com/foobar/">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/work/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/home/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:X="http://ns.example.com/foobar/">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/work/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/home/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/foo.txt</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</D:multistatus>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/foo.txt</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</D:multistatus>
This example tries to fetch one known and one unknown property from child resources only.
此示例仅尝试从子资源获取一个已知和一个未知属性。
>> Request <<
>> Request <<
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 189
Depth: 1
Prefer: return=minimal, depth-noroot
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 189
Depth: 1
Prefer: return=minimal, depth-noroot
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<D:resourcetype/>
<X:foobar/>
</D:prop>
</D:propfind>
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<D:resourcetype/>
<X:foobar/>
</D:prop>
</D:propfind>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 837
Preference-Applied: return=minimal, depth-noroot
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 837
Preference-Applied: return=minimal, depth-noroot
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/work/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/home/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/foo.txt</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/work/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/home/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/container/foo.txt</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
B.1.3. Minimal PROPFIND Request/Response with an Empty DAV:propstat Element
B.1.3. 具有空DAV:propstat元素的最小PROPFIND请求/响应
This example tries to fetch an unknown property from a collection.
此示例尝试从集合中获取未知属性。
>> Request <<
>> Request <<
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 166
Prefer: return=minimal
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 166
Prefer: return=minimal
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<X:foobar/>
</D:prop>
</D:propfind>
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<X:foobar/>
</D:prop>
</D:propfind>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 255
Preference-Applied: return=minimal
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 255
Preference-Applied: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop/>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop/>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
This example tries to fetch an unknown property from several resources via the DAV:expand-property [RFC3253] REPORT type.
此示例尝试通过DAV:expand property[RFC3253]报告类型从多个资源中获取未知属性。
>> Request <<
>> Request <<
REPORT /dav/principals/ HTTP/1.1
REPORT /dav/principals/ HTTP/1.1
Host: webdav.example.com
Content-type: text/xml; charset=utf-8
Content-length: 847
Host: webdav.example.com
Content-type: text/xml; charset=utf-8
Content-length: 847
<?xml version="1.0" encoding="utf-8"?>
<D:expand-property xmlns:D="DAV:">
<D:property name="current-user-principal">
<D:property name="resourcetype"/>
<D:property name="displayname"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
<D:property name="calendar-home-set"
namespace="urn:ietf:params:xml:ns:caldav">
<D:property name="resourcetype"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
</D:property>
<D:property name="addressbook-home-set"
namespace="urn:ietf:params:xml:ns:carddav">
<D:property name="resourcetype"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
</D:property>
</D:property>
</D:expand-property>
<?xml version="1.0" encoding="utf-8"?>
<D:expand-property xmlns:D="DAV:">
<D:property name="current-user-principal">
<D:property name="resourcetype"/>
<D:property name="displayname"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
<D:property name="calendar-home-set"
namespace="urn:ietf:params:xml:ns:caldav">
<D:property name="resourcetype"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
</D:property>
<D:property name="addressbook-home-set"
namespace="urn:ietf:params:xml:ns:carddav">
<D:property name="resourcetype"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
</D:property>
</D:property>
</D:expand-property>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 2664
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 2664
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav"
xmlns:R="urn:ietf:params:xml:ns:carddav"
xmlns:X="http://ns.example.com/foobar">
<D:response>
<D:href>/dav/principals/</D:href>
<D:propstat>
<D:prop>
<D:current-user-principal>
<D:response>
<D:href>/dav/principals/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:principal/>
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav"
xmlns:R="urn:ietf:params:xml:ns:carddav"
xmlns:X="http://ns.example.com/foobar">
<D:response>
<D:href>/dav/principals/</D:href>
<D:propstat>
<D:prop>
<D:current-user-principal>
<D:response>
<D:href>/dav/principals/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:principal/>
</D:resourcetype>
<D:displayname>ken</D:displayname>
<C:calendar-home-set>
<D:response>
<D:href>/dav/calendars/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</C:calendar-home-set>
<R:addressbook-home-set>
<D:response>
<D:href>/dav/addressbooks/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</R:addressbook-home-set>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:resourcetype>
<D:displayname>ken</D:displayname>
<C:calendar-home-set>
<D:response>
<D:href>/dav/calendars/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</C:calendar-home-set>
<R:addressbook-home-set>
<D:response>
<D:href>/dav/addressbooks/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</R:addressbook-home-set>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</D:current-user-principal>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
</D:propstat>
</D:response>
</D:current-user-principal>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
This example tries to fetch an unknown property from several resources via the DAV:expand-property [RFC3253] REPORT type.
此示例尝试通过DAV:expand property[RFC3253]报告类型从多个资源中获取未知属性。
>> Request <<
>> Request <<
REPORT /dav/principals/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 847
Prefer: return=minimal
REPORT /dav/principals/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 847
Prefer: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:expand-property xmlns:D="DAV:">
<D:property name="current-user-principal">
<D:property name="resourcetype"/>
<D:property name="displayname"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
<D:property name="calendar-home-set"
namespace="urn:ietf:params:xml:ns:caldav">
<D:property name="resourcetype"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
</D:property>
<D:property name="addressbook-home-set"
namespace="urn:ietf:params:xml:ns:carddav">
<D:property name="resourcetype"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
</D:property>
</D:property>
</D:expand-property>
<?xml version="1.0" encoding="utf-8"?>
<D:expand-property xmlns:D="DAV:">
<D:property name="current-user-principal">
<D:property name="resourcetype"/>
<D:property name="displayname"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
<D:property name="calendar-home-set"
namespace="urn:ietf:params:xml:ns:caldav">
<D:property name="resourcetype"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
</D:property>
<D:property name="addressbook-home-set"
namespace="urn:ietf:params:xml:ns:carddav">
<D:property name="resourcetype"/>
<D:property name="foobar"
namespace="http://ns.example.com/foobar"/>
</D:property>
</D:property>
</D:expand-property>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 1998 Preference-Applied: return=minimal
内容长度：1998应用的首选项：返回=最小值
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav"
xmlns:R="urn:ietf:params:xml:ns:carddav"
xmlns:X="http://ns.example.com/foobar">
<D:response>
<D:href>/dav/principals/</D:href>
<D:propstat>
<D:prop>
<D:current-user-principal>
<D:response>
<D:href>/dav/principals/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:principal/>
</D:resourcetype>
<D:displayname>ken</D:displayname>
<C:calendar-home-set>
<D:response>
<D:href>/dav/calendars/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</C:calendar-home-set>
<R:addressbook-home-set>
<D:response>
<D:href>/dav/addressbooks/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</R:addressbook-home-set>
</D:prop>
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav"
xmlns:R="urn:ietf:params:xml:ns:carddav"
xmlns:X="http://ns.example.com/foobar">
<D:response>
<D:href>/dav/principals/</D:href>
<D:propstat>
<D:prop>
<D:current-user-principal>
<D:response>
<D:href>/dav/principals/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:principal/>
</D:resourcetype>
<D:displayname>ken</D:displayname>
<C:calendar-home-set>
<D:response>
<D:href>/dav/calendars/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</C:calendar-home-set>
<R:addressbook-home-set>
<D:response>
<D:href>/dav/addressbooks/user/ken/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</R:addressbook-home-set>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:current-user-principal>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:current-user-principal>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
>> Request <<
>> Request <<
PROPPATCH /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 199
PROPPATCH /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 199
<?xml version="1.0" encoding="utf-8"?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:propertyupdate>
<?xml version="1.0" encoding="utf-8"?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:propertyupdate>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 297
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: 297
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop>
<D:displayname/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop>
<D:displayname/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
>> Request <<
>> Request <<
PROPPATCH /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 199
Prefer: return=minimal
PROPPATCH /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 199
Prefer: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:propertyupdate>
<?xml version="1.0" encoding="utf-8"?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:propertyupdate>
>> Response <<
>> Response <<
HTTP/1.1 200 OK Content-Length: 0 Preference-Applied: return=minimal
HTTP/1.1 200 OK内容长度：应用0首选项：返回=最小值
>> Request <<
>> Request <<
MKCOL /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 181
MKCOL /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 181
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:mkcol>
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:mkcol>
>> Response <<
>> Response <<
HTTP/1.1 201 Created
HTTP/1.1201已创建
Cache-Control: no-cache
Content-Type: application/xml; charset=utf-8
Content-Length: 224
Cache-Control: no-cache
Content-Type: application/xml; charset=utf-8
Content-Length: 224
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol-response xmlns:D="DAV:">
<D:propstat>
<D:prop>
<D:displayname/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:mkcol-response>
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol-response xmlns:D="DAV:">
<D:propstat>
<D:prop>
<D:displayname/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:mkcol-response>
>> Request <<
>> Request <<
MKCOL /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 181
Prefer: return=minimal
MKCOL /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: 181
Prefer: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:mkcol>
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:mkcol>
>> Response <<
>> Response <<
HTTP/1.1 201 Created Cache-Control: no-cache Content-Length: 0 Preference-Applied: return=minimal
HTTP/1.1 201已创建缓存控制：无缓存内容长度：应用0首选项：返回=最小值
Note that this request is not conditional because by using the POST [RFC5995] method, the client lets the server choose the resource URI, thereby guaranteeing that it will not modify an existing resource.
请注意，此请求不是有条件的，因为通过使用POST[RFC5995]方法，客户端允许服务器选择资源URI，从而保证它不会修改现有资源。
>> Request <<
>> Request <<
POST /container/work;add-member/ HTTP/1.1
Host: caldav.example.com
Content-Type: text/calendar; charset=utf-8
Content-Length: 521
POST /container/work;add-member/ HTTP/1.1
Host: caldav.example.com
Content-Type: text/calendar; charset=utf-8
Content-Length: 521
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185254Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@
example.com
END:VEVENT
END:VCALENDAR
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185254Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@
example.com
END:VEVENT
END:VCALENDAR
>> Response <<
>> Response <<
HTTP/1.1 201 Created
Location: /container/work/abc.ics
Content-Length: 0
HTTP/1.1 201 Created
Location: /container/work/abc.ics
Content-Length: 0
Note that the server did not include any validator header fields (e.g., ETag) in the response, signaling that the created representation differs from the representation sent in the body of the request. The client has to send a separate GET request to retrieve the current representation:
请注意，服务器在响应中没有包含任何验证器头字段（例如ETag），这表明创建的表示不同于请求主体中发送的表示。客户端必须发送单独的GET请求以检索当前表示：
>> Request <<
>> Request <<
GET /container/work/abc.ics HTTP/1.1
Host: caldav.example.com
GET /container/work/abc.ics HTTP/1.1
Host: caldav.example.com
>> Response <<
>> Response <<
HTTP/1.1 200 OK
HTTP/1.1200ok
Content-Type: text/calendar; charset=utf-8
Content-Length: 541
ETag: "nahduyejc"
Schedule-Tag: "jfd84hgbcn"
Content-Type: text/calendar; charset=utf-8
Content-Length: 541
ETag: "nahduyejc"
Schedule-Tag: "jfd84hgbcn"
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185300Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS=
1.2:mailto:jdoe@example.com
END:VEVENT
END:VCALENDAR
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185300Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS=
1.2:mailto:jdoe@example.com
END:VEVENT
END:VCALENDAR
Note that this request is not conditional because by using the POST [RFC5995] method, the client lets the server choose the resource URI, thereby guaranteeing that it will not modify an existing resource.
请注意，此请求不是有条件的，因为通过使用POST[RFC5995]方法，客户端允许服务器选择资源URI，从而保证它不会修改现有资源。
>> Request <<
>> Request <<
POST /container/work;add-member/ HTTP/1.1
Host: caldav.example.com
Content-Type: text/calendar; charset=utf-8
Content-Length: 521
Prefer: return=representation
POST /container/work;add-member/ HTTP/1.1
Host: caldav.example.com
Content-Type: text/calendar; charset=utf-8
Content-Length: 521
Prefer: return=representation
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185254Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185254Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@
example.com
END:VEVENT
END:VCALENDAR
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@
example.com
END:VEVENT
END:VCALENDAR
>> Response <<
>> Response <<
HTTP/1.1 201 Created
Location: /container/work/abc.ics
Content-Type: text/calendar; charset=utf-8
Content-Length: 541
Content-Location: /container/work/abc.ics
ETag: "nahduyejc"
Schedule-Tag: "jfd84hgbcn"
Preference-Applied: return=representation
HTTP/1.1 201 Created
Location: /container/work/abc.ics
Content-Type: text/calendar; charset=utf-8
Content-Length: 541
Content-Location: /container/work/abc.ics
ETag: "nahduyejc"
Schedule-Tag: "jfd84hgbcn"
Preference-Applied: return=representation
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185300Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS=
1.2:mailto:jdoe@example.com
END:VEVENT
END:VCALENDAR
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185300Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS=
1.2:mailto:jdoe@example.com
END:VEVENT
END:VCALENDAR
B.6.1. Typical Conditional Resource Update Failure and Retrieval via PUT + GET
B.6.1. 典型的条件资源更新失败和通过PUT+GET检索
>> Request <<
>> Request <<
PUT /container/motd.txt HTTP/1.1
Host: dav.example.com
Content-Type: text/plain
Content-Length: 69
If-Match: "asd973"
PUT /container/motd.txt HTTP/1.1
Host: dav.example.com
Content-Type: text/plain
Content-Length: 69
If-Match: "asd973"
Either write something worth reading or do something worth writing.
要么写一些值得读的东西，要么做一些值得写的事情。
>> Response <<
>> Response <<
HTTP/1.1 412 Precondition Failed Content-Length: 0
HTTP/1.1 412前置条件失败的内容长度：0
The resource has been modified by another user agent (ETag mismatch); therefore, the client has to send a separate GET request to retrieve the current representation:
资源已被另一个用户代理修改（ETag不匹配）；因此，客户端必须发送单独的GET请求来检索当前表示：
>> Request <<
>> Request <<
GET /container/motd.txt HTTP/1.1
Host: dav.example.com
GET /container/motd.txt HTTP/1.1
Host: dav.example.com
>> Response <<
>> Response <<
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 52
ETag: "789sdas"
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 52
ETag: "789sdas"
An investment in knowledge pays the best interest.
对知识的投资回报最大。
B.6.2. Streamlined Conditional Resource Update Failure and Retrieval via PUT
B.6.2. 通过PUT简化条件资源更新失败和检索
>> Request <<
>> Request <<
PUT /container/motd.txt HTTP/1.1
Host: dav.example.com
Content-Type: text/plain
PUT /container/motd.txt HTTP/1.1
Host: dav.example.com
Content-Type: text/plain
Content-Length: 69 If-Match: "asd973" Prefer: return=representation
内容长度：69如果匹配：“asd973”首选：返回=表示
Either write something worth reading or do something worth writing.
要么写一些值得读的东西，要么做一些值得写的事情。
>> Response <<
>> Response <<
HTTP/1.1 412 Precondition Failed
Content-Type: text/plain
Content-Length: 52
Content-Location: /container/motd.txt
ETag: "789sdas"
Preference-Applied: return=representation
HTTP/1.1 412 Precondition Failed
Content-Type: text/plain
Content-Length: 52
Content-Location: /container/motd.txt
ETag: "789sdas"
Preference-Applied: return=representation
An investment in knowledge pays the best interest.
对知识的投资回报最大。
Acknowledgements
致谢
The author would like to thank the following individuals for contributing their ideas and support for writing this specification: Cyrus Daboo, Helge Hess, Andrew McMillan, Arnaud Quillaud, and Julian Reschke.
作者要感谢以下个人为编写本规范贡献了他们的想法和支持：Cyrus Daboo、Helge Hess、Andrew McMillan、Arnaud Quillaud和Julian Reschke。
The author would also like to thank the Calendaring and Scheduling Consortium for advice with this specification and for organizing interoperability testing events to help refine it.
作者还想感谢日历和日程安排联盟对本规范的建议，以及组织互操作性测试活动以帮助完善本规范。
Author's Address
作者地址
Kenneth Murchison Carnegie Mellon University 5000 Forbes Avenue Pittsburgh, PA 15213 United States of America
肯尼斯·默奇森卡内基·梅隆大学美国宾夕法尼亚州匹兹堡福布斯大道5000号，邮编15213
Phone: +1-412-268-1982
Email: murch@andrew.cmu.edu
Phone: +1-412-268-1982
Email: murch@andrew.cmu.edu