Internet Engineering Task Force (IETF) C. Daboo
Request for Comments: 6352 Apple
Category: Standards Track August 2011
ISSN: 2070-1721
Internet Engineering Task Force (IETF) C. Daboo
Request for Comments: 6352 Apple
Category: Standards Track August 2011
ISSN: 2070-1721
CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)
CardDAV:Web分布式创作和版本控制（WebDAV）的vCard扩展
Abstract
摘要
This document defines extensions to the Web Distributed Authoring and Versioning (WebDAV) protocol to specify a standard way of accessing, managing, and sharing contact information based on the vCard format.
本文档定义了Web分布式创作和版本控制（WebDAV）协议的扩展，以指定基于vCard格式访问、管理和共享联系人信息的标准方式。
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 5741.
本文件是互联网工程任务组（IETF）的产品。它代表了IETF社区的共识。它已经接受了公众审查，并已被互联网工程指导小组（IESG）批准出版。有关互联网标准的更多信息，请参见RFC 5741第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/rfc6352.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc6352.
Copyright Notice
版权公告
Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有（c）2011 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许可证中所述的无担保。
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow
本文件可能包含2008年11月10日之前发布或公开的IETF文件或IETF贡献中的材料。控制某些材料版权的人可能没有授予IETF信托允许的权利
modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.
在IETF标准过程之外修改此类材料。在未从控制此类材料版权的人员处获得充分许可的情况下，不得在IETF标准流程之外修改本文件，也不得在IETF标准流程之外创建其衍生作品，除了将其格式化以RFC形式发布或将其翻译成英语以外的其他语言。
Table of Contents
目录
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6
4. Address Book Data Model . . . . . . . . . . . . . . . . . . . 7
4.1. Address Book Server . . . . . . . . . . . . . . . . . . . 7
5. Address Book Resources . . . . . . . . . . . . . . . . . . . . 7
5.1. Address Object Resources . . . . . . . . . . . . . . . . . 7
5.1.1. Data Type Conversion . . . . . . . . . . . . . . . . . 8
5.1.1.1. Additional Precondition for GET . . . . . . . . . 8
5.2. Address Book Collections . . . . . . . . . . . . . . . . . 9
6. Address Book Feature . . . . . . . . . . . . . . . . . . . . . 10
6.1. Address Book Support . . . . . . . . . . . . . . . . . . . 10
6.1.1. Example: Using OPTIONS for the Discovery of
Support for CardDAV . . . . . . . . . . . . . . . . . 10
6.2. Address Book Properties . . . . . . . . . . . . . . . . . 10
6.2.1. CARDDAV:addressbook-description Property . . . . . . . 10
6.2.2. CARDDAV:supported-address-data Property . . . . . . . 11
6.2.3. CARDDAV:max-resource-size Property . . . . . . . . . . 12
6.3. Creating Resources . . . . . . . . . . . . . . . . . . . . 13
6.3.1. Extended MKCOL Method . . . . . . . . . . . . . . . . 13
6.3.1.1. Example - Successful MKCOL Request . . . . . . . . 14
6.3.2. Creating Address Object Resources . . . . . . . . . . 15
6.3.2.1. Additional Preconditions for PUT, COPY, and
MOVE . . . . . . . . . . . . . . . . . . . . . . . 16
6.3.2.2. Non-Standard vCard Properties and Parameters . . . 17
6.3.2.3. Address Object Resource Entity Tag . . . . . . . . 18
7. Address Book Access Control . . . . . . . . . . . . . . . . . 18
7.1. Additional Principal Properties . . . . . . . . . . . . . 18
7.1.1. CARDDAV:addressbook-home-set Property . . . . . . . . 19
7.1.2. CARDDAV:principal-address Property . . . . . . . . . . 19
8. Address Book Reports . . . . . . . . . . . . . . . . . . . . . 20
8.1. REPORT Method . . . . . . . . . . . . . . . . . . . . . . 20
8.2. Ordinary Collections . . . . . . . . . . . . . . . . . . . 21
8.3. Searching Text: Collations . . . . . . . . . . . . . . . . 21
8.3.1. CARDDAV:supported-collation-set Property . . . . . . . 22
8.4. Partial Retrieval . . . . . . . . . . . . . . . . . . . . 23
8.5. Non-Standard Properties and Parameters . . . . . . . . . . 23
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6
4. Address Book Data Model . . . . . . . . . . . . . . . . . . . 7
4.1. Address Book Server . . . . . . . . . . . . . . . . . . . 7
5. Address Book Resources . . . . . . . . . . . . . . . . . . . . 7
5.1. Address Object Resources . . . . . . . . . . . . . . . . . 7
5.1.1. Data Type Conversion . . . . . . . . . . . . . . . . . 8
5.1.1.1. Additional Precondition for GET . . . . . . . . . 8
5.2. Address Book Collections . . . . . . . . . . . . . . . . . 9
6. Address Book Feature . . . . . . . . . . . . . . . . . . . . . 10
6.1. Address Book Support . . . . . . . . . . . . . . . . . . . 10
6.1.1. Example: Using OPTIONS for the Discovery of
Support for CardDAV . . . . . . . . . . . . . . . . . 10
6.2. Address Book Properties . . . . . . . . . . . . . . . . . 10
6.2.1. CARDDAV:addressbook-description Property . . . . . . . 10
6.2.2. CARDDAV:supported-address-data Property . . . . . . . 11
6.2.3. CARDDAV:max-resource-size Property . . . . . . . . . . 12
6.3. Creating Resources . . . . . . . . . . . . . . . . . . . . 13
6.3.1. Extended MKCOL Method . . . . . . . . . . . . . . . . 13
6.3.1.1. Example - Successful MKCOL Request . . . . . . . . 14
6.3.2. Creating Address Object Resources . . . . . . . . . . 15
6.3.2.1. Additional Preconditions for PUT, COPY, and
MOVE . . . . . . . . . . . . . . . . . . . . . . . 16
6.3.2.2. Non-Standard vCard Properties and Parameters . . . 17
6.3.2.3. Address Object Resource Entity Tag . . . . . . . . 18
7. Address Book Access Control . . . . . . . . . . . . . . . . . 18
7.1. Additional Principal Properties . . . . . . . . . . . . . 18
7.1.1. CARDDAV:addressbook-home-set Property . . . . . . . . 19
7.1.2. CARDDAV:principal-address Property . . . . . . . . . . 19
8. Address Book Reports . . . . . . . . . . . . . . . . . . . . . 20
8.1. REPORT Method . . . . . . . . . . . . . . . . . . . . . . 20
8.2. Ordinary Collections . . . . . . . . . . . . . . . . . . . 21
8.3. Searching Text: Collations . . . . . . . . . . . . . . . . 21
8.3.1. CARDDAV:supported-collation-set Property . . . . . . . 22
8.4. Partial Retrieval . . . . . . . . . . . . . . . . . . . . 23
8.5. Non-Standard Properties and Parameters . . . . . . . . . . 23
8.6. CARDDAV:addressbook-query Report . . . . . . . . . . . . . 23
8.6.1. Limiting Results . . . . . . . . . . . . . . . . . . . 25
8.6.2. Truncation of Results . . . . . . . . . . . . . . . . 25
8.6.3. Example: Partial Retrieval of vCards Matching
NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 26
8.6.4. Example: Partial Retrieval of vCards Matching a
Full Name or Email Address . . . . . . . . . . . . . . 27
8.6.5. Example: Truncated Results . . . . . . . . . . . . . . 29
8.7. CARDDAV:addressbook-multiget Report . . . . . . . . . . . 31
8.7.1. Example: CARDDAV:addressbook-multiget Report . . . . . 32
8.7.2. Example: CARDDAV:addressbook-multiget Report . . . . . 33
9. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . 34
9.1. Restrict the Properties Returned . . . . . . . . . . . . . 34
9.2. Avoiding Lost Updates . . . . . . . . . . . . . . . . . . 35
9.3. Client Configuration . . . . . . . . . . . . . . . . . . . 35
9.4. Finding Other Users' Address Books . . . . . . . . . . . . 35
10. XML Element Definitions . . . . . . . . . . . . . . . . . . . 36
10.1. CARDDAV:addressbook XML Element . . . . . . . . . . . . . 36
10.2. CARDDAV:supported-collation XML Element . . . . . . . . . 36
10.3. CARDDAV:addressbook-query XML Element . . . . . . . . . . 37
10.4. CARDDAV:address-data XML Element . . . . . . . . . . . . . 37
10.4.1. CARDDAV:allprop XML Element . . . . . . . . . . . . . 39
10.4.2. CARDDAV:prop XML Element . . . . . . . . . . . . . . . 39
10.5. CARDDAV:filter XML Element . . . . . . . . . . . . . . . . 40
10.5.1. CARDDAV:prop-filter XML Element . . . . . . . . . . . 40
10.5.2. CARDDAV:param-filter XML Element . . . . . . . . . . . 41
10.5.3. CARDDAV:is-not-defined XML Element . . . . . . . . . . 42
10.5.4. CARDDAV:text-match XML Element . . . . . . . . . . . . 42
10.6. CARDDAV:limit XML Element . . . . . . . . . . . . . . . . 43
10.6.1. CARDDAV:nresults XML Element . . . . . . . . . . . . . 44
10.7. CARDDAV:addressbook-multiget XML Element . . . . . . . . . 44
11. Service Discovery via SRV Records . . . . . . . . . . . . . . 45
12. Internationalization Considerations . . . . . . . . . . . . . 45
13. Security Considerations . . . . . . . . . . . . . . . . . . . 45
14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 46
14.1. Namespace Registration . . . . . . . . . . . . . . . . . . 46
15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 47
16.1. Normative References . . . . . . . . . . . . . . . . . . . 47
16.2. Informative References . . . . . . . . . . . . . . . . . . 48
8.6. CARDDAV:addressbook-query Report . . . . . . . . . . . . . 23
8.6.1. Limiting Results . . . . . . . . . . . . . . . . . . . 25
8.6.2. Truncation of Results . . . . . . . . . . . . . . . . 25
8.6.3. Example: Partial Retrieval of vCards Matching
NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 26
8.6.4. Example: Partial Retrieval of vCards Matching a
Full Name or Email Address . . . . . . . . . . . . . . 27
8.6.5. Example: Truncated Results . . . . . . . . . . . . . . 29
8.7. CARDDAV:addressbook-multiget Report . . . . . . . . . . . 31
8.7.1. Example: CARDDAV:addressbook-multiget Report . . . . . 32
8.7.2. Example: CARDDAV:addressbook-multiget Report . . . . . 33
9. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . 34
9.1. Restrict the Properties Returned . . . . . . . . . . . . . 34
9.2. Avoiding Lost Updates . . . . . . . . . . . . . . . . . . 35
9.3. Client Configuration . . . . . . . . . . . . . . . . . . . 35
9.4. Finding Other Users' Address Books . . . . . . . . . . . . 35
10. XML Element Definitions . . . . . . . . . . . . . . . . . . . 36
10.1. CARDDAV:addressbook XML Element . . . . . . . . . . . . . 36
10.2. CARDDAV:supported-collation XML Element . . . . . . . . . 36
10.3. CARDDAV:addressbook-query XML Element . . . . . . . . . . 37
10.4. CARDDAV:address-data XML Element . . . . . . . . . . . . . 37
10.4.1. CARDDAV:allprop XML Element . . . . . . . . . . . . . 39
10.4.2. CARDDAV:prop XML Element . . . . . . . . . . . . . . . 39
10.5. CARDDAV:filter XML Element . . . . . . . . . . . . . . . . 40
10.5.1. CARDDAV:prop-filter XML Element . . . . . . . . . . . 40
10.5.2. CARDDAV:param-filter XML Element . . . . . . . . . . . 41
10.5.3. CARDDAV:is-not-defined XML Element . . . . . . . . . . 42
10.5.4. CARDDAV:text-match XML Element . . . . . . . . . . . . 42
10.6. CARDDAV:limit XML Element . . . . . . . . . . . . . . . . 43
10.6.1. CARDDAV:nresults XML Element . . . . . . . . . . . . . 44
10.7. CARDDAV:addressbook-multiget XML Element . . . . . . . . . 44
11. Service Discovery via SRV Records . . . . . . . . . . . . . . 45
12. Internationalization Considerations . . . . . . . . . . . . . 45
13. Security Considerations . . . . . . . . . . . . . . . . . . . 45
14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 46
14.1. Namespace Registration . . . . . . . . . . . . . . . . . . 46
15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 47
16.1. Normative References . . . . . . . . . . . . . . . . . . . 47
16.2. Informative References . . . . . . . . . . . . . . . . . . 48
Address books containing contact information are a key component of personal information management tools, such as email, calendaring and scheduling, and instant messaging clients. To date several protocols have been used for remote access to contact data, including the Lightweight Directory Access Protocol (LDAP) [RFC4510], Internet Message Support Protocol [IMSP], and Application Configuration Access Protocol (ACAP) [RFC2244], together with SyncML used for synchronization of such data.
包含联系人信息的通讯簿是个人信息管理工具（如电子邮件、日历和日程安排以及即时消息客户端）的关键组成部分。迄今为止，已经使用了几种协议来远程访问联系人数据，包括轻型目录访问协议（LDAP）[RFC4510]、互联网消息支持协议[IMSP]和应用程序配置访问协议（ACAP）[RFC2244]，以及用于同步此类数据的SyncML。
WebDAV [RFC4918] offers a number of advantages as a framework or basis for address book access and management. Most of these advantages boil down to a significant reduction in the costs of design, implementation, interoperability testing, and deployment.
WebDAV[RFC4918]作为通讯簿访问和管理的框架或基础，提供了许多优势。这些优势大多归结为显著降低了设计、实施、互操作性测试和部署的成本。
The key features of address book support with WebDAV are:
WebDAV支持通讯簿的主要功能包括：
1. Ability to use multiple address books with hierarchical layout.
1. 能够使用分层布局的多个通讯簿。
2. Ability to control access to individual address books and address entries as per WebDAV Access Control List (ACL) [RFC3744].
2. 能够根据WebDAV访问控制列表（ACL）[RFC3744]控制对单个通讯簿和地址项的访问。
3. Principal collections can be used to enumerate and query other users on the system as per WebDAV ACL [RFC3744].
3. 主体集合可用于根据WebDAV ACL[RFC3744]枚举和查询系统上的其他用户。
4. Server-side searching of address data, avoiding the need for clients to download an entire address book in order to do a quick address 'expansion' operation.
4. 服务器端搜索地址数据，避免客户端下载整个地址簿以执行快速地址“扩展”操作。
5. Well-defined internationalization support through WebDAV's use of XML.
5. 通过WebDAV使用XML提供定义良好的国际化支持。
6. Use of vCards [RFC2426] for well-defined address schema to enhance client interoperability.
6. 使用vCard[RFC2426]实现定义良好的地址模式，以增强客户端互操作性。
7. Many limited clients (e.g., mobile devices) contain an HTTP stack that makes implementing WebDAV much easier than other protocols.
7. 许多有限的客户端（例如，移动设备）包含HTTP堆栈，这使得实现WebDAV比其他协议更容易。
The key disadvantage of address book support in WebDAV is:
WebDAV中通讯簿支持的主要缺点是：
1. Lack of change notification. Many of the alternative protocols also lack this ability. However, an extension for push notifications could easily be developed.
1. 缺少更改通知。许多替代协议也缺乏这种能力。但是，推送通知的扩展很容易开发。
vCard is a MIME directory profile aimed at encapsulating personal addressing and contact information about people. The specification of vCard was originally done by the Versit consortium, with a
vCard是一个MIME目录配置文件，旨在封装有关人员的个人地址和联系信息。vCard的规格最初是由Version consortium完成的，具有
subsequent 3.0 version standardized by the IETF [RFC2426]. vCard is in widespread use in email clients and mobile devices as a means of encapsulating address information for transport via email or for import/export and synchronization operations.
IETF标准化的后续3.0版本[RFC2426]。vCard在电子邮件客户端和移动设备中广泛使用，作为封装地址信息的一种手段，用于通过电子邮件传输或用于导入/导出和同步操作。
An update to vCard -- vCard v4 -- is currently being developed [RFC6350] and is compatible with this specification.
目前正在开发vCard的更新版本vCard v4[RFC6350]，该版本与本规范兼容。
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]中所述进行解释。
The term "protected" is used in the Conformance field of property definitions as defined in Section 15 of [RFC4918].
术语“受保护”用于[RFC4918]第15节中定义的属性定义的一致性字段。
This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 3.2) as a purely notational convention. WebDAV request and response bodies cannot be validated by a DTD due to the specific extensibility rules defined in Section 17 of [RFC4918] and due to the fact that all XML elements defined by that specification use the XML namespace name "DAV:". In particular:
本文档使用XML DTD片段（[W3C.REC-XML-20081126]，第3.2节）作为纯粹的符号约定。由于[RFC4918]第17节中定义的特定扩展性规则以及该规范定义的所有XML元素都使用XML命名空间名称“DAV:”，DTD无法验证WebDAV请求和响应主体。特别地：
1. Element names use the "DAV:" namespace.
1. 元素名称使用“DAV:”名称空间。
2. Element ordering is irrelevant unless explicitly stated.
2. 除非明确说明，否则元素顺序是不相关的。
3. Extension elements (elements not already defined as valid child elements) may be added anywhere, except when explicitly stated otherwise.
3. 扩展元素（尚未定义为有效子元素的元素）可以添加到任何位置，除非另有明确说明。
4. Extension attributes (attributes not already defined as valid for this element) may be added anywhere, except when explicitly stated otherwise.
4. 扩展属性（尚未定义为此元素有效的属性）可以添加到任何位置，除非另有明确说明。
The namespace "urn:ietf:params:xml:ns:carddav" is reserved for the XML elements defined in this specification, its revisions, and related CardDAV specifications. XML elements defined by individual implementations MUST NOT use the "urn:ietf:params:xml:ns:carddav" namespace, and instead should use a namespace that they control.
命名空间“urn:ietf:params:xml:ns:carddav”是为本规范及其修订版和相关的carddav规范中定义的xml元素保留的。由单个实现定义的XML元素不能使用“urn:ietf:params:XML:ns:carddav”命名空间，而应该使用它们控制的命名空间。
When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:carddav" are referenced in this document outside of the context of an XML fragment, the strings "DAV:" and "CARDDAV:" will be prefixed to the element types, respectively.
当本文档在XML片段的上下文之外引用名称空间“DAV:”和“urn:ietf:params:XML:ns:carddav”中的XML元素类型时，字符串“DAV:”和“carddav:”将分别作为元素类型的前缀。
This document inherits, and sometimes extends, DTD productions from Section 14 of [RFC4918].
本文档继承并有时扩展[RFC4918]第14节中的DTD产品。
Also, note that some CardDAV XML element names are identical to WebDAV XML element names, though their namespace differs. Care must be taken not to confuse the two sets of names.
另外，请注意，一些CardDAV XML元素名称与WebDAV XML元素名称相同，尽管它们的命名空间不同。必须注意不要混淆这两组名称。
This section lists what functionality is required of a CardDAV server. To advertise support for CardDAV, a server:
本节列出了CardDAV服务器所需的功能。要公布对服务器CardDAV的支持，请执行以下操作：
o MUST support vCard v3 [RFC2426] as a media type for the address object resource format;
o 必须支持vCard v3[RFC2426]作为地址对象资源格式的媒体类型；
o MUST support WebDAV Class 3 [RFC4918];
o 必须支持WebDAV 3类[RFC4918]；
o MUST support WebDAV ACL [RFC3744];
o 必须支持WebDAV ACL[RFC3744]；
o MUST support secure transport as defined in [RFC2818] using Transport Layer Security (TLS) [RFC5246] and using the certificate validation procedures described in [RFC5280];
o 必须使用传输层安全性（TLS）[RFC5246]并使用[RFC5280]中描述的证书验证程序，支持[RFC2818]中定义的安全传输；
o MUST support ETags [RFC2616] with additional requirements specified in Section 6.3.2.3 of this document;
o 必须按照本文件第6.3.2.3节规定的附加要求支持ETAG[RFC2616]；
o MUST support all address book reports defined in Section 8 of this document; and
o 必须支持本文件第8节中定义的所有通讯簿报告；和
o MUST advertise support on all address book collections and address object resources for the address book reports in the DAV:supported-report-set property, as defined in Versioning Extensions to WebDAV [RFC3253].
o 必须根据WebDAV[RFC3253]版本控制扩展中的定义，在DAV:supported report set属性中公布对通讯簿报告的所有通讯簿集合和地址对象资源的支持。
In addition, a server:
此外，服务器：
o SHOULD support vCard v4 [RFC6350] as a media type for the address object resource format;
o 应支持vCard v4[RFC6350]作为地址对象资源格式的媒体类型；
o SHOULD support the extended MKCOL method [RFC5689] to create address book collections as defined in Section 6.3.1 of this document.
o 应支持扩展的MKCOL方法[RFC5689]来创建本文档第6.3.1节中定义的通讯簿集合。
o SHOULD support the DAV:current-user-principal-URL property as defined in [RFC5397] to give clients a fast way to locate user principals.
o 应支持[RFC5397]中定义的DAV:current user principal URL属性，以便为客户端提供快速查找用户主体的方法。
As a brief overview, a CardDAV address book is modeled as a WebDAV collection with a well-defined structure; each of these address book collections contains a number of resources representing address objects as their direct child resources. Each resource representing an address object is called an "address object resource". Each address object resource and each address book collection can be individually locked and have individual WebDAV properties. Requirements derived from this model are provided in Sections 5.1 and 5.2.
作为简要概述，CardDAV通讯簿被建模为具有良好定义结构的WebDAV集合；每个地址簿集合都包含许多资源，这些资源将地址对象表示为它们的直接子资源。表示地址对象的每个资源称为“地址对象资源”。每个地址对象资源和每个通讯簿集合都可以单独锁定，并具有单独的WebDAV属性。第5.1节和第5.2节提供了从该模型得出的要求。
A CardDAV server is an address-aware engine combined with a WebDAV server. The server may include address data in some parts of its URL namespace and non-address data in other parts.
CardDAV服务器是与WebDAV服务器相结合的地址感知引擎。服务器可能在其URL命名空间的某些部分包含地址数据，在其他部分包含非地址数据。
A WebDAV server can advertise itself as a CardDAV server if it supports the functionality defined in this specification at any point within the root of its repository. That might mean that address data is spread throughout the repository and mixed with non-address data in nearby collections (e.g., address data may be found in /lisa/ addressbook/ as well as in /bernard/addressbook/, and non-address data in /lisa/calendars/). Or, it might mean that address data can be found only in certain sections of the repository (e.g., /addressbooks/user/). Address book features are only required in the repository sections that are or contain address objects. So, a repository confining address data to the /carddav/ collection would only need to support the CardDAV required features within that collection.
如果WebDAV服务器在其存储库根目录中的任何位置支持本规范中定义的功能，则它可以将自己作为CardDAV服务器进行宣传。这可能意味着地址数据分布在整个存储库中，并与附近集合中的非地址数据混合（例如，地址数据可以在/lisa/addressbook/以及/bernard/addressbook/中找到，而非地址数据可以在/lisa/calendars/中找到）。或者，这可能意味着地址数据只能在存储库的某些部分中找到（例如，/addressbooks/user/）。通讯簿功能仅在属于或包含地址对象的存储库部分中需要。因此，将地址数据限制在/carddav/集合中的存储库只需要支持该集合中需要的carddav功能。
The CardDAV server is the canonical location for address data and state information. Clients may submit requests to change data or download data. Clients may store address objects offline and attempt to synchronize at a later time. Address data on the server can change between the time of last synchronization and when attempting an update, as address book collections may be shared and accessible via multiple clients. Entity tags and locking help this work.
CardDAV服务器是地址数据和状态信息的标准位置。客户可以提交更改数据或下载数据的请求。客户端可以脱机存储地址对象，并在以后尝试同步。服务器上的地址数据可以在上次同步和尝试更新之间更改，因为地址簿集合可以通过多个客户端共享和访问。实体标记和锁定有助于这项工作。
This specification uses vCard as the default format for address or contact information being stored on the server. However, this specification does allow other formats for address data provided that the server advertises support for those additional formats as
本规范使用vCard作为存储在服务器上的地址或联系人信息的默认格式。但是，该规范允许使用其他格式的地址数据，前提是服务器宣传对这些其他格式的支持
described below. The requirements in this section pertain to vCard address data or formats that follow the semantics of vCard data.
如下所述。本节中的要求涉及vCard地址数据或遵循vCard数据语义的格式。
Address object resources contained in address book collections MUST contain a single vCard component only.
通讯簿集合中包含的地址对象资源只能包含单个vCard组件。
vCard components in an address book collection MUST have a UID property value that MUST be unique in the scope of the address book collection in which it is contained.
通讯簿集合中的vCard组件必须具有UID属性值，该属性值在包含它的通讯簿集合的范围内必须是唯一的。
Servers might support more than one primary media type for address object resources, for example, vCard v3.0 and vCard v4.0. In such cases, servers have to accept all media types that they advertise via the CARDDAV:supported-address-data WebDAV property (see Section 6.2.2).
服务器可能支持多个地址对象资源的主媒体类型，例如vCard v3.0和vCard v4.0。在这种情况下，服务器必须接受通过CARDDAV:supported address data WebDAV属性发布的所有媒体类型（请参见第6.2.2节）。
However, clients can use standard HTTP content negotiation behavior (the Accept request header defined in Section 14.1 of [RFC2616]) to request that an address object resource's data be returned in a specific media type format. For example, a client merely capable of handling vCard v3.0 would only want to have address object resources returned in v3.0 format.
但是，客户端可以使用标准HTTP内容协商行为（在[RFC2616]第14.1节中定义的接受请求头）请求以特定媒体类型格式返回地址对象资源的数据。例如，仅能够处理vCard v3.0的客户端只希望以v3.0格式返回地址对象资源。
Additionally, REPORT requests, defined later in this specification, allow for the return of address object resource data within an XML response body. Again, the client can use content negotiation to request that data be returned in a specific media type by specifying appropriate attributes on the CARDDAV:address-data XML element used in the request body (see Section 10.4).
此外，本规范后面定义的报告请求允许在XML响应体中返回地址对象资源数据。同样，客户机可以使用内容协商，通过在请求正文中使用的CARDDAV:address数据XML元素上指定适当的属性，请求以特定媒体类型返回数据（请参见第10.4节）。
In some cases, it might not be possible for a server to convert from one media type to another. When that happens, the server MUST return the CARDDAV:supported-address-data-conversion precondition (see below) in the response body (when the failure to convert applies to the entire response) or use that same precondition code in the DAV:response XML element in the response for the targeted address object resource when one of the REPORTs defined below is used. See Section 8.7.2 for an example of this.
在某些情况下，服务器可能无法从一种媒体类型转换为另一种媒体类型。发生这种情况时，服务器必须在响应正文中返回CARDDAV:supported address data conversion前提条件（请参见下文）（当转换失败适用于整个响应时）或者在使用下面定义的其中一个报告时，在目标地址对象资源的响应中的DAV:response XML元素中使用相同的前提条件代码。参见第8.7.2节，了解此示例。
This specification creates additional preconditions for the GET method.
此规范为GET方法创建了附加的先决条件。
The new precondition is:
新的先决条件是：
(CARDDAV:supported-address-data-conversion): The resource targeted by the GET request can be converted to the media type specified in the Accept request header included with the request.
（CARDDAV：支持的地址数据转换）：GET请求所针对的资源可以转换为请求中包含的Accept request标头中指定的媒体类型。
Address book collections appear to clients as a WebDAV collection resource, identified by a URL. An address book collection MUST report the DAV:collection and CARDDAV:addressbook XML elements in the value of the DAV:resourcetype property. The element type declaration for CARDDAV:addressbook is:
在客户端看来，通讯簿集合是由URL标识的WebDAV集合资源。通讯簿集合必须在DAV:resourcetype属性的值中报告DAV:collection和CARDDAV:addressbook XML元素。CARDDAV:addressbook的元素类型声明为：
<!ELEMENT addressbook EMPTY>
<!ELEMENT addressbook EMPTY>
An address book collection can be created through provisioning (e.g., automatically created when a user's account is provisioned), or it can be created with the extended MKCOL method (see Section 6.3.1). This can be used by a user to create additional address books (e.g., "soccer team members") or for users to share an address book (e.g., "sales team contacts"). However, note that this document doesn't define what extra address book collections are for. Users must rely on non-standard cues to find out what an address book collection is for, or use the CARDDAV:addressbook-description property defined in Section 6.2.1 to provide such a cue.
地址簿集合可以通过设置创建（例如，设置用户帐户时自动创建），也可以使用扩展的MKCOL方法创建（参见第6.3.1节）。用户可以使用此功能创建其他通讯簿（如“足球队成员”），或用户共享通讯簿（如“销售团队联系人”）。但是，请注意，本文档没有定义额外的通讯簿集合的用途。用户必须依赖非标准提示来确定通讯簿集合的用途，或者使用第6.2.1节中定义的CARDDAV:addressbook description属性来提供此类提示。
The following restrictions are applied to the resources within an address book collection:
以下限制适用于通讯簿集合中的资源：
a. Address book collections MUST only contain address object resources and collections that are not address book collections. That is, the only "top-level" non-collection resources allowed in an address book collection are address object resources. This ensures that address book clients do not have to deal with non-address data in an address book collection, though they do have to distinguish between address object resources and collections when using standard WebDAV techniques to examine the contents of a collection.
a. 通讯簿集合只能包含地址对象资源和不是通讯簿集合的集合。也就是说，通讯簿集合中唯一允许的“顶级”非集合资源是地址对象资源。这确保了通讯簿客户端不必处理通讯簿集合中的非地址数据，尽管它们在使用标准WebDAV技术检查集合内容时必须区分地址对象资源和集合。
b. Collections contained in address book collections MUST NOT contain address book collections at any depth. That is, "nesting" of address book collections within other address book collections at any depth is not allowed. This specification does not define how collections contained in an address book collection are used or how they relate to any address object resources contained in the address book collection.
b. 通讯簿集合中包含的集合不得包含任何深度的通讯簿集合。也就是说，不允许在任何深度将通讯簿集合“嵌套”到其他通讯簿集合中。本规范不定义如何使用通讯簿集合中包含的集合，也不定义它们与通讯簿集合中包含的任何地址对象资源的关系。
Multiple address book collections MAY be children of the same collection.
多个通讯簿集合可能是同一集合的子集合。
A server supporting the features described in this document MUST include "addressbook" as a field in the DAV response header from an OPTIONS request on any resource that supports any address book properties, reports, or methods. A value of "addressbook" in the DAV response header MUST indicate that the server supports all MUST level requirements and REQUIRED features specified in this document.
支持本文档所述功能的服务器必须在支持任何通讯簿属性、报告或方法的任何资源上的选项请求的DAV响应标头中包含“addressbook”字段。DAV响应标头中的“addressbook”值必须表明服务器支持本文档中指定的所有必须级别要求和必需功能。
>> Request <<
>> Request <<
OPTIONS /addressbooks/users/ HTTP/1.1
Host: addressbook.example.com
OPTIONS /addressbooks/users/ HTTP/1.1
Host: addressbook.example.com
>> Response <<
>> Response <<
HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
DAV: 1, 2, 3, access-control, addressbook
DAV: extended-mkcol
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Length: 0
HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
DAV: 1, 2, 3, access-control, addressbook
DAV: extended-mkcol
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Length: 0
In this example, the OPTIONS response indicates that the server supports CardDAV in this namespace; therefore, the '/addressbooks/ users/' collection may be used as a parent for address book collections as the extended MKCOL method is available and as a possible target for REPORT requests for address book reports.
在本例中，选项响应指示服务器在此命名空间中支持CardDAV；因此，“/addressbooks/users/”集合可以用作通讯簿集合的父集合，因为扩展的MKCOL方法可用，并且可以作为通讯簿报表请求的可能目标。
Name: addressbook-description
姓名：通讯录说明
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Provides a human-readable description of the address book collection.
目的：提供通讯簿集合的可读说明。
Value: Any text.
值：任何文本。
Protected: SHOULD NOT be protected so that users can specify a description.
受保护：不应进行保护，以便用户可以指定描述。
COPY/MOVE behavior: This property value SHOULD be preserved in COPY and MOVE operations.
复制/移动行为：此属性值应在复制和移动操作中保留。
allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop request.
PROPFIND DAV:allprop请求不应返回allprop行为。
Description: This property contains a description of the address book collection that is suitable for presentation to a user. The xml:lang attribute can be used to add a language tag for the value of this property.
描述：此属性包含适合向用户演示的通讯簿集合的描述。lang属性可用于为此属性的值添加语言标记。
Definition:
定义：
<!ELEMENT addressbook-description (#PCDATA)>
<!-- PCDATA value: string -->
<!ELEMENT addressbook-description (#PCDATA)>
<!-- PCDATA value: string -->
Example:
例子：
<C:addressbook-description xml:lang="fr-CA"
xmlns:C="urn:ietf:params:xml:ns:carddav"
>Adresses de Oliver Daboo</C:addressbook-description>
<C:addressbook-description xml:lang="fr-CA"
xmlns:C="urn:ietf:params:xml:ns:carddav"
>Adresses de Oliver Daboo</C:addressbook-description>
Name: supported-address-data
名称：支持的地址数据
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Specifies what media types are allowed for address object resources in an address book collection.
用途：指定通讯簿集合中的地址对象资源允许的媒体类型。
Protected: MUST be protected as it indicates the level of support provided by the server.
受保护：必须受保护，因为它指示服务器提供的支持级别。
COPY/MOVE behavior: This property value MUST be preserved in COPY and MOVE operations.
复制/移动行为：复制和移动操作中必须保留此属性值。
allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop request.
PROPFIND DAV:allprop请求不应返回allprop行为。
Description: The CARDDAV:supported-address-data property is used to specify the media type supported for the address object resources contained in a given address book collection (e.g., vCard version
描述：CARDDAV:supported address data属性用于指定给定通讯簿集合（例如vCard版本）中包含的地址对象资源支持的媒体类型
3.0). Any attempt by the client to store address object resources with a media type not listed in this property MUST result in an error, with the CARDDAV:supported-address-data precondition (Section 6.3.2.1) being violated. In the absence of this property, the server MUST only accept data with the media type "text/vcard" and vCard version 3.0, and clients can assume that is all the server will accept.
3.0). 如果客户端试图使用此属性中未列出的媒体类型存储地址对象资源，则必须导致错误，并违反CARDDAV:supported address data前提条件（第6.3.2.1节）。如果没有此属性，服务器必须只接受媒体类型为“text/vcard”且vcard版本为3.0的数据，并且客户端可以假定服务器将接受所有这些数据。
Definition:
定义：
<!ELEMENT supported-address-data (address-data-type+)>
<!ELEMENT supported-address-data (address-data-type+)>
<!ELEMENT address-data-type EMPTY>
<!ATTLIST address-data-type content-type CDATA "text/vcard"
version CDATA "3.0">
<!-- content-type value: a MIME media type -->
<!-- version value: a version string -->
<!ELEMENT address-data-type EMPTY>
<!ATTLIST address-data-type content-type CDATA "text/vcard"
version CDATA "3.0">
<!-- content-type value: a MIME media type -->
<!-- version value: a version string -->
Example:
例子：
<C:supported-address-data
xmlns:C="urn:ietf:params:xml:ns:carddav">
<C:address-data-type content-type="text/vcard" version="3.0"/>
</C:supported-address-data>
<C:supported-address-data
xmlns:C="urn:ietf:params:xml:ns:carddav">
<C:address-data-type content-type="text/vcard" version="3.0"/>
</C:supported-address-data>
Name: max-resource-size
名称：最大资源大小
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Provides a numeric value indicating the maximum size in octets of a resource that the server is willing to accept when an address object resource is stored in an address book collection.
用途：提供一个数值，指示当地址对象资源存储在通讯簿集合中时，服务器愿意接受的资源的最大大小（以八位字节为单位）。
Value: Any text representing a numeric value.
值：表示数值的任何文本。
Protected: 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: SHOULD NOT be returned by a PROPFIND DAV:allprop request.
PROPFIND DAV:allprop请求不应返回allprop行为。
Description: The CARDDAV:max-resource-size is used to specify a numeric value that represents the maximum size in octets that the server is willing to accept when an address object resource is stored in an address book collection. Any attempt to store an address book object resource exceeding this size MUST result in an error, with the CARDDAV:max-resource-size precondition (Section 6.3.2.1) being violated. In the absence of this property, the client can assume that the server will allow storing a resource of any reasonable size.
描述：CARDDAV:max resource size用于指定一个数值，该数值表示地址对象资源存储在通讯簿集合中时服务器愿意接受的最大大小（以八位字节为单位）。任何存储超过此大小的通讯簿对象资源的尝试都必须导致错误，并违反CARDDAV:max resource size前提条件（第6.3.2.1节）。如果没有此属性，客户端可以假定服务器将允许存储任何合理大小的资源。
Definition:
定义：
<!ELEMENT max-resource-size (#PCDATA)>
<!-- PCDATA value: a numeric value (positive decimal integer) -->
<!ELEMENT max-resource-size (#PCDATA)>
<!-- PCDATA value: a numeric value (positive decimal integer) -->
Example:
例子：
<C:max-resource-size xmlns:C="urn:ietf:params:xml:ns:carddav"
>102400</C:max-resource-size>
<C:max-resource-size xmlns:C="urn:ietf:params:xml:ns:carddav"
>102400</C:max-resource-size>
Address book collections and address object resources may be created by either a CardDAV client or the CardDAV server. This specification defines restrictions and a data model that both clients and servers MUST adhere to when manipulating such address data.
通讯簿集合和地址对象资源可以由CardDAV客户端或CardDAV服务器创建。此规范定义了客户端和服务器在处理此类地址数据时必须遵守的限制和数据模型。
An HTTP request using the extended MKCOL method [RFC5689] can be used to create a new address book collection resource. A server MAY restrict address book collection creation to particular collections.
使用扩展MKCOL方法[RFC5689]的HTTP请求可用于创建新的通讯簿集合资源。服务器可能会将通讯簿集合的创建限制为特定集合。
To create an address book, the client sends an extended MKCOL request to the server and in the body of the request sets the DAV:resourcetype property to the resource type for an address book collection as defined in Section 5.2.
要创建通讯簿，客户端向服务器发送一个扩展的MKCOL请求，并在请求正文中将DAV:resourcetype属性设置为第5.2节中定义的通讯簿集合的资源类型。
Support for creating address books on the server is only RECOMMENDED and not REQUIRED because some address book stores only support one address book per user (or principal), and those are typically pre-created for each account. However, servers and clients are strongly encouraged to support address book creation whenever possible to allow users to create multiple address book collections to help organize their data better.
仅建议支持在服务器上创建通讯簿，而不是必需的，因为某些通讯簿存储仅支持每个用户（或主体）一个通讯簿，并且通常为每个帐户预先创建这些通讯簿。但是，强烈建议服务器和客户端尽可能支持通讯簿创建，以允许用户创建多个通讯簿集合，帮助更好地组织数据。
The DAV:displayname property can be used for a human-readable name of the address book. Clients can either specify the value of the DAV:displayname property in the request body of the extended MKCOL request or, alternatively, issue a PROPPATCH request to change the DAV:displayname property to the appropriate value immediately after using the extended MKCOL request. When displaying address book collections to users, clients SHOULD check the DAV:displayname property and use that value as the name of the address book. In the event that the DAV:displayname property is not set, the client MAY use the last part of the address book collection URI as the name; however, that path segment may be "opaque" and not represent any meaningful human-readable text.
DAV:displayname属性可用于通讯簿的可读名称。客户端可以在扩展MKCOL请求的请求正文中指定DAV:displayname属性的值，或者，在使用扩展MKCOL请求后立即发出PROPPATCH请求将DAV:displayname属性更改为适当的值。向用户显示通讯簿集合时，客户端应检查DAV:displayname属性，并将该值用作通讯簿的名称。如果未设置DAV:displayname属性，则客户端可以使用通讯簿集合URI的最后一部分作为名称；然而，该路径段可能是“不透明的”，并且不代表任何有意义的人类可读文本。
This example creates an address book collection called /home/lisa/ addressbook/ on the server addressbook.example.com with specific values for the properties DAV:resourcetype, DAV:displayname, and CARDDAV:addressbook-description.
此示例在服务器addressbook.example.com上创建一个名为/home/lisa/addressbook/的通讯簿集合，其中包含属性DAV:resourcetype、DAV:displayname和CARDDAV:addressbook description的特定值。
>> Request <<
>> Request <<
MKCOL /home/lisa/addressbook/ HTTP/1.1
Host: addressbook.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
MKCOL /home/lisa/addressbook/ HTTP/1.1
Host: addressbook.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:mkcol xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:set>
<D:prop>
<D:resourcetype>
<D:collection/>
<C:addressbook/>
</D:resourcetype>
<D:displayname>Lisa's Contacts</D:displayname>
<C:addressbook-description xml:lang="en"
>My primary address book.</C:addressbook-description>
</D:prop>
</D:set>
</D:mkcol>
<?xml version="1.0" encoding="utf-8" ?>
<D:mkcol xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:set>
<D:prop>
<D:resourcetype>
<D:collection/>
<C:addressbook/>
</D:resourcetype>
<D:displayname>Lisa's Contacts</D:displayname>
<C:addressbook-description xml:lang="en"
>My primary address book.</C:addressbook-description>
</D:prop>
</D:set>
</D:mkcol>
>> Response <<
>> Response <<
HTTP/1.1 201 Created
Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
HTTP/1.1 201 Created
Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:mkcol-response xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:propstat>
<D:prop>
<D:resourcetype/>
<D:displayname/>
<C:addressbook-description/>
</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:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:propstat>
<D:prop>
<D:resourcetype/>
<D:displayname/>
<C:addressbook-description/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:mkcol-response>
Clients populate address book collections with address object resources. The URL for each address object resource is entirely arbitrary and does not need to bear a specific relationship (but might) to the address object resource's vCard properties or other metadata. New address object resources MUST be created with a PUT request targeted at an unmapped URI. A PUT request targeted at a mapped URI updates an existing address object resource.
客户端使用地址对象资源填充通讯簿集合。每个地址对象资源的URL完全是任意的，不需要与地址对象资源的vCard属性或其他元数据具有特定关系（但可能）。必须使用针对未映射URI的PUT请求创建新地址对象资源。针对映射URI的PUT请求更新现有地址对象资源。
When servers create new resources, it's not hard for the server to choose a unique URL. It's slightly tougher for clients, because a client might not want to examine all resources in the collection and might not want to lock the entire collection to ensure that a new one isn't created with a name collision. However, there is an HTTP feature to mitigate this. If the client intends to create a new address resource, the client SHOULD use the HTTP header "If-None-Match: *" on the PUT request. The Request-URI on the PUT request MUST include the target collection, where the resource is to be created, plus the name of the resource in the last path segment. The "If-None-Match" header ensures that the client will not inadvertently overwrite an existing resource even if the last path segment turned out to already be used.
当服务器创建新资源时，服务器不难选择唯一的URL。对于客户端来说，这稍微有些困难，因为客户端可能不希望检查集合中的所有资源，也不希望锁定整个集合以确保创建新集合时不会发生名称冲突。但是，有一个HTTP特性可以缓解这种情况。如果客户端打算创建一个新的地址资源，客户端应该在PUT请求上使用HTTP头“If None Match:*”。PUT请求上的请求URI必须包括要在其中创建资源的目标集合，以及最后一个路径段中的资源名称。“If None Match”标头确保即使最后一个路径段已被使用，客户端也不会无意中覆盖现有资源。
>> Request <<
>> Request <<
PUT /lisa/addressbook/newvcard.vcf HTTP/1.1
If-None-Match: *
Host: addressbook.example.com
Content-Type: text/vcard
Content-Length: xxx
PUT /lisa/addressbook/newvcard.vcf HTTP/1.1
If-None-Match: *
Host: addressbook.example.com
Content-Type: text/vcard
Content-Length: xxx
BEGIN:VCARD
VERSION:3.0
FN:Cyrus Daboo
N:Daboo;Cyrus
ADR;TYPE=POSTAL:;2822 Email HQ;Suite 2821;RFCVille;PA;15213;USA
EMAIL;TYPE=INTERNET,PREF:cyrus@example.com
NICKNAME:me
NOTE:Example VCard.
ORG:Self Employed
TEL;TYPE=WORK,VOICE:412 605 0499
TEL;TYPE=FAX:412 605 0705
URL:http://www.example.com
UID:1234-5678-9000-1
END:VCARD
BEGIN:VCARD
VERSION:3.0
FN:Cyrus Daboo
N:Daboo;Cyrus
ADR;TYPE=POSTAL:;2822 Email HQ;Suite 2821;RFCVille;PA;15213;USA
EMAIL;TYPE=INTERNET,PREF:cyrus@example.com
NICKNAME:me
NOTE:Example VCard.
ORG:Self Employed
TEL;TYPE=WORK,VOICE:412 605 0499
TEL;TYPE=FAX:412 605 0705
URL:http://www.example.com
UID:1234-5678-9000-1
END:VCARD
>> Response <<
>> Response <<
HTTP/1.1 201 Created
Date: Thu, 02 Sep 2004 16:53:32 GMT
Content-Length: 0
ETag: "123456789-000-111"
HTTP/1.1 201 Created
Date: Thu, 02 Sep 2004 16:53:32 GMT
Content-Length: 0
ETag: "123456789-000-111"
The request to change an existing address object resource without overwriting a change made on the server uses a specific ETag in an "If-Match" header, rather than the "If-None-Match" header.
在不覆盖服务器上所做更改的情况下更改现有地址对象资源的请求在“If Match”头中使用特定的ETag，而不是在“If None Match”头中使用。
File names for vCards are commonly suffixed by ".vcf", and clients may choose to use the same convention for URLs.
vCard的文件名通常以“.vcf”作为后缀，客户端可以选择对URL使用相同的约定。
This specification creates additional preconditions for the PUT, COPY, and MOVE methods. These preconditions apply:
本规范为PUT、COPY和MOVE方法创建了附加的先决条件。这些先决条件适用于：
o When a PUT operation of an address object resource into an address book collection occurs.
o 将地址对象资源放入通讯簿集合的PUT操作发生时。
o When a COPY or MOVE operation of an address object resource into an address book collection occurs.
o 将地址对象资源复制或移动到通讯簿集合中时。
The new preconditions are:
新的先决条件是：
(CARDDAV:supported-address-data): The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST be a supported media type (i.e., vCard) for address object resources.
（CARDDAV：支持的地址数据）：在PUT请求中提交的资源，或复制或移动请求的目标资源，必须是地址对象资源支持的媒体类型（即vCard）。
(CARDDAV:valid-address-data): The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST be valid data for the media type being specified (i.e., MUST contain valid vCard data).
（CARDDAV：有效地址数据）：在PUT请求中提交的资源，或复制或移动请求的目标资源，必须是指定媒体类型的有效数据（即，必须包含有效的vCard数据）。
(CARDDAV:no-uid-conflict): The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST NOT specify a vCard UID property value already in use in the targeted address book collection or overwrite an existing address object resource with one that has a different UID property value. Servers SHOULD report the URL of the resource that is already making use of the same UID property value in the DAV:href element.
（CARDDAV:无uid冲突）：在PUT请求中提交的资源，或复制或移动请求的目标资源，不得指定已在目标通讯簿集合中使用的vCard uid属性值，或使用具有不同uid属性值的资源覆盖现有地址对象资源。服务器应报告已在DAV:href元素中使用相同UID属性值的资源的URL。
<!ELEMENT no-uid-conflict (DAV:href)>
<!ELEMENT no-uid-conflict (DAV:href)>
(CARDDAV:addressbook-collection-location-ok): In a COPY or MOVE request, when the Request-URI is an address book collection, the URI targeted by the Destination HTTP Request header MUST identify a location where an address book collection can be created.
（CARDDAV:addressbook collection location ok）：在复制或移动请求中，当请求URI是地址簿集合时，目标HTTP请求标头所针对的URI必须标识可以创建地址簿集合的位置。
(CARDDAV:max-resource-size): The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST have a size in octets less than or equal to the value of the CARDDAV:max-resource-size property value (Section 6.2.3) on the address book collection where the resource will be stored.
（CARDDAV:max resource size）：在PUT请求中提交的资源，或复制或移动请求的目标资源，其大小（以八位字节为单位）必须小于或等于存储资源的通讯簿集合上的CARDDAV:max resource size属性值（第6.2.3节）。
vCard provides a "standard mechanism for doing non-standard things". This extension support allows implementers to make use of non-standard vCard properties and parameters whose names are prefixed with the text "X-".
vCard提供了“做非标准事情的标准机制”。此扩展支持允许实现者使用名称前缀为文本“X-”的非标准vCard属性和参数。
Servers MUST support the use of non-standard properties and parameters in address object resources stored via the PUT method.
服务器必须支持在通过PUT方法存储的地址对象资源中使用非标准属性和参数。
Servers may need to enforce rules for their own "private" properties or parameters, so servers MAY reject any attempt by the client to change those or use values for those outside of any restrictions the server may have. A server SHOULD ensure that any "private"
服务器可能需要为其自己的“私有”属性或参数强制执行规则，因此服务器可能会拒绝客户端更改这些属性或参数的任何尝试，或使用服务器可能具有的任何限制以外的属性或参数的值。服务器应确保任何“专用”
properties or parameters it uses follow the convention of including a vendor ID in the "X-" name, as described in Section 3.8 of [RFC2426], e.g., "X-ABC-PRIVATE".
其使用的属性或参数遵循在“X-”名称中包含供应商ID的约定，如[RFC2426]第3.8节所述，例如“X-ABC-PRIVATE”。
The DAV:getetag property MUST be defined and set to a strong entity tag on all address object resources.
必须在所有地址对象资源上定义DAV:getetag属性并将其设置为强实体标记。
A response to a GET request targeted at an address object resource MUST contain an ETag response header field indicating the current value of the strong entity tag of the address object resource.
针对地址对象资源的GET请求的响应必须包含ETag响应头字段，该字段指示地址对象资源的强实体标记的当前值。
Servers SHOULD return a strong entity tag (ETag header) in a PUT response when the stored address object resource is equivalent by octet equality to the address object resource submitted in the body of the PUT request. This allows clients to reliably use the returned strong entity tag for data synchronization purposes. For instance, the client can do a PROPFIND request on the stored address object resource, have the DAV:getetag property returned, compare that value with the strong entity tag it received on the PUT response, and know that if they are equal, then the address object resource on the server has not been changed.
当存储的地址对象资源与PUT请求主体中提交的地址对象资源具有八位字节相等性时，服务器应在PUT响应中返回强实体标记（ETag头）。这允许客户端可靠地使用返回的强实体标记进行数据同步。例如，客户机可以对存储的地址对象资源执行PROPFIND请求，返回DAV:getetag属性，将该值与它在PUT响应中接收到的强实体标记进行比较，并知道如果它们相等，则服务器上的地址对象资源未被更改。
In the case where the data stored by a server as a result of a PUT request is not equivalent by octet equality to the submitted address object resource, the behavior of the ETag response header is not specified here, with the exception that a strong entity tag MUST NOT be returned in the response. As a result, a client may need to retrieve the modified address object resource (and ETag) as a basis for further changes, rather than use the address object resource it had sent with the PUT request.
如果服务器因PUT请求而存储的数据与提交的地址对象资源的八位字节相等性不同，则此处不指定ETag响应头的行为，但响应中不得返回强实体标记除外。因此，客户机可能需要检索修改后的地址对象资源（和ETag）作为进一步更改的基础，而不是使用它与PUT请求一起发送的地址对象资源。
CardDAV servers MUST support and adhere to the requirements of WebDAV ACL [RFC3744]. WebDAV ACL provides a framework for an extensible set of privileges that can be applied to WebDAV collections and ordinary resources.
CardDAV服务器必须支持并遵守WebDAV ACL[RFC3744]的要求。WebDAV ACL为可扩展权限集提供了一个框架，该权限集可应用于WebDAV集合和普通资源。
This section defines additional properties for WebDAV principal resources as defined in [RFC3744].
本节定义了[RFC3744]中定义的WebDAV主体资源的其他属性。
Name: addressbook-home-set
名称：通讯簿主页集
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Identifies the URL of any WebDAV collections that contain address book collections owned by the associated principal resource.
目的：标识包含关联主体资源所拥有的通讯簿集合的任何WebDAV集合的URL。
Protected: MAY be protected if the server has fixed locations in which address books are created.
受保护：如果服务器具有创建通讯簿的固定位置，则可能受保护。
COPY/MOVE behavior: This property value MUST be preserved in COPY and MOVE operations.
复制/移动行为：复制和移动操作中必须保留此属性值。
allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop request.
PROPFIND DAV:allprop请求不应返回allprop行为。
Description: The CARDDAV:addressbook-home-set property is meant to allow users to easily find the address book collections owned by the principal. Typically, users will group all the address book collections that they own under a common collection. This property specifies the URL of collections that are either address book collections or ordinary collections that have child or descendant address book collections owned by the principal.
描述：CARDDAV:addressbook home set属性旨在允许用户轻松找到委托人拥有的通讯簿集合。通常，用户会将他们拥有的所有通讯簿集合分组到一个公共集合下。此属性指定具有主体所拥有的子或子代通讯簿集合的通讯簿集合或普通集合的集合的URL。
Definition:
定义：
<!ELEMENT addressbook-home-set (DAV:href*)>
<!ELEMENT addressbook-home-set (DAV:href*)>
Example:
例子：
<C:addressbook-home-set xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:href>/bernard/addresses/</D:href>
</C:addressbook-home-set>
<C:addressbook-home-set xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:href>/bernard/addresses/</D:href>
</C:addressbook-home-set>
Name: principal-address
姓名：主要地址
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Identifies the URL of an address object resource that corresponds to the user represented by the principal.
目的：标识与主体表示的用户相对应的地址对象资源的URL。
Protected: MAY be protected if the server provides a fixed location for principal addresses.
受保护：如果服务器为主体地址提供固定位置，则可能受保护。
COPY/MOVE behavior: This property value MUST be preserved in COPY and MOVE operations.
复制/移动行为：复制和移动操作中必须保留此属性值。
allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop request.
PROPFIND DAV:allprop请求不应返回allprop行为。
Description: The CARDDAV:principal-address property is meant to allow users to easily find contact information for users represented by principals on the system. This property specifies the URL of the resource containing the corresponding contact information. The resource could be an address object resource in an address book collection, or it could be a resource in a "regular" collection.
描述：CARDDAV:principal address属性用于允许用户轻松查找系统上由主体表示的用户的联系信息。此属性指定包含相应联系人信息的资源的URL。该资源可以是通讯簿集合中的地址对象资源，也可以是“常规”集合中的资源。
Definition:
定义：
<!ELEMENT principal-address (DAV:href)>
<!ELEMENT principal-address (DAV:href)>
Example:
例子：
<C:principal-address xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:href>/system/cyrus.vcf</D:href>
</C:principal-address>
<C:principal-address xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:href>/system/cyrus.vcf</D:href>
</C:principal-address>
This section defines the reports that CardDAV servers MUST support on address book collections and address object resources.
本节定义了CardDAV服务器在通讯簿集合和地址对象资源上必须支持的报告。
CardDAV servers MUST advertise support for these reports on all address book collections and address object resources with the DAV:supported-report-set property defined in Section 3.1.5 of [RFC3253]. CardDAV servers MAY also advertise support for these reports on ordinary collections.
CardDAV服务器必须使用[RFC3253]第3.1.5节中定义的DAV:supported report set属性在所有通讯簿集合和地址对象资源上公布对这些报告的支持。CardDAV服务器还可以在普通集合上公布对这些报告的支持。
Some of these reports allow address data (from possibly multiple resources) to be returned.
其中一些报告允许返回地址数据（可能来自多个资源）。
The REPORT method (defined in Section 3.6 of [RFC3253]) provides an extensible mechanism for obtaining information about a resource. Unlike the PROPFIND method, which returns the value of one or more named properties, the REPORT method can involve more complex
报告方法（定义见[RFC3253]第3.6节）为获取资源信息提供了一种可扩展的机制。与PROPFIND方法（返回一个或多个命名属性的值）不同，REPORT方法可能涉及更复杂的问题
processing. REPORT is valuable in cases where the server has access to all of the information needed to perform the complex request (such as a query), and where it would require multiple requests for the client to retrieve the information needed to perform the same request.
处理。当服务器可以访问执行复杂请求（如查询）所需的所有信息，并且客户端需要多次请求才能检索执行同一请求所需的信息时，报表非常有用。
A server that supports this specification MUST support the DAV:expand-property report (defined in Section 3.8 of [RFC3253]).
支持此规范的服务器必须支持DAV:expand属性报告（定义见[RFC3253]第3.8节）。
Servers MAY support the reports defined in this document on ordinary collections (collections that are not address book collections) in addition to address book collections or address object resources. In computing responses to the reports on ordinary collections, servers MUST only consider address object resources contained in address book collections that are targeted by the REPORT based on the value of the Depth request header.
除了通讯簿集合或地址对象资源之外，服务器还可以支持本文档中定义的关于普通集合（不是通讯簿集合的集合）的报告。在计算对普通集合的报告的响应时，服务器必须只考虑基于深度请求头部的值而包含在报告目标的地址簿集合中的地址对象资源。
Some of the reports defined in this section do text matches of character strings provided by the client and compared to stored address data. Since vCard data is by default encoded in the UTF-8 charset and may include characters outside of the US-ASCII charset range in some property and parameter values, there is a need to ensure that text matching follows well-defined rules.
本节中定义的一些报告对客户端提供的字符串进行文本匹配，并与存储的地址数据进行比较。由于vCard数据默认编码为UTF-8字符集，并且在某些属性和参数值中可能包含US-ASCII字符集范围之外的字符，因此需要确保文本匹配遵循定义良好的规则。
To deal with this, this specification makes use of the IANA Collation Registry defined in [RFC4790] to specify collations that may be used to carry out the text comparison operations with a well-defined rule.
为了解决这个问题，本规范使用[RFC4790]中定义的IANA排序规则注册表来指定排序规则，这些排序规则可用于使用定义良好的规则执行文本比较操作。
Collations supported by the server MUST support "equality" and "substring" match operations as per [RFC4790], Section 4.2, including the "prefix" and "suffix" options for "substring" matching. CardDAV uses these match options for "equals", "contains", "starts-with", and "ends-with" match operations.
根据[RFC4790]第4.2节，服务器支持的排序规则必须支持“相等”和“子字符串”匹配操作，包括“子字符串”匹配的“前缀”和“后缀”选项。CardDAV将这些匹配选项用于“等于”、“包含”、“以开始”和“以结束”匹配操作。
CardDAV servers are REQUIRED to support the "i;ascii-casemap" [RFC4790] and "i;unicode-casemap" [RFC5051] collations and MAY support other collations.
CardDAV服务器需要支持“i；ascii casemap”[RFC4790]和“i；unicode casemap”[RFC5051]排序规则，并且可能支持其他排序规则。
Servers MUST advertise the set of collations that they support via the CARDDAV:supported-collation-set property defined on any resource that supports reports that use collations.
服务器必须通过在支持使用排序规则的报表的任何资源上定义的CARDDAV:supported collation set属性公布其支持的排序规则集。
In the absence of a collation explicitly specified by the client, or if the client specifies the "default" collation identifier (as defined in [RFC4790], Section 3.1), the server MUST default to using "i;unicode-casemap" as the collation.
如果没有客户机明确指定的排序规则，或者如果客户机指定了“默认”排序规则标识符（如[RFC4790]第3.1节中的定义），则服务器必须默认使用“i；unicode casemap”作为排序规则。
Wildcards (as defined in [RFC4790], Section 3.2) MUST NOT be used in the collation identifier.
排序规则标识符中不得使用通配符（如[RFC4790]第3.2节中的定义）。
If the client chooses a collation not supported by the server, the server MUST respond with a CARDDAV:supported-collation precondition error response.
如果客户端选择服务器不支持的排序规则，服务器必须使用CARDDAV:supported collation premission错误响应进行响应。
Name: supported-collation-set
名称：支持的排序规则集
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Identifies the set of collations supported by the server for text matching operations.
目的：标识服务器支持的用于文本匹配操作的排序规则集。
Protected: MUST be protected as it indicates support provided by the server.
受保护：必须受保护，因为它表示服务器提供的支持。
COPY/MOVE behavior: This property value MUST be preserved in COPY and MOVE operations.
复制/移动行为：复制和移动操作中必须保留此属性值。
allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop request.
PROPFIND DAV:allprop请求不应返回allprop行为。
Description: The CARDDAV:supported-collation-set property contains two or more CARDDAV:supported-collation elements that specify the identifiers of the collations supported by the server.
描述：CARDDAV:supported排序规则集属性包含两个或多个CARDDAV:supported排序规则元素，用于指定服务器支持的排序规则的标识符。
Definition:
定义：
<!ELEMENT supported-collation-set (
supported-collation
supported-collation
supported-collation*)>
<!-- Both "i;ascii-casemap" and "i;unicode-casemap"
will be present -->
<!ELEMENT supported-collation-set (
supported-collation
supported-collation
supported-collation*)>
<!-- Both "i;ascii-casemap" and "i;unicode-casemap"
will be present -->
<!ELEMENT supported-collation (#PCDATA)>
<!ELEMENT supported-collation (#PCDATA)>
Example:
例子：
<C:supported-collation-set
xmlns:C="urn:ietf:params:xml:ns:carddav">
<C:supported-collation>i;ascii-casemap</C:supported-collation>
<C:supported-collation>i;octet</C:supported-collation>
<C:supported-collation>i;unicode-casemap</C:supported-collation>
</C:supported-collation-set>
<C:supported-collation-set
xmlns:C="urn:ietf:params:xml:ns:carddav">
<C:supported-collation>i;ascii-casemap</C:supported-collation>
<C:supported-collation>i;octet</C:supported-collation>
<C:supported-collation>i;unicode-casemap</C:supported-collation>
</C:supported-collation-set>
Some address book reports defined in this document allow partial retrieval of address object resources. A CardDAV client can specify what information to return in the body of an address book REPORT request.
本文档中定义的某些通讯簿报告允许部分检索地址对象资源。CardDAV客户端可以指定在通讯簿报告请求的正文中返回哪些信息。
A CardDAV client can request particular WebDAV property values, all WebDAV property values, or a list of the names of the resource's WebDAV properties. A CardDAV client can also request address data to be returned and whether all vCard properties should be returned or only particular ones. See CARDDAV:address-data in Section 10.4.
CardDAV客户端可以请求特定的WebDAV属性值、所有WebDAV属性值或资源的WebDAV属性名称列表。CardDAV客户端还可以请求返回地址数据，以及是否应返回所有vCard属性或仅返回特定属性。参见第10.4节中的CARDDAV：地址数据。
Servers MUST support the use of non-standard vCard property or parameter names in the CARDDAV:address-data XML element in address book REPORT requests to allow clients to request that non-standard properties and parameters be returned in the address data provided in the response.
服务器必须支持在通讯簿报告请求中的CARDDAV:address数据XML元素中使用非标准vCard属性或参数名称，以允许客户端请求在响应中提供的地址数据中返回非标准属性和参数。
Servers MAY support the use of non-standard vCard property or parameter names in the CARDDAV:prop-filter and CARDDAV:param-filter XML elements specified in the CARDDAV:filter XML element of address book REPORT requests.
服务器可能支持在通讯簿报告请求的CARDDAV:filter XML元素中指定的CARDDAV:prop筛选器和CARDDAV:param筛选器XML元素中使用非标准vCard属性或参数名称。
Servers MUST fail with the CARDDAV:supported-filter precondition if an address book REPORT request uses a CARDDAV:prop-filter or CARDDAV:param-filter XML element that makes reference to a non-standard vCard property or parameter name on which the server does not support queries.
如果通讯簿报告请求使用CARDDAV:prop筛选器或CARDDAV:param筛选器XML元素引用服务器不支持查询的非标准vCard属性或参数名称，则服务器必须以CARDDAV:supported筛选器前提条件失败。
The CARDDAV:addressbook-query REPORT performs a search for all address object resources that match a specified filter. The response of this report will contain all the WebDAV properties and address object resource data specified in the request. In the case of the
CARDDAV:addressbook查询报告搜索与指定筛选器匹配的所有地址对象资源。此报告的响应将包含请求中指定的所有WebDAV属性和地址对象资源数据。就
CARDDAV:address-data XML element, one can explicitly specify the vCard properties that should be returned in the address object resource data that matches the filter.
CARDDAV:address-data-XML元素，可以显式指定应在与筛选器匹配的地址对象资源数据中返回的vCard属性。
The format of this report is modeled on the PROPFIND method. The request and response bodies of the CARDDAV:addressbook-query report use XML elements that are also used by PROPFIND. In particular, the request can include XML elements to request WebDAV properties to be returned. When that occurs, the response should follow the same behavior as PROPFIND with respect to the DAV:multistatus response elements used to return specific WebDAV property results. For instance, a request to retrieve the value of a WebDAV property that does not exist is an error and MUST be noted with a response XML element that contains a 404 (Not Found) status value.
此报告的格式以PROPFIND方法为模型。CARDDAV:addressbook查询报告的请求和响应主体使用PROPFIND也使用的XML元素。特别是，请求可以包含XML元素，以请求返回WebDAV属性。当发生这种情况时，响应应该遵循与PROPFIND相同的行为，与用于返回特定WebDAV属性结果的DAV:multistatus响应元素相关。例如，检索不存在的WebDAV属性值的请求是一个错误，必须使用包含404（未找到）状态值的响应XML元素进行说明。
Support for the CARDDAV:addressbook-query REPORT is REQUIRED.
需要支持CARDDAV:addressbook查询报告。
Marshalling:
编组：
The request body MUST be a CARDDAV:addressbook-query XML element as defined in Section 10.3.
请求主体必须是第10.3节中定义的CARDDAV:addressbook查询XML元素。
The request MUST include a Depth header. The scope of the query is determined by the value of the Depth header. For example, to query all address object resources in an address book collection, the REPORT would use the address book collection as the Request-URI and specify a Depth of 1 or infinity.
请求必须包含深度标头。查询的范围由深度标题的值确定。例如，要查询通讯簿集合中的所有地址对象资源，报表将使用通讯簿集合作为请求URI，并指定深度为1或无穷大。
The response body for a successful request MUST be a DAV:multistatus XML element (i.e., the response uses the same format as the response for PROPFIND). In the case where there are no response elements, the returned DAV:multistatus XML element is empty.
成功请求的响应体必须是DAV:multistatusxml元素（即，响应使用与PROPFIND响应相同的格式）。在没有响应元素的情况下，返回的DAV:multistatusxml元素为空。
The response body for a successful CARDDAV:addressbook-query REPORT request MUST contain a DAV:response element for each address object that matched the search filter. Address data is returned in the CARDDAV:address-data XML element inside the DAV:propstat XML element.
对于与搜索筛选器匹配的每个地址对象，成功的CARDDAV:addressbook查询报告请求的响应正文必须包含一个DAV:response元素。地址数据在DAV:propstat XML元素内的CARDDAV:Address数据XML元素中返回。
Preconditions:
先决条件：
(CARDDAV:supported-address-data): The attributes "content-type" and "version" of the CARDDAV:address-data XML element (see Section 10.4) specify a media type supported by the server for address object resources.
（CARDDAV:支持的地址数据）：CARDDAV:地址数据XML元素的属性“内容类型”和“版本”（请参见第10.4节）指定服务器支持的地址对象资源的媒体类型。
(CARDDAV:supported-filter): The CARDDAV:prop-filter (see Section 10.5.1) and CARDDAV:param-filter (see Section 10.5.2) XML elements used in the CARDDAV:filter XML element (see Section 10.5) in the REPORT request only make reference to vCard properties and parameters for which queries are supported by the server. That is, if the CARDDAV:filter element attempts to reference an unsupported vCard property or parameter, this precondition is violated. A server SHOULD report the CARDDAV:prop-filter or CARDDAV:param-filter for which it does not provide support.
（CARDDAV:supported filter）：报告请求中CARDDAV:filter XML元素（参见第10.5.5节）中使用的CARDDAV:prop过滤器（参见第10.5.1节）和CARDDAV:param过滤器（参见第10.5.2节）XML元素仅引用服务器支持查询的vCard属性和参数。也就是说，如果CARDDAV:filter元素尝试引用不受支持的vCard属性或参数，则违反此前提条件。服务器应报告其不支持的CARDDAV:prop筛选器或CARDDAV:param筛选器。
<!ELEMENT supported-filter (prop-filter*,
param-filter*)>
<!ELEMENT supported-filter (prop-filter*,
param-filter*)>
(CARDDAV:supported-collation): Any XML attribute specifying a collation MUST specify a collation supported by the server as described in Section 8.3.
（CARDDAV：支持的排序规则）：任何指定排序规则的XML属性都必须指定服务器支持的排序规则，如第8.3节所述。
Postconditions:
后条件：
(DAV:number-of-matches-within-limits): The number of matching address object resources must fall within server-specific, predefined limits. For example, this condition might be triggered if a search specification would cause the return of an extremely large number of responses.
（DAV：限制内的匹配数）：匹配地址对象资源的数量必须在特定于服务器的预定义限制内。例如，如果搜索规范会导致返回大量响应，则可能会触发此条件。
A client can limit the number of results returned by the server through use of the CARDDAV:limit element in the request body. This is useful when clients are only interested in a few matches or only have limited space to display results to users and thus don't need the overhead of receiving more than that. When the results are truncated by the server, the server MUST follow the rules below for indicating a result set truncation to the client.
客户端可以通过使用请求正文中的CARDDAV:limit元素来限制服务器返回的结果数。当客户端只对几个匹配项感兴趣，或者只有有限的空间向用户显示结果，因此不需要额外的接收开销时，这非常有用。当结果被服务器截断时，服务器必须遵循以下规则向客户端指示结果集截断。
A server MAY limit the number of resources in a response, for example, to limit the amount of work expended in processing a query, or as the result of an explicit limit set by the client. If the result set is truncated because of such a limit, the response MUST use status code 207 (Multi-Status), return a DAV:multistatus response body, and indicate a status of 507 (Insufficient Storage) for the Request-URI. That DAV:response element SHOULD include a DAV:error element with the DAV:number-of-matches-within-limits precondition, as defined in [RFC3744], Section 9.2.
服务器可以限制响应中的资源数量，例如，限制处理查询所花费的工作量，或者作为客户端设置的显式限制的结果。如果结果集因此类限制而被截断，则响应必须使用状态代码207（多状态），返回DAV:multistatus响应正文，并为请求URI指示507（存储不足）状态。该DAV:response元素应包括一个DAV:error元素，该元素具有[RFC3744]第9.2节中定义的DAV:number of matches within limits前提条件。
The server SHOULD also include the partial results in additional DAV:response elements. If a client-requested limit is being applied, the 507 response for the Request-URI MUST NOT be included in calculating the limit (e.g., if the client requests that only a single result be returned, and multiple matches are present, then the DAV:multistatus response will include one DAV:response for the matching resource and one DAV:response for the 507 status on the Request-URI).
服务器还应该在附加的DAV:response元素中包含部分结果。如果应用了客户端请求的限制，则在计算限制时不得包括请求URI的507响应（例如，如果客户端请求仅返回一个结果，并且存在多个匹配项，则DAV:multistatus响应将包括一个用于匹配资源的DAV:response和一个用于请求URI上507状态的DAV:response）。
In this example, the client requests that the server search for address object resources that contain a NICKNAME property whose value equals some specific text and return specific vCard properties for those vCards found. In addition, the DAV:getetag property is also requested and returned as part of the response.
在本例中，客户端请求服务器搜索包含昵称属性（其值等于某些特定文本）的地址对象资源，并为找到的那些vCard返回特定vCard属性。此外，DAV:getetag属性也作为响应的一部分被请求和返回。
>> Request <<
>> Request <<
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-query xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
<C:address-data>
<C:prop name="VERSION"/>
<C:prop name="UID"/>
<C:prop name="NICKNAME"/>
<C:prop name="EMAIL"/>
<C:prop name="FN"/>
</C:address-data>
</D:prop>
<C:filter>
<C:prop-filter name="NICKNAME">
<C:text-match collation="i;unicode-casemap"
match-type="equals"
>me</C:text-match>
</C:prop-filter>
</C:filter>
</C:addressbook-query>
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-query xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
<C:address-data>
<C:prop name="VERSION"/>
<C:prop name="UID"/>
<C:prop name="NICKNAME"/>
<C:prop name="EMAIL"/>
<C:prop name="FN"/>
</C:address-data>
</D:prop>
<C:filter>
<C:prop-filter name="NICKNAME">
<C:text-match collation="i;unicode-casemap"
match-type="equals"
>me</C:text-match>
</C:prop-filter>
</C:filter>
</C:addressbook-query>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/v102.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fb"</D:getetag>
<C:address-data>BEGIN:VCARD
VERSION:3.0
NICKNAME:me
UID:34222-232@example.com
FN:Cyrus Daboo
EMAIL:daboo@example.com
END:VCARD
</C:address-data>
</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:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/v102.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fb"</D:getetag>
<C:address-data>BEGIN:VCARD
VERSION:3.0
NICKNAME:me
UID:34222-232@example.com
FN:Cyrus Daboo
EMAIL:daboo@example.com
END:VCARD
</C:address-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
8.6.4. Example: Partial Retrieval of vCards Matching a Full Name or Email Address
8.6.4. 示例：部分检索与全名或电子邮件地址匹配的vCard
In this example, the client requests that the server search for address object resources that contain a FN property whose value contains some specific text or that contain an EMAIL property whose value contains other text and return specific vCard properties for those vCards found. In addition, the DAV:getetag property is also requested and returned as part of the response.
在此示例中，客户端请求服务器搜索包含FN属性（其值包含某些特定文本）或包含电子邮件属性（其值包含其他文本）的地址对象资源，并为找到的那些vCard返回特定vCard属性。此外，DAV:getetag属性也作为响应的一部分被请求和返回。
>> Request <<
>> Request <<
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-query xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
<C:address-data>
<C:prop name="VERSION"/>
<C:prop name="UID"/>
<C:prop name="NICKNAME"/>
<C:prop name="EMAIL"/>
<C:prop name="FN"/>
</C:address-data>
</D:prop>
<C:filter test="anyof">
<C:prop-filter name="FN">
<C:text-match collation="i;unicode-casemap"
match-type="contains"
>daboo</C:text-match>
</C:prop-filter>
<C:prop-filter name="EMAIL">
<C:text-match collation="i;unicode-casemap"
match-type="contains"
>daboo</C:text-match>
</C:prop-filter>
</C:filter>
</C:addressbook-query>
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-query xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
<C:address-data>
<C:prop name="VERSION"/>
<C:prop name="UID"/>
<C:prop name="NICKNAME"/>
<C:prop name="EMAIL"/>
<C:prop name="FN"/>
</C:address-data>
</D:prop>
<C:filter test="anyof">
<C:prop-filter name="FN">
<C:text-match collation="i;unicode-casemap"
match-type="contains"
>daboo</C:text-match>
</C:prop-filter>
<C:prop-filter name="EMAIL">
<C:text-match collation="i;unicode-casemap"
match-type="contains"
>daboo</C:text-match>
</C:prop-filter>
</C:filter>
</C:addressbook-query>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/v102.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fb"</D:getetag>
<C:address-data>BEGIN:VCARD
VERSION:3.0
NICKNAME:me
UID:34222-232@example.com
FN:David Boo
EMAIL:daboo@example.com
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/v102.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fb"</D:getetag>
<C:address-data>BEGIN:VCARD
VERSION:3.0
NICKNAME:me
UID:34222-232@example.com
FN:David Boo
EMAIL:daboo@example.com
END:VCARD
</C:address-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/home/bernard/addressbook/v104.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fc"</D:getetag>
<C:address-data>BEGIN:VCARD
VERSION:3.0
NICKNAME:oliver
UID:34222-23222@example.com
FN:Oliver Daboo
EMAIL:oliver@example.com
END:VCARD
</C:address-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
END:VCARD
</C:address-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/home/bernard/addressbook/v104.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fc"</D:getetag>
<C:address-data>BEGIN:VCARD
VERSION:3.0
NICKNAME:oliver
UID:34222-23222@example.com
FN:Oliver Daboo
EMAIL:oliver@example.com
END:VCARD
</C:address-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
In this example, the client requests that the server search for address object resources that contain a FN property whose value contains some specific text and return the DAV:getetag property for two results only. The server response includes a 507 status for the Request-URI indicating that there were more than two resources that matched the query, but that the server truncated the result set as requested by the client.
在本例中，客户机请求服务器搜索包含FN属性（其值包含某些特定文本）的地址对象资源，并仅为两个结果返回DAV:getetag属性。服务器响应包括请求URI的507状态，指示有两个以上的资源与查询匹配，但服务器根据客户端的请求截断了结果集。
>> Request <<
>> Request <<
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-query xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-query xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
</D:prop>
<C:filter test="anyof">
<C:prop-filter name="FN">
<C:text-match collation="i;unicode-casemap"
match-type="contains"
>daboo</C:text-match>
</C:prop-filter>
</C:filter>
<C:limit>
<C:nresults>2</C:nresults>
</C:limit>
</C:addressbook-query>
<D:prop>
<D:getetag/>
</D:prop>
<C:filter test="anyof">
<C:prop-filter name="FN">
<C:text-match collation="i;unicode-casemap"
match-type="contains"
>daboo</C:text-match>
</C:prop-filter>
</C:filter>
<C:limit>
<C:nresults>2</C:nresults>
</C:limit>
</C:addressbook-query>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/</D:href>
<D:status>HTTP/1.1 507 Insufficient Storage</D:status>
<D:error><D:number-of-matches-within-limits/></D:error>
<D:responsedescription xml:lang="en">
Only two matching records were returned
</D:responsedescription>
</D:response>
<D:response>
<D:href>/home/bernard/addressbook/v102.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fb"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/home/bernard/addressbook/v104.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fc"</D:getetag>
</D:prop>
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/</D:href>
<D:status>HTTP/1.1 507 Insufficient Storage</D:status>
<D:error><D:number-of-matches-within-limits/></D:error>
<D:responsedescription xml:lang="en">
Only two matching records were returned
</D:responsedescription>
</D:response>
<D:response>
<D:href>/home/bernard/addressbook/v102.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fb"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/home/bernard/addressbook/v104.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fc"</D:getetag>
</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:multistatus>
The CARDDAV:addressbook-multiget REPORT is used to retrieve specific address object resources from within a collection, if the Request-URI is a collection, or to retrieve a specific address object resource, if the Request-URI is an address object resource. This report is similar to the CARDDAV:addressbook-query REPORT (see Section 8.6), except that it takes a list of DAV:href elements instead of a CARDDAV:filter element to determine which address object resources to return.
如果请求URI是集合，则使用CARDDAV:addressbook multiget报告从集合中检索特定的地址对象资源；如果请求URI是地址对象资源，则使用该报告检索特定的地址对象资源。此报告类似于CARDDAV:addressbook查询报告（请参见第8.6节），不同之处在于它使用一个DAV:href元素列表而不是CARDDAV:filter元素来确定要返回的地址对象资源。
Support for the addressbook-multiget REPORT is REQUIRED.
需要对addressbook multiget报告的支持。
Marshalling:
编组：
The request body MUST be a CARDDAV:addressbook-multiget XML element (see Section 10.7), which MUST contain at least one DAV:href XML element and one optional CARDDAV:address-data element as defined in Section 10.4. If DAV:href elements are present, the scope of the request is the set of resources identified by these elements, which all need to be members (not necessarily internal members) of the resource identified by the Request-URI. Otherwise, the scope is the resource identified by the Request-URI itself.
请求主体必须是CARDDAV:addressbook multiget XML元素（参见第10.7节），该元素必须至少包含一个DAV:href XML元素和一个可选的CARDDAV:address数据元素，如第10.4节所定义。如果存在DAV:href元素，则请求的范围是由这些元素标识的资源集，它们都需要是由请求URI标识的资源的成员（不一定是内部成员）。否则，作用域就是由请求URI本身标识的资源。
The request MUST include a Depth: 0 header; however, the actual scope of the REPORT is determined as described above.
请求必须包含深度：0标头；然而，报告的实际范围如上所述确定。
The response body for a successful request MUST be a DAV:multistatus XML element.
成功请求的响应体必须是DAV:multistatusxml元素。
The response body for a successful CARDDAV:addressbook-multiget REPORT request MUST contain a DAV:response element for each address object resource referenced by the provided set of DAV:href elements. Address data is returned in the CARDDAV:address-data element inside the DAV:prop element.
对于所提供的一组DAV:href元素引用的每个地址对象资源，成功的CARDDAV:addressbook multiget报告请求的响应正文必须包含一个DAV:response元素。地址数据在DAV:prop元素内的CARDDAV:Address数据元素中返回。
In the case of an error accessing any of the provided DAV:href resources, the server MUST return the appropriate error status code in the DAV:status element of the corresponding DAV:response element.
如果访问任何提供的DAV:href资源时出错，服务器必须在相应DAV:response元素的DAV:status元素中返回相应的错误状态代码。
Preconditions:
先决条件：
(CARDDAV:supported-address-data): The attributes "content-type" and "version" of the CARDDAV:address-data XML elements (see Section 10.4) specify a media type supported by the server for address object resources.
（CARDDAV:supported address data）：CARDDAV:address数据XML元素的属性“内容类型”和“版本”（请参见第10.4节）指定服务器支持的地址对象资源的媒体类型。
Postconditions:
后条件：
None.
没有一个
In this example, the client requests the server to return specific vCard properties of the address components referenced by specific URIs. In addition, the DAV:getetag property is also requested and returned as part of the response. Note that, in this example, the resource at http://addressbook.example.com/home/bernard/addressbook/vcf1.vcf does not exist, resulting in an error status response.
在本例中，客户端请求服务器返回特定URI引用的地址组件的特定vCard属性。此外，DAV:getetag属性也作为响应的一部分被请求和返回。请注意，在本例中，位于http://addressbook.example.com/home/bernard/addressbook/vcf1.vcf 不存在，导致错误状态响应。
>> Request <<
>> Request <<
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-multiget xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
<C:address-data>
<C:prop name="VERSION"/>
<C:prop name="UID"/>
<C:prop name="NICKNAME"/>
<C:prop name="EMAIL"/>
<C:prop name="FN"/>
</C:address-data>
</D:prop>
<D:href>/home/bernard/addressbook/vcf102.vcf</D:href>
<D:href>/home/bernard/addressbook/vcf1.vcf</D:href>
</C:addressbook-multiget>
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-multiget xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
<C:address-data>
<C:prop name="VERSION"/>
<C:prop name="UID"/>
<C:prop name="NICKNAME"/>
<C:prop name="EMAIL"/>
<C:prop name="FN"/>
</C:address-data>
</D:prop>
<D:href>/home/bernard/addressbook/vcf102.vcf</D:href>
<D:href>/home/bernard/addressbook/vcf1.vcf</D:href>
</C:addressbook-multiget>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/vcf102.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fb"</D:getetag>
<C:address-data>BEGIN:VCARD
VERSION:3.0
NICKNAME:me
UID:34222-232@example.com
FN:Cyrus Daboo
EMAIL:daboo@example.com
END:VCARD
</C:address-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/home/bernard/addressbook/vcf1.vcf</D:href>
<D:status>HTTP/1.1 404 Resource not found</D:status>
</D:response>
</D:multistatus>
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/vcf102.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"23ba4d-ff11fb"</D:getetag>
<C:address-data>BEGIN:VCARD
VERSION:3.0
NICKNAME:me
UID:34222-232@example.com
FN:Cyrus Daboo
EMAIL:daboo@example.com
END:VCARD
</C:address-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/home/bernard/addressbook/vcf1.vcf</D:href>
<D:status>HTTP/1.1 404 Resource not found</D:status>
</D:response>
</D:multistatus>
In this example, the client requests the server to return vCard v4.0 data of the address components referenced by specific URIs. In addition, the DAV:getetag property is also requested and returned as part of the response. Note that, in this example, the resource at http://addressbook.example.com/home/bernard/addressbook/vcf3.vcf exists but in a media type format that the server is unable to convert, resulting in an error status response.
在本例中，客户端请求服务器返回特定URI引用的地址组件的vCard v4.0数据。此外，DAV:getetag属性也作为响应的一部分被请求和返回。请注意，在本例中，位于http://addressbook.example.com/home/bernard/addressbook/vcf3.vcf 存在，但服务器无法转换媒体类型格式，导致错误状态响应。
>> Request <<
>> Request <<
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
REPORT /home/bernard/addressbook/ HTTP/1.1
Host: addressbook.example.com
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-multiget xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
<C:address-data content-type='text/vcard' version='4.0'/>
</D:prop>
<D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
</C:addressbook-multiget>
<?xml version="1.0" encoding="utf-8" ?>
<C:addressbook-multiget xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:prop>
<D:getetag/>
<C:address-data content-type='text/vcard' version='4.0'/>
</D:prop>
<D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
</C:addressbook-multiget>
>> Response <<
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
<D:status>HTTP/1.1 415 Unsupported Media Type</D:status>
<D:error><C:supported-address-data-conversion/></D:error>
<D:responsedescription>Unable to convert from vCard v3.0
to vCard v4.0</D:responsedescription>
</D:response>
</D:multistatus>
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:carddav">
<D:response>
<D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
<D:status>HTTP/1.1 415 Unsupported Media Type</D:status>
<D:error><C:supported-address-data-conversion/></D:error>
<D:responsedescription>Unable to convert from vCard v3.0
to vCard v4.0</D:responsedescription>
</D:response>
</D:multistatus>
Clients may not need all the properties in a vCard object when presenting information to the user, or looking up specific items for their email address, for example. Since some property data can be large (e.g., PHOTO or SOUND with in-line content) clients can choose to ignore those by only requesting the specific items it knows it will use, through use of the CARDDAV:address-data XML element in the relevant reports.
例如，在向用户显示信息或查找其电子邮件地址的特定项目时，客户端可能不需要vCard对象中的所有属性。由于某些属性数据可能很大（例如，带有内嵌内容的照片或声音），因此客户端可以选择忽略这些数据，只通过在相关报告中使用CARDDAV:address数据XML元素请求它知道将使用的特定项。
However, if a client needs to make a change to a vCard, it can only change the entire vCard data via a PUT request. There is no way to incrementally make a change to a set of properties within a vCard object resource. As a result, the client will have to cache the entire set of properties on a resource that is being changed.
但是，如果客户端需要更改vCard，则只能通过PUT请求更改整个vCard数据。无法增量更改vCard对象资源中的一组属性。因此，客户机必须在正在更改的资源上缓存整个属性集。
When resources are accessed by multiple clients, the possibility of clients overwriting each other's changes exists. To alleviate this, clients SHOULD use the If-Match request header on PUT requests with the ETag of the previously retrieved resource data to check whether the resource was modified since it was previously retrieved. If a precondition failure occurs, clients need to reload the resource and go through their own merge or conflict resolution process before writing back the data (again using the If-Match check).
当多个客户端访问资源时，客户端可能会覆盖彼此的更改。为了缓解这种情况，客户机应该在PUT请求上使用If Match request头和以前检索到的资源数据的ETag，以检查资源是否在以前检索到后进行了修改。如果先决条件失败，客户端需要重新加载资源，并在写回数据之前完成自己的合并或冲突解决过程（再次使用If匹配检查）。
When CardDAV clients need to be configured, the key piece of information that they require is the principal-URL of the user whose address book information is desired. Servers SHOULD support the DAV:current-user-principal-URL property as defined in [RFC5397] to give clients a fast way to locate user principals.
当需要配置CardDAV客户端时，它们需要的关键信息是需要其通讯簿信息的用户的主要URL。服务器应支持[RFC5397]中定义的DAV:current user principal URL属性，以便为客户端提供快速查找用户主体的方法。
Given support for SRV records (Section 11) and DAV:current-user-principal-URL [RFC5397], users only need enter a user identifier, host name, and password to configure their client. The client would take the host name and do an SRV lookup to locate the CardDAV server, then execute an authenticated PROPFIND on the root/resource looking for the DAV:current-user-principal-URL property. The value returned gives the client direct access to the user's principal-URL and from there all the related CardDAV properties needed to locate address books.
由于支持SRV记录（第11节）和DAV：当前用户主体URL[RFC5397]，用户只需输入用户标识符、主机名和密码即可配置其客户端。客户端将获取主机名并执行SRV查找以定位CardDAV服务器，然后在根/资源上执行经过身份验证的PROPFIND，以查找DAV:current user principal URL属性。返回的值允许客户端直接访问用户的主要URL，并从该URL访问定位通讯簿所需的所有相关CardDAV属性。
For use cases of address book sharing, one might wish to find the address book belonging to another user. To find other users' address books on the same server, the DAV:principal-property-search REPORT [RFC3744] can be used to search principals for matching properties and return specified properties for the matching principal resources. To search for an address book owned by a user named "Laurie", the REPORT request body would look like this:
对于通讯簿共享的用例，可能希望找到属于另一个用户的通讯簿。要在同一服务器上查找其他用户的通讯簿，可以使用DAV:principal属性搜索报告[RFC3744]搜索主体以查找匹配的属性，并返回匹配主体资源的指定属性。要搜索名为“Laurie”的用户拥有的通讯簿，报告请求主体如下所示：
<?xml version="1.0" encoding="utf-8" ?>
<D:principal-property-search xmlns:D="DAV:">
<D:property-search>
<D:prop>
<D:displayname/>
</D:prop>
<D:match>Laurie</D:match>
</D:property-search>
<D:prop>
<C:addressbook-home-set
xmlns:C="urn:ietf:params:xml:ns:carddav"/>
<D:displayname/>
</D:prop>
</D:principal-property-search>
<?xml version="1.0" encoding="utf-8" ?>
<D:principal-property-search xmlns:D="DAV:">
<D:property-search>
<D:prop>
<D:displayname/>
</D:prop>
<D:match>Laurie</D:match>
</D:property-search>
<D:prop>
<C:addressbook-home-set
xmlns:C="urn:ietf:params:xml:ns:carddav"/>
<D:displayname/>
</D:prop>
</D:principal-property-search>
The server performs a case-sensitive or caseless search for a matching string subset of "Laurie" within the DAV:displayname property. Thus, the server might return "Laurie Dusseault", "Laurier Desruisseaux", or "Wilfrid Laurier" all as matching DAV:displayname values, and the address books for each of these.
服务器在DAV:displayname属性中对匹配的字符串子集“Laurie”执行区分大小写或无大小写的搜索。因此，服务器可能会返回“Laurie Dusseault”、“Laurier desruissaux”或“Wilfrid Laurier”作为匹配的DAV:displayname值，以及每个值的地址簿。
Name: addressbook
姓名：通讯录
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Specifies the resource type of an address book collection.
目的：指定通讯簿集合的资源类型。
Description: See Section 5.2.
说明：见第5.2节。
Definition:
定义：
<!ELEMENT addressbook EMPTY>
<!ELEMENT addressbook EMPTY>
Name: supported-collation
名称：支持的排序规则
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Identifies a single collation via its collation identifier as defined by [RFC4790].
目的：通过[RFC4790]定义的排序规则标识符标识单个排序规则。
Description: The CARDDAV:supported-collation contains the text of a collation identifier as described in Section 8.3.1.
说明：CARDDAV:支持的排序规则包含第8.3.1节所述的排序规则标识符文本。
Definition:
定义：
<!ELEMENT supported-collation (#PCDATA)>
<!-- PCDATA value: collation identifier -->
<!ELEMENT supported-collation (#PCDATA)>
<!-- PCDATA value: collation identifier -->
Name: addressbook-query
名称：地址簿查询
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Defines a report for querying address book data
用途：定义用于查询通讯簿数据的报表
Description: See Section 8.6.
说明：见第8.6节。
Definition:
定义：
<!ELEMENT addressbook-query ((DAV:allprop |
DAV:propname |
DAV:prop)?, filter, limit?)>
<!ELEMENT addressbook-query ((DAV:allprop |
DAV:propname |
DAV:prop)?, filter, limit?)>
Name: address-data
名称：地址数据
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Specifies one of the following:
目的：指定以下内容之一：
1. The parts of an address object resource that should be returned by a given address book REPORT request, and the media type and version for the returned data; or
1. 给定通讯簿报告请求应返回的地址对象资源部分，以及返回数据的媒体类型和版本；或
2. The content of an address object resource in a response to an address book REPORT request.
2. 对通讯簿报告请求的响应中地址对象资源的内容。
Description: When used in an address book REPORT request, the CARDDAV:address-data XML element specifies which parts of address object resources need to be returned in the response. If the CARDDAV:address-data XML element doesn't contain any CARDDAV:prop elements, address object resources will be returned in their entirety. Additionally, a media type and version can be specified to request that the server return the data in that format if possible.
描述：在地址簿报告请求中使用时，CARDDAV:address数据XML元素指定响应中需要返回地址对象资源的哪些部分。如果CARDDAV:address数据XML元素不包含任何CARDDAV:prop元素，则将返回全部地址对象资源。此外，如果可能，还可以指定媒体类型和版本，以请求服务器以该格式返回数据。
Finally, when used in an address book REPORT response, the CARDDAV:address-data XML element specifies the content of an address object resource. Given that XML parsers normalize the
最后，当在通讯簿报告响应中使用时，CARDDAV:address数据XML元素指定地址对象资源的内容。假设XML解析器将
two-character sequence CRLF (US-ASCII decimal 13 and US-ASCII decimal 10) to a single LF character (US-ASCII decimal 10), the CR character (US-ASCII decimal 13) MAY be omitted in address object resources specified in the CARDDAV:address-data XML element. Furthermore, address object resources specified in the CARDDAV:address-data XML element MAY be invalid per their media type specification if the CARDDAV:address-data XML element part of the address book REPORT request did not specify required vCard properties (e.g., UID, etc.) or specified a CARDDAV:prop XML element with the "novalue" attribute set to "yes".
从两个字符序列CRLF（US-ASCII十进制13和US-ASCII十进制10）到单个LF字符（US-ASCII十进制10），可以在CARDDAV:address data XML元素中指定的地址对象资源中省略CR字符（US-ASCII十进制13）。此外，如果通讯簿报告请求的CARDDAV:address数据XML元素部分未指定所需的vCard属性（例如UID等），或未指定带有“novalue”的CARDDAV:prop XML元素，则CARDDAV:address数据XML元素中指定的地址对象资源根据其媒体类型规范可能无效属性设置为“是”。
Note: The CARDDAV:address-data XML element is specified in requests and responses inside the DAV:prop XML element as if it were a WebDAV property. However, the CARDDAV:address-data XML element is not a WebDAV property and as such it is not returned in PROPFIND responses nor used in PROPPATCH requests.
注意：CARDDAV:address数据XML元素在DAV:prop XML元素内的请求和响应中指定，就像它是WebDAV属性一样。但是，CARDDAV:address数据XML元素不是WebDAV属性，因此它不会在PROPFIND响应中返回，也不会在PROPPATCH请求中使用。
Note: The address data embedded within the CARDDAV:address-data XML element MUST follow the standard XML character data encoding rules, including use of <, >, & etc., entity encoding or the use of a <![CDATA[ ... ]]> construct. In the latter case, the vCard data cannot contain the character sequence "]]>", which is the end delimiter for the CDATA section.
注意：嵌入CARDDAV:address数据XML元素中的地址数据必须遵循标准的XML字符数据编码规则，包括使用<>&；等，实体编码或使用<<！[CDATA[…]]>构造。在后一种情况下，vCard数据不能包含字符序列“]]>”，这是CDATA节的结束分隔符。
Definition:
定义：
<!ELEMENT address-data (allprop | prop*)>
<!ELEMENT address-data (allprop | prop*)>
when nested in the DAV:prop XML element in an address book REPORT request to specify which parts of address object resources should be returned in the response;
当嵌套在地址簿报告请求中的DAV:prop XML元素中时，指定响应中应返回地址对象资源的哪些部分；
<!ELEMENT address-data (#PCDATA)>
<!-- PCDATA value: address data -->
<!ELEMENT address-data (#PCDATA)>
<!-- PCDATA value: address data -->
when nested in the DAV:prop XML element in an address book REPORT response to specify the content of a returned address object resource.
嵌套在通讯簿报告响应中的DAV:prop XML元素中时，用于指定返回的地址对象资源的内容。
<!ATTLIST address-data content-type CDATA "text/vcard"
version CDATA "3.0">
<!-- content-type value: a MIME media type -->
<!-- version value: a version string -->
<!ATTLIST address-data content-type CDATA "text/vcard"
version CDATA "3.0">
<!-- content-type value: a MIME media type -->
<!-- version value: a version string -->
attributes can be used on each variant of the CALDAV:address-data XML element.
属性可用于CALDAV:address数据XML元素的每个变体。
Name: allprop
姓名：allprop
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Specifies that all vCard properties shall be returned.
目的：指定应返回所有vCard属性。
Description: This element can be used when the client wants all vCard properties of components returned by a report.
描述：当客户端希望报告返回组件的所有vCard属性时，可以使用此元素。
Definition:
定义：
<!ELEMENT allprop EMPTY>
<!ELEMENT allprop EMPTY>
Note: The CARDDAV:allprop element defined here has the same name as the DAV:allprop element defined in WebDAV. However, the CARDDAV:allprop element defined here uses the "urn:ietf:params:xml:ns:carddav" namespace, as opposed to the "DAV:" namespace used for the DAV:allprop element defined in WebDAV.
注意：此处定义的CARDDAV:allprop元素与WebDAV中定义的DAV:allprop元素具有相同的名称。但是，此处定义的CARDDAV:allprop元素使用“urn:ietf:params:xml:ns:CARDDAV”命名空间，而不是WebDAV中定义的DAV:allprop元素使用的“DAV:”命名空间。
Name: prop
姓名：道具
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Defines which vCard properties to return in the response.
目的：定义要在响应中返回的vCard属性。
Description: The "name" attribute specifies the name of the vCard property to return (e.g., "NICKNAME"). The "novalue" attribute can be used by clients to request that the actual value of the property not be returned (if the "novalue" attribute is set to "yes"). In that case, the server will return just the vCard property name and any vCard parameters and a trailing ":" without the subsequent value data.
描述：“name”属性指定要返回的vCard属性的名称（例如，“昵称”）。客户端可以使用“novalue”属性请求不返回属性的实际值（如果“novalue”属性设置为“yes”）。在这种情况下，服务器将只返回vCard属性名称和任何vCard参数以及尾随“：”而不返回后续值数据。
vCard allows a "group" prefix to appear before a property name in the vCard data. When the "name" attribute does not specify a group prefix, it MUST match properties in the vCard data without a group prefix or with any group prefix. When the "name" attribute includes a group prefix, it MUST match properties that have exactly the same group prefix and name. For example, a "name" set to "TEL" will match "TEL", "X-ABC.TEL", and "X-ABC-1.TEL" vCard properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL" vCard property only; it will not match "TEL" or "X-ABC-1.TEL".
vCard允许在vCard数据中的属性名称之前显示“组”前缀。当“name”属性未指定组前缀时，它必须匹配vCard数据中不带组前缀或任何组前缀的属性。当“name”属性包含组前缀时，它必须匹配具有完全相同的组前缀和名称的属性。例如，设置为“TEL”的“name”将匹配“TEL”、“X-ABC.TEL”和“X-ABC-1.TEL”vCard属性。设置为“X-ABC.TEL”的“名称”将仅与“X-ABC.TEL”vCard属性匹配；它将与“TEL”或“X-ABC-1.TEL”不匹配。
Definition:
定义：
<!ELEMENT prop EMPTY>
<!ELEMENT prop EMPTY>
<!ATTLIST prop name CDATA #REQUIRED
novalue (yes | no) "no">
<!-- name value: a vCard property name -->
<!-- novalue value: "yes" or "no" -->
<!ATTLIST prop name CDATA #REQUIRED
novalue (yes | no) "no">
<!-- name value: a vCard property name -->
<!-- novalue value: "yes" or "no" -->
Note: The CARDDAV:prop element defined here has the same name as the DAV:prop element defined in WebDAV. However, the CARDDAV:prop element defined here uses the "urn:ietf:params:xml:ns:carddav" namespace, as opposed to the "DAV:" namespace used for the DAV:prop element defined in WebDAV.
注意：此处定义的CARDDAV:prop元素与WebDAV中定义的DAV:prop元素具有相同的名称。但是，此处定义的CARDDAV:prop元素使用“urn:ietf:params:xml:ns:CARDDAV”命名空间，而不是WebDAV中定义的DAV:prop元素使用的“DAV:”命名空间。
Name: filter
名称：过滤器
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Determines which matching objects are returned.
目的：确定返回哪些匹配对象。
Description: The "filter" element specifies the search filter used to match address objects that should be returned by a report. The "test" attribute specifies whether any (logical OR) or all (logical AND) of the prop-filter tests need to match in order for the overall filter to match.
描述：“filter”元素指定用于匹配报表应返回的地址对象的搜索筛选器。“test”属性指定是否需要匹配任何（逻辑OR）或所有（逻辑AND）道具过滤器测试，以使整个过滤器匹配。
Definition:
定义：
<!ELEMENT filter (prop-filter*)>
<!ELEMENT filter (prop-filter*)>
<!ATTLIST filter test (anyof | allof) "anyof">
<!-- test value:
anyof logical OR for prop-filter matches
allof logical AND for prop-filter matches -->
<!ATTLIST filter test (anyof | allof) "anyof">
<!-- test value:
anyof logical OR for prop-filter matches
allof logical AND for prop-filter matches -->
Name: prop-filter
名称：道具过滤器
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Limits the search to specific vCard properties.
目的：将搜索限制为特定vCard属性。
Description: The CARDDAV:prop-filter XML element specifies search criteria on a specific vCard property (e.g., "NICKNAME"). An address object is said to match a CARDDAV:prop-filter if:
描述：CARDDAV:prop filter XML元素指定特定vCard属性（例如，“昵称”）的搜索条件。如果满足以下条件，则称地址对象与CARDDAV:prop过滤器匹配：
* A vCard property of the type specified by the "name" attribute exists, and the CARDDAV:prop-filter is empty, or it matches any specified CARDDAV:text-match or CARDDAV:param-filter conditions. The "test" attribute specifies whether any (logical OR) or all (logical AND) of the text-filter and param-filter tests need to match in order for the overall filter to match.
* 存在由“name”属性指定的类型的vCard属性，并且CARDDAV:prop筛选器为空，或者它匹配任何指定的CARDDAV:text match或CARDDAV:param筛选器条件。“test”属性指定文本筛选器和参数筛选器测试中的任何（逻辑或）或所有（逻辑与）是否需要匹配，以使整个筛选器匹配。
or:
或：
* A vCard property of the type specified by the "name" attribute does not exist, and the CARDDAV:is-not-defined element is specified.
* 由“name”属性指定的类型的vCard属性不存在，并且指定了CARDDAV:未定义元素。
vCard allows a "group" prefix to appear before a property name in the vCard data. When the "name" attribute does not specify a group prefix, it MUST match properties in the vCard data without a group prefix or with any group prefix. When the "name" attribute includes a group prefix, it MUST match properties that have exactly the same group prefix and name. For example, a "name" set to "TEL" will match "TEL", "X-ABC.TEL", "X-ABC-1.TEL" vCard properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL" vCard property only, it will not match "TEL" or "X-ABC-1.TEL".
vCard允许在vCard数据中的属性名称之前显示“组”前缀。当“name”属性未指定组前缀时，它必须匹配vCard数据中不带组前缀或任何组前缀的属性。当“name”属性包含组前缀时，它必须匹配具有完全相同的组前缀和名称的属性。例如，设置为“TEL”的“name”将匹配“TEL”、“X-ABC.TEL”、“X-ABC-1.TEL”vCard属性。设置为“X-ABC.TEL”的“name”将仅与“X-ABC.TEL”vCard属性匹配，而与“TEL”或“X-ABC-1.TEL”不匹配。
Definition:
定义：
<!ELEMENT prop-filter (is-not-defined |
(text-match*, param-filter*))>
<!ELEMENT prop-filter (is-not-defined |
(text-match*, param-filter*))>
<!ATTLIST prop-filter name CDATA #REQUIRED
test (anyof | allof) "anyof">
<!-- name value: a vCard property name (e.g., "NICKNAME")
test value:
anyof logical OR for text-match/param-filter matches
allof logical AND for text-match/param-filter matches -->
<!ATTLIST prop-filter name CDATA #REQUIRED
test (anyof | allof) "anyof">
<!-- name value: a vCard property name (e.g., "NICKNAME")
test value:
anyof logical OR for text-match/param-filter matches
allof logical AND for text-match/param-filter matches -->
Name: param-filter
名称：参数过滤器
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Limits the search to specific parameter values.
目的：将搜索限制为特定参数值。
Description: The CARDDAV:param-filter XML element specifies search criteria on a specific vCard property parameter (e.g., TYPE) in the scope of a given CARDDAV:prop-filter. A vCard property is said to match a CARDDAV:param-filter if:
描述：CARDDAV:param filter XML元素指定给定CARDDAV:prop筛选器范围内特定vCard属性参数（例如，类型）的搜索条件。在以下情况下，vCard属性称为与CARDDAV:param筛选器匹配：
* A parameter of the type specified by the "name" attribute exists, and the CARDDAV:param-filter is empty, or it matches the CARDDAV:text-match conditions if specified.
* 存在由“name”属性指定的类型的参数，并且CARDDAV:param筛选器为空，或者它与CARDDAV:text匹配条件匹配（如果指定）。
or:
或：
* A parameter of the type specified by the "name" attribute does not exist, and the CARDDAV:is-not-defined element is specified.
* 由“name”属性指定的类型的参数不存在，并且未指定CARDDAV:is-defined元素。
Definition:
定义：
<!ELEMENT param-filter (is-not-defined | text-match)?>
<!ELEMENT param-filter (is-not-defined | text-match)?>
<!ATTLIST param-filter name CDATA #REQUIRED>
<!-- name value: a property parameter name (e.g., "TYPE") -->
<!ATTLIST param-filter name CDATA #REQUIRED>
<!-- name value: a property parameter name (e.g., "TYPE") -->
Name: is-not-defined
名称：未定义
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Specifies that a match should occur if the enclosing vCard property or parameter does not exist.
目的：指定如果封闭vCard属性或参数不存在，则应发生匹配。
Description: The CARDDAV:is-not-defined XML element specifies that a match occurs if the enclosing vCard property or parameter value specified in an address book REPORT request does not exist in the address data being tested.
描述：CARDDAV:is not defined XML元素指定，如果地址簿报告请求中指定的封闭vCard属性或参数值在正在测试的地址数据中不存在，则会发生匹配。
Definition:
定义：
<!ELEMENT is-not-defined EMPTY>
<!ELEMENT is-not-defined EMPTY>
Name: text-match
名称：文本匹配
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Specifies a substring match on a vCard property or parameter value.
目的：指定vCard属性或参数值上的子字符串匹配。
Description: The CARDDAV:text-match XML element specifies text used for a substring match against the vCard property or parameter value specified in an address book REPORT request.
描述：CARDDAV:text match XML元素指定用于与通讯簿报告请求中指定的vCard属性或参数值进行子字符串匹配的文本。
The "collation" attribute is used to select the collation that the server MUST use for character string matching. In the absence of this attribute, the server MUST use the "i;unicode-casemap" collation.
“collation”属性用于选择服务器必须用于字符串匹配的排序规则。如果没有此属性，服务器必须使用“i；unicode casemap”排序规则。
The "negate-condition" attribute is used to indicate that this test returns a match if the text matches, when the attribute value is set to "no", or return a match if the text does not match, if the attribute value is set to "yes". For example, this can be used to match components with a CATEGORIES property not set to PERSON.
“否定条件”属性用于指示当属性值设置为“否”时，如果文本匹配，则此测试返回匹配；如果属性值设置为“是”，则如果文本不匹配，则返回匹配。例如，这可用于匹配“类别”属性未设置为“人”的组件。
The "match-type" attribute is used to indicate the type of match operation to use. Possible choices are:
“匹配类型”属性用于指示要使用的匹配操作的类型。可能的选择包括：
"equals" - an exact match to the target string
“等于”-与目标字符串完全匹配
"contains" - a substring match, matching anywhere within the target string
“包含”-子字符串匹配，匹配目标字符串中的任何位置
"starts-with" - a substring match, matching only at the start of the target string
“以开头”-子字符串匹配，仅在目标字符串的开头匹配
"ends-with" - a substring match, matching only at the end of the target string
“以结尾”-子字符串匹配，仅在目标字符串的结尾匹配
Definition:
定义：
<!ELEMENT text-match (#PCDATA)>
<!-- PCDATA value: string -->
<!ELEMENT text-match (#PCDATA)>
<!-- PCDATA value: string -->
<!ATTLIST text-match collation CDATA "i;unicode-casemap" negate-condition (yes | no) "no" match-type (equals|contains|starts-with|ends-with) "contains">
<!ATTLIST文本匹配排序规则CDATA“i；unicode casemap”否定条件（是|否）“否”匹配类型（等于|包含|以|开始|以|结束）“包含”>
Name: limit
名称：限额
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Specifies different types of limits that can be applied to the results returned by the server.
目的：指定可应用于服务器返回的结果的不同类型的限制。
Description: The CARDDAV:limit XML element can be used to specify different types of limits that the client can request the server to apply to the results returned by the server. Currently, only the CARDDAV:nresults limit can be used; other types of limit could be defined in the future.
描述：CARDDAV:limit XML元素可用于指定客户端可以请求服务器应用于服务器返回结果的不同类型的限制。目前，只能使用CARDDAV:nresults限制；其他类型的限制可以在将来定义。
Definition:
定义：
<!ELEMENT limit (nresults)>
<!ELEMENT limit (nresults)>
Name: nresults
姓名：nresults
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: Specifies a limit on the number of results returned by the server.
目的：指定对服务器返回的结果数的限制。
Description: The CARDDAV:nresults XML element contains a requested maximum number of DAV:response elements to be returned in the response body of a query. The server MAY disregard this limit. The value of this element is an unsigned integer.
描述：CARDDAV:nresults XML元素包含查询响应体中返回的请求的最大DAV:response元素数。服务器可以忽略此限制。此元素的值是无符号整数。
Definition:
定义：
<!ELEMENT nresults (#PCDATA)>
<!-- nresults value: unsigned integer, must be digits -->
<!ELEMENT nresults (#PCDATA)>
<!-- nresults value: unsigned integer, must be digits -->
Name: addressbook-multiget
名称：addressbook multiget
Namespace: urn:ietf:params:xml:ns:carddav
Namespace: urn:ietf:params:xml:ns:carddav
Purpose: CardDAV report used to retrieve specific address objects via their URIs.
用途：CardDAV报告，用于通过特定地址对象的URI检索特定地址对象。
Description: See Section 8.7.
说明：见第8.7节。
Definition:
定义：
<!ELEMENT addressbook-multiget ((DAV:allprop |
DAV:propname |
DAV:prop)?,
DAV:href+)>
<!ELEMENT addressbook-multiget ((DAV:allprop |
DAV:propname |
DAV:prop)?,
DAV:href+)>
[RFC2782] defines a DNS-based service discovery protocol that has been widely adopted as a means of locating particular services within a local area network and beyond, using SRV RRs.
[RFC2782]定义了一种基于DNS的服务发现协议，该协议已被广泛采用，作为使用SRV RRs在局域网内外定位特定服务的一种手段。
This specification adds two service types for use with SRV records:
本规范添加了两种用于SRV记录的服务类型：
carddav: Identifies a CardDAV server that uses HTTP without TLS [RFC2818].
carddav：标识使用HTTP而不使用TLS的carddav服务器[RFC2818]。
carddavs: Identifies a CardDAV server that uses HTTP with TLS [RFC2818].
carddavs：标识使用HTTP和TLS的CardDAV服务器[RFC2818]。
Example: non-TLS service record
示例：非TLS服务记录
_carddav._tcp SRV 0 1 80 addressbook.example.com.
_carddav._TCPSRV 0 1 80 addressbook.example.com。
Example: TLS service
示例：TLS服务
_carddavs._tcp SRV 0 1 443 addressbook.example.com.
_carddavs._TCPSRV 0 1 443 addressbook.example.com。
CardDAV allows internationalized strings to be stored and retrieved for the description of address book collections (see Section 6.2.1).
CardDAV允许存储和检索国际化字符串以描述通讯簿集合（参见第6.2.1节）。
The CARDDAV:addressbook-query REPORT (Section 8.6) includes a text searching option controlled by the CARDDAV:text-match element and details of character handling are covered in the description of that element (see Section 10.5.4).
CARDDAV:addressbook查询报告（第8.6节）包括一个由CARDDAV:text match元素控制的文本搜索选项，该元素的描述中介绍了字符处理的详细信息（见第10.5.4节）。
HTTP protocol transactions are sent in the clear over the network unless protection from snooping is negotiated. This can be accomplished by use of TLS as defined in [RFC2818]. In particular, if HTTP Basic authentication [RFC2617] is available, the server MUST allow TLS to be used at the same time, and it SHOULD prevent use of Basic authentication when TLS is not in use. Clients SHOULD use TLS whenever possible.
HTTP协议事务通过网络以明文形式发送，除非协商防止窥探。这可以通过使用[RFC2818]中定义的TLS来实现。特别是，如果HTTP基本身份验证[RFC2617]可用，则服务器必须允许同时使用TLS，并且应防止在TLS未使用时使用基本身份验证。客户机应尽可能使用TLS。
With the ACL extension [RFC3744] present, WebDAV allows control over who can access (read or write) any resource on the WebDAV server. In addition, WebDAV ACL provides for an "inheritance" mechanism, whereby resources may inherit access privileges from other resources. Often, the "other" resource is a parent collection of the resource itself. Servers are able to support address books that are "private"
在存在ACL扩展[RFC3744]的情况下，WebDAV允许控制谁可以访问（读取或写入）WebDAV服务器上的任何资源。此外，WebDAV ACL还提供了一种“继承”机制，通过这种机制，资源可以从其他资源继承访问权限。通常，“其他”资源是资源本身的父集合。服务器能够支持“专用”的通讯簿
(accessible only to the "owner"), "shared" (accessible to the owner and other specified authenticated users), and "public" (accessible to any authenticated or unauthenticated users). When provisioning address books of a particular type, servers MUST ensure that the correct privileges are applied on creation. In particular, private and shared address books MUST NOT be accessible by unauthenticated users (to prevent data from being automatically searched or indexed by web "crawlers").
（仅可供“所有者”访问）、“共享”（可供所有者和其他指定的经过身份验证的用户访问）和“公共”（可供任何经过身份验证或未经身份验证的用户访问）。设置特定类型的通讯簿时，服务器必须确保在创建时应用正确的权限。特别是，未经身份验证的用户不得访问私人和共享通讯簿（以防止数据被网络“爬虫”自动搜索或索引）。
Clients SHOULD warn users in an appropriate fashion when they copy or move address data from a private address book to a shared address book or public address book. Clients SHOULD provide a clear indication as to which address books are private, shared, or public. Clients SHOULD provide an appropriate warning when changing access privileges for a private or shared address book with data so as to allow unauthenticated users access.
当用户将地址数据从私人通讯簿复制或移动到共享通讯簿或公共通讯簿时，客户端应以适当的方式警告用户。客户应明确指出哪些通讯簿是私有的、共享的或公共的。更改带有数据的私人或共享通讯簿的访问权限时，客户端应提供适当的警告，以允许未经验证的用户访问。
This specification currently relies on standard HTTP authentication mechanisms for identifying users. These comprise Basic and Digest authentication [RFC2617] as well as TLS [RFC2818] using client-side certificates.
该规范目前依赖于标准HTTP身份验证机制来识别用户。这些包括基本和摘要身份验证[RFC2617]以及使用客户端证书的TLS[RFC2818]。
This document uses a URN to describe a new XML namespace conforming to the registry mechanism described in [RFC3688].
本文档使用URN来描述符合[RFC3688]中描述的注册表机制的新XML命名空间。
Registration request for the carddav namespace:
carddav命名空间的注册请求：
URI: urn:ietf:params:xml:ns:carddav
URI: urn:ietf:params:xml:ns:carddav
Registrant Contact: The IESG <iesg@ietf.org>
Registrant Contact: The IESG <iesg@ietf.org>
XML: None - not applicable for namespace registrations.
XML:None-不适用于命名空间注册。
Thanks go to Lisa Dusseault and Bernard Desruisseaux for their work on CalDAV, on which CardDAV is heavily based. The following individuals contributed their ideas and support for writing this specification: Mike Douglass, Stefan Eissing, Helge Hess, Arnaud Quillaud, Julian Reschke, Elias Sinderson, Greg Stein, Wilfredo Sanchez, and Simon Vaillancourt.
感谢Lisa Dusseault和Bernard Desruisseaux对CalDAV所做的工作，CardDAV是CalDAV的重要基础。以下个人为编写本规范贡献了他们的想法和支持：迈克·道格拉斯、斯特凡·艾辛、赫尔格·赫斯、阿诺·奎劳德、朱利安·雷什克、埃利亚斯·辛德森、格雷格·斯坦、威尔弗雷多·桑切斯和西蒙·维兰科特。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2119]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，1997年3月。
[RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile", RFC 2426, September 1998.
[RFC2426]Dawson，F.和T.Howes，“vCard MIME目录配置文件”，RFC 2426，1998年9月。
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2616]菲尔丁，R.，盖蒂斯，J.，莫卧儿，J.，弗莱斯蒂克，H.，马斯特，L.，利奇，P.，和T.伯纳斯李，“超文本传输协议——HTTP/1.1”，RFC 2616，1999年6月。
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999.
[RFC2617]Franks，J.，Hallam Baker，P.，Hostetler，J.，Lawrence，S.，Leach，P.，Lootonen，A.，和L.Stewart，“HTTP认证：基本和摘要访问认证”，RFC 26171999年6月。
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, February 2000.
[RFC2782]Gulbrandsen，A.，Vixie，P.和L.Esibov，“用于指定服务位置（DNS SRV）的DNS RR”，RFC 2782，2000年2月。
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC2818]Rescorla，E.，“TLS上的HTTP”，RFC2818，2000年5月。
[RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. Whitehead, "Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)", RFC 3253, March 2002.
[RFC3253]Clemm，G.，Amsden，J.，Ellison，T.，Kaler，C.，和J.Whitehead，“WebDAV的版本控制扩展（Web分布式创作和版本控制）”，RFC 3253，2002年3月。
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
[RFC3688]Mealling，M.“IETF XML注册表”，BCP 81，RFC 3688，2004年1月。
[RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol", RFC 3744, May 2004.
[RFC3744]Clemm，G.，Reschke，J.，Sedlar，E.，和J.Whitehead，“Web分布式创作和版本控制（WebDAV）访问控制协议”，RFC 3744，2004年5月。
[RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet Application Protocol Collation Registry", RFC 4790, March 2007.
[RFC4790]Newman，C.，Duerst，M.，和A.Gulbrandsen，“互联网应用协议整理注册表”，RFC 47902007年3月。
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
[RFC4918]Dusseault，L.，“用于Web分布式创作和版本控制（WebDAV）的HTTP扩展”，RFC4918，2007年6月。
[RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation Algorithm", RFC 5051, October 2007.
[RFC5051]Crispin，M.，“i；unicode案例图-简单unicode排序算法”，RFC 5051，2007年10月。
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5246]Dierks，T.和E.Rescorla，“传输层安全（TLS）协议版本1.2”，RFC 5246，2008年8月。
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, May 2008.
[RFC5280]Cooper，D.，Santesson，S.，Farrell，S.，Boeyen，S.，Housley，R.，和W.Polk，“Internet X.509公钥基础设施证书和证书撤销列表（CRL）配置文件”，RFC 52802008年5月。
[RFC5397] Sanchez, W. and C. Daboo, "WebDAV Current Principal Extension", RFC 5397, December 2008.
[RFC5397]Sanchez，W.和C.Daboo，“WebDAV当前主要扩展”，RFC 53972008年12月。
[RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring and Versioning (WebDAV)", RFC 5689, September 2009.
[RFC5689]Daboo，C.“用于Web分布式创作和版本控制（WebDAV）的扩展MKCOL”，RFC 5689，2009年9月。
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, August 2011.
[RFC6350]Perreault，S.，“vCard格式规范”，RFC 63502011年8月。
[W3C.REC-xml-20081126] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[W3C.REC-xml-20081126]Bray，T.，Paoli，J.，Sperberg McQueen，C.，Maler，E.，和F.Yergeau，“可扩展标记语言（xml）1.0（第五版）”，万维网联盟建议REC-xml-20081126，2008年11月<http://www.w3.org/TR/2008/REC-xml-20081126>.
[IMSP] Myers, J., "IMSP - Internet Message Support Protocol", Work in Progress, June 1995.
[IMSP]迈尔斯，J.，“IMSP-互联网消息支持协议”，正在进行的工作，1995年6月。
[RFC2244] Newman, C. and J. Myers, "ACAP -- Application Configuration Access Protocol", RFC 2244, November 1997.
[RFC2244]Newman，C.和J.Myers，“ACAP——应用程序配置访问协议”，RFC2244，1997年11月。
[RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006.
[RFC4510]Zeilenga，K.，“轻量级目录访问协议（LDAP）：技术规范路线图”，RFC45102006年6月。
Author's Address
作者地址
Cyrus Daboo Apple, Inc. 1 Infinite Loop Cupertino, CA 95014 USA
赛勒斯·达布苹果公司，美国加利福尼亚州库比蒂诺市无限环路1号，邮编95014
EMail: cyrus@daboo.name
URI: http://www.apple.com/
EMail: cyrus@daboo.name
URI: http://www.apple.com/