mirror of
https://git.friendi.ca/friendica/friendica-addons.git
synced 2024-08-20 21:50:21 +00:00
2691 lines
96 KiB
Text
2691 lines
96 KiB
Text
|
||
|
||
|
||
|
||
|
||
|
||
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)
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Copyright Notice
|
||
|
||
Copyright (c) 2011 IETF Trust and the persons identified as the
|
||
document authors. All rights reserved.
|
||
|
||
This document is subject to BCP 78 and the IETF Trust's Legal
|
||
Provisions Relating to IETF Documents
|
||
(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.
|
||
|
||
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
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 1]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
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
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 2]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 3]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
1. Introduction and Overview
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
The key features of address book support with WebDAV are:
|
||
|
||
1. Ability to use multiple address books with hierarchical layout.
|
||
|
||
2. Ability to control access to individual address books and address
|
||
entries as per WebDAV Access Control List (ACL) [RFC3744].
|
||
|
||
3. Principal collections can be used to enumerate and query other
|
||
users on the system as per 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.
|
||
|
||
5. Well-defined internationalization support through WebDAV's use of
|
||
XML.
|
||
|
||
6. Use of vCards [RFC2426] for well-defined address schema to
|
||
enhance client interoperability.
|
||
|
||
7. Many limited clients (e.g., mobile devices) contain an HTTP stack
|
||
that makes implementing WebDAV much easier than other protocols.
|
||
|
||
The key disadvantage of address book support in WebDAV is:
|
||
|
||
1. Lack of change notification. Many of the alternative protocols
|
||
also lack this ability. However, an extension for push
|
||
notifications could easily be developed.
|
||
|
||
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
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 4]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
An update to vCard -- vCard v4 -- is currently being developed
|
||
[RFC6350] and is compatible with this specification.
|
||
|
||
2. Conventions
|
||
|
||
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].
|
||
|
||
The term "protected" is used in the Conformance field of property
|
||
definitions as defined in Section 15 of [RFC4918].
|
||
|
||
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:
|
||
|
||
1. Element names use the "DAV:" namespace.
|
||
|
||
2. Element ordering is irrelevant unless explicitly stated.
|
||
|
||
3. Extension elements (elements not already defined as valid child
|
||
elements) may be added anywhere, except when explicitly stated
|
||
otherwise.
|
||
|
||
4. Extension attributes (attributes not already defined as valid for
|
||
this element) may be added anywhere, except when explicitly
|
||
stated otherwise.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 5]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
This document inherits, and sometimes extends, DTD productions from
|
||
Section 14 of [RFC4918].
|
||
|
||
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.
|
||
|
||
3. Requirements Overview
|
||
|
||
This section lists what functionality is required of a CardDAV
|
||
server. To advertise support for CardDAV, a server:
|
||
|
||
o MUST support vCard v3 [RFC2426] as a media type for the address
|
||
object resource format;
|
||
|
||
o MUST support WebDAV Class 3 [RFC4918];
|
||
|
||
o MUST support 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 MUST support ETags [RFC2616] with additional requirements
|
||
specified in Section 6.3.2.3 of this document;
|
||
|
||
o MUST support all address book reports defined in Section 8 of this
|
||
document; and
|
||
|
||
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].
|
||
|
||
In addition, a server:
|
||
|
||
o SHOULD support vCard v4 [RFC6350] as a media type for the address
|
||
object resource format;
|
||
|
||
o SHOULD support the extended MKCOL method [RFC5689] to create
|
||
address book collections as defined in Section 6.3.1 of this
|
||
document.
|
||
|
||
o SHOULD support the DAV:current-user-principal-URL property as
|
||
defined in [RFC5397] to give clients a fast way to locate user
|
||
principals.
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 6]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
4. Address Book Data Model
|
||
|
||
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.
|
||
|
||
4.1. Address Book Server
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
5. Address Book Resources
|
||
|
||
5.1. Address Object Resources
|
||
|
||
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
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 7]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
described below. The requirements in this section pertain to vCard
|
||
address data or formats that follow the semantics of vCard data.
|
||
|
||
Address object resources contained in address book collections MUST
|
||
contain a single vCard component only.
|
||
|
||
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.
|
||
|
||
5.1.1. Data Type Conversion
|
||
|
||
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).
|
||
|
||
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.
|
||
|
||
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).
|
||
|
||
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.
|
||
|
||
5.1.1.1. Additional Precondition for GET
|
||
|
||
This specification creates additional preconditions for the GET
|
||
method.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 8]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
5.2. Address Book Collections
|
||
|
||
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:
|
||
|
||
<!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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 9]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
Multiple address book collections MAY be children of the same
|
||
collection.
|
||
|
||
6. Address Book Feature
|
||
|
||
6.1. Address Book Support
|
||
|
||
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.
|
||
|
||
6.1.1. Example: Using OPTIONS for the Discovery of Support for CardDAV
|
||
|
||
>> Request <<
|
||
|
||
OPTIONS /addressbooks/users/ HTTP/1.1
|
||
Host: addressbook.example.com
|
||
|
||
>> 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
|
||
|
||
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.
|
||
|
||
6.2. Address Book Properties
|
||
|
||
6.2.1. CARDDAV:addressbook-description Property
|
||
|
||
Name: addressbook-description
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Provides a human-readable description of the address book
|
||
collection.
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 10]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!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>
|
||
|
||
6.2.2. CARDDAV:supported-address-data Property
|
||
|
||
Name: supported-address-data
|
||
|
||
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.
|
||
|
||
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
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 11]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!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 -->
|
||
|
||
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>
|
||
|
||
6.2.3. CARDDAV:max-resource-size Property
|
||
|
||
Name: max-resource-size
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 12]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!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>
|
||
|
||
6.3. Creating Resources
|
||
|
||
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.
|
||
|
||
6.3.1. Extended MKCOL Method
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 13]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
6.3.1.1. Example - Successful MKCOL Request
|
||
|
||
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.
|
||
|
||
>> Request <<
|
||
|
||
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>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 14]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
>> 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
|
||
|
||
<?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>
|
||
|
||
6.3.2. Creating Address Object Resources
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 15]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
>> Request <<
|
||
|
||
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
|
||
|
||
>> Response <<
|
||
|
||
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.
|
||
|
||
File names for vCards are commonly suffixed by ".vcf", and clients
|
||
may choose to use the same convention for URLs.
|
||
|
||
6.3.2.1. Additional Preconditions for PUT, COPY, and MOVE
|
||
|
||
This specification creates additional preconditions for the PUT,
|
||
COPY, and MOVE methods. These preconditions apply:
|
||
|
||
o When a PUT operation of an address object resource into an address
|
||
book collection occurs.
|
||
|
||
o When a COPY or MOVE operation of an address object resource into
|
||
an address book collection occurs.
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 16]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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: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: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.
|
||
|
||
<!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: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.
|
||
|
||
6.3.2.2. Non-Standard vCard Properties and Parameters
|
||
|
||
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-".
|
||
|
||
Servers MUST support the use of non-standard properties and
|
||
parameters in address object resources stored via the PUT method.
|
||
|
||
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"
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 17]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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".
|
||
|
||
6.3.2.3. Address Object Resource Entity Tag
|
||
|
||
The DAV:getetag property MUST be defined and set to a strong entity
|
||
tag on all address object resources.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
7. Address Book Access Control
|
||
|
||
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.
|
||
|
||
7.1. Additional Principal Properties
|
||
|
||
This section defines additional properties for WebDAV principal
|
||
resources as defined in [RFC3744].
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 18]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
7.1.1. CARDDAV:addressbook-home-set Property
|
||
|
||
Name: addressbook-home-set
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!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>
|
||
|
||
7.1.2. CARDDAV:principal-address Property
|
||
|
||
Name: principal-address
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 19]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!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>
|
||
|
||
8. Address Book Reports
|
||
|
||
This section defines the reports that CardDAV servers MUST support on
|
||
address book collections and address object resources.
|
||
|
||
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.
|
||
|
||
Some of these reports allow address data (from possibly multiple
|
||
resources) to be returned.
|
||
|
||
8.1. REPORT Method
|
||
|
||
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
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 20]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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]).
|
||
|
||
8.2. Ordinary Collections
|
||
|
||
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.
|
||
|
||
8.3. Searching Text: Collations
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
CardDAV servers are REQUIRED to support the "i;ascii-casemap"
|
||
[RFC4790] and "i;unicode-casemap" [RFC5051] collations and MAY
|
||
support other collations.
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 21]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
Wildcards (as defined in [RFC4790], Section 3.2) MUST NOT be used in
|
||
the collation identifier.
|
||
|
||
If the client chooses a collation not supported by the server, the
|
||
server MUST respond with a CARDDAV:supported-collation precondition
|
||
error response.
|
||
|
||
8.3.1. CARDDAV:supported-collation-set Property
|
||
|
||
Name: supported-collation-set
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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 (#PCDATA)>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 22]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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>
|
||
|
||
8.4. Partial Retrieval
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
8.5. Non-Standard Properties and Parameters
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
8.6. CARDDAV:addressbook-query Report
|
||
|
||
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
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 23]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Support for the CARDDAV:addressbook-query REPORT is REQUIRED.
|
||
|
||
Marshalling:
|
||
|
||
The request body MUST be a CARDDAV:addressbook-query XML element
|
||
as defined in Section 10.3.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 24]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
(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.
|
||
|
||
<!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.
|
||
|
||
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.
|
||
|
||
8.6.1. Limiting Results
|
||
|
||
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.
|
||
|
||
8.6.2. Truncation of Results
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 25]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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).
|
||
|
||
8.6.3. Example: Partial Retrieval of vCards Matching NICKNAME
|
||
|
||
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.
|
||
|
||
>> Request <<
|
||
|
||
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>
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 26]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
>> 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
|
||
|
||
<?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
|
||
|
||
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.
|
||
|
||
>> Request <<
|
||
|
||
REPORT /home/bernard/addressbook/ HTTP/1.1
|
||
Host: addressbook.example.com
|
||
Depth: 1
|
||
Content-Type: text/xml; charset="utf-8"
|
||
Content-Length: xxxx
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 27]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
<?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 <<
|
||
|
||
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
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 28]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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>
|
||
|
||
8.6.5. Example: Truncated Results
|
||
|
||
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.
|
||
|
||
>> Request <<
|
||
|
||
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">
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 29]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
<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 <<
|
||
|
||
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>
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 30]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
<D:status>HTTP/1.1 200 OK</D:status>
|
||
</D:propstat>
|
||
</D:response>
|
||
</D:multistatus>
|
||
|
||
8.7. CARDDAV:addressbook-multiget Report
|
||
|
||
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.
|
||
|
||
Support for the addressbook-multiget REPORT is REQUIRED.
|
||
|
||
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.
|
||
|
||
The request MUST include a Depth: 0 header; however, the actual
|
||
scope of the REPORT is determined as described above.
|
||
|
||
The response body for a successful request MUST be a
|
||
DAV:multistatus XML element.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 31]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
Postconditions:
|
||
|
||
None.
|
||
|
||
8.7.1. Example: CARDDAV:addressbook-multiget Report
|
||
|
||
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.
|
||
|
||
>> Request <<
|
||
|
||
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>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 32]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
>> 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
|
||
|
||
<?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>
|
||
|
||
8.7.2. Example: CARDDAV:addressbook-multiget Report
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 33]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
>> Request <<
|
||
|
||
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>
|
||
|
||
>> 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
|
||
|
||
<?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>
|
||
|
||
9. Client Guidelines
|
||
|
||
9.1. Restrict the Properties Returned
|
||
|
||
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.
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 34]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
9.2. Avoiding Lost Updates
|
||
|
||
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).
|
||
|
||
9.3. Client Configuration
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
9.4. Finding Other Users' Address Books
|
||
|
||
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:
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 35]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
<?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.
|
||
|
||
10. XML Element Definitions
|
||
|
||
10.1. CARDDAV:addressbook XML Element
|
||
|
||
Name: addressbook
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Specifies the resource type of an address book collection.
|
||
|
||
Description: See Section 5.2.
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT addressbook EMPTY>
|
||
|
||
10.2. CARDDAV:supported-collation XML Element
|
||
|
||
Name: supported-collation
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Identifies a single collation via its collation identifier
|
||
as defined by [RFC4790].
|
||
|
||
Description: The CARDDAV:supported-collation contains the text of a
|
||
collation identifier as described in Section 8.3.1.
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 36]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT supported-collation (#PCDATA)>
|
||
<!-- PCDATA value: collation identifier -->
|
||
|
||
10.3. CARDDAV:addressbook-query XML Element
|
||
|
||
Name: addressbook-query
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Defines a report for querying address book data
|
||
|
||
Description: See Section 8.6.
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT addressbook-query ((DAV:allprop |
|
||
DAV:propname |
|
||
DAV:prop)?, filter, limit?)>
|
||
|
||
10.4. CARDDAV:address-data XML Element
|
||
|
||
Name: address-data
|
||
|
||
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
|
||
|
||
2. The content of an address object resource in a response to an
|
||
address book REPORT request.
|
||
|
||
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.
|
||
|
||
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
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 37]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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".
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!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;
|
||
|
||
<!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.
|
||
|
||
<!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.
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 38]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
10.4.1. CARDDAV:allprop XML Element
|
||
|
||
Name: allprop
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Specifies that all vCard properties shall be returned.
|
||
|
||
Description: This element can be used when the client wants all
|
||
vCard properties of components returned by a report.
|
||
|
||
Definition:
|
||
|
||
<!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.
|
||
|
||
10.4.2. CARDDAV:prop XML Element
|
||
|
||
Name: prop
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Defines which vCard properties to return in the response.
|
||
|
||
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.
|
||
|
||
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".
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 39]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT prop EMPTY>
|
||
|
||
<!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.
|
||
|
||
10.5. CARDDAV:filter XML Element
|
||
|
||
Name: filter
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!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 -->
|
||
|
||
10.5.1. CARDDAV:prop-filter XML Element
|
||
|
||
Name: prop-filter
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Limits the search to specific vCard properties.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 40]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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:
|
||
|
||
* 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.
|
||
|
||
or:
|
||
|
||
* A vCard property of the type specified by the "name" attribute
|
||
does not exist, and the CARDDAV:is-not-defined element is
|
||
specified.
|
||
|
||
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".
|
||
|
||
Definition:
|
||
|
||
<!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 -->
|
||
|
||
10.5.2. CARDDAV:param-filter XML Element
|
||
|
||
Name: param-filter
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Limits the search to specific parameter values.
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 41]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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:
|
||
|
||
* 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.
|
||
|
||
or:
|
||
|
||
* A parameter of the type specified by the "name" attribute does
|
||
not exist, and the CARDDAV:is-not-defined element is specified.
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT param-filter (is-not-defined | text-match)?>
|
||
|
||
<!ATTLIST param-filter name CDATA #REQUIRED>
|
||
<!-- name value: a property parameter name (e.g., "TYPE") -->
|
||
|
||
10.5.3. CARDDAV:is-not-defined XML Element
|
||
|
||
Name: is-not-defined
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Specifies that a match should occur if the enclosing vCard
|
||
property or parameter does not exist.
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT is-not-defined EMPTY>
|
||
|
||
10.5.4. CARDDAV:text-match XML Element
|
||
|
||
Name: text-match
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Specifies a substring match on a vCard property or
|
||
parameter value.
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 42]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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 -->
|
||
|
||
<!ATTLIST text-match
|
||
collation CDATA "i;unicode-casemap"
|
||
negate-condition (yes | no) "no"
|
||
match-type (equals|contains|starts-with|ends-with) "contains">
|
||
|
||
10.6. CARDDAV:limit XML Element
|
||
|
||
Name: limit
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: Specifies different types of limits that can be applied to
|
||
the results returned by the server.
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 43]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT limit (nresults)>
|
||
|
||
10.6.1. CARDDAV:nresults XML Element
|
||
|
||
Name: nresults
|
||
|
||
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.
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT nresults (#PCDATA)>
|
||
<!-- nresults value: unsigned integer, must be digits -->
|
||
|
||
10.7. CARDDAV:addressbook-multiget XML Element
|
||
|
||
Name: addressbook-multiget
|
||
|
||
Namespace: urn:ietf:params:xml:ns:carddav
|
||
|
||
Purpose: CardDAV report used to retrieve specific address objects
|
||
via their URIs.
|
||
|
||
Description: See Section 8.7.
|
||
|
||
Definition:
|
||
|
||
<!ELEMENT addressbook-multiget ((DAV:allprop |
|
||
DAV:propname |
|
||
DAV:prop)?,
|
||
DAV:href+)>
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 44]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
11. Service Discovery via SRV Records
|
||
|
||
[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.
|
||
|
||
This specification adds two service types for use with SRV records:
|
||
|
||
carddav: Identifies a CardDAV server that uses HTTP without TLS
|
||
[RFC2818].
|
||
|
||
carddavs: Identifies a CardDAV server that uses HTTP with TLS
|
||
[RFC2818].
|
||
|
||
Example: non-TLS service record
|
||
|
||
_carddav._tcp SRV 0 1 80 addressbook.example.com.
|
||
|
||
Example: TLS service
|
||
|
||
_carddavs._tcp SRV 0 1 443 addressbook.example.com.
|
||
|
||
12. Internationalization Considerations
|
||
|
||
CardDAV allows internationalized strings to be stored and retrieved
|
||
for the description of address book collections (see Section 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).
|
||
|
||
13. Security Considerations
|
||
|
||
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.
|
||
|
||
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"
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 45]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
(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.
|
||
|
||
14. IANA Consideration
|
||
|
||
This document uses a URN to describe a new XML namespace conforming
|
||
to the registry mechanism described in [RFC3688].
|
||
|
||
14.1. Namespace Registration
|
||
|
||
Registration request for the carddav namespace:
|
||
|
||
URI: urn:ietf:params:xml:ns:carddav
|
||
|
||
Registrant Contact: The IESG <iesg@ietf.org>
|
||
|
||
XML: None - not applicable for namespace registrations.
|
||
|
||
15. Acknowledgments
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 46]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
16. References
|
||
|
||
16.1. Normative References
|
||
|
||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
|
||
Requirement Levels", BCP 14, RFC 2119, March 1997.
|
||
|
||
[RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
|
||
RFC 2426, September 1998.
|
||
|
||
[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.
|
||
|
||
[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.
|
||
|
||
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
|
||
specifying the location of services (DNS SRV)", RFC 2782,
|
||
February 2000.
|
||
|
||
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
|
||
|
||
[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.
|
||
|
||
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
|
||
January 2004.
|
||
|
||
[RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
|
||
Distributed Authoring and Versioning (WebDAV)
|
||
Access Control Protocol", RFC 3744, May 2004.
|
||
|
||
[RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
|
||
Application Protocol Collation Registry", RFC 4790,
|
||
March 2007.
|
||
|
||
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
|
||
Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
|
||
|
||
[RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation
|
||
Algorithm", RFC 5051, October 2007.
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 47]
|
||
|
||
RFC 6352 CardDAV August 2011
|
||
|
||
|
||
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
|
||
(TLS) Protocol Version 1.2", RFC 5246, August 2008.
|
||
|
||
[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.
|
||
|
||
[RFC5397] Sanchez, W. and C. Daboo, "WebDAV Current Principal
|
||
Extension", RFC 5397, December 2008.
|
||
|
||
[RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring
|
||
and Versioning (WebDAV)", RFC 5689, September 2009.
|
||
|
||
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
|
||
August 2011.
|
||
|
||
[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>.
|
||
|
||
16.2. Informative References
|
||
|
||
[IMSP] Myers, J., "IMSP - Internet Message Support Protocol",
|
||
Work in Progress, June 1995.
|
||
|
||
[RFC2244] Newman, C. and J. Myers, "ACAP -- Application
|
||
Configuration Access Protocol", RFC 2244, November 1997.
|
||
|
||
[RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol
|
||
(LDAP): Technical Specification Road Map", RFC 4510,
|
||
June 2006.
|
||
|
||
Author's Address
|
||
|
||
Cyrus Daboo
|
||
Apple, Inc.
|
||
1 Infinite Loop
|
||
Cupertino, CA 95014
|
||
USA
|
||
|
||
EMail: cyrus@daboo.name
|
||
URI: http://www.apple.com/
|
||
|
||
|
||
|
||
|
||
|
||
Daboo Standards Track [Page 48]
|
||
|