diff options
| author | RedMatrix <info@friendica.com> | 2014-06-29 10:16:51 +1000 |
|---|---|---|
| committer | RedMatrix <info@friendica.com> | 2014-06-29 10:16:51 +1000 |
| commit | e228c2ed32593cdbf35992d60e7408dd2c0e33e0 (patch) | |
| tree | b6ff696d625712ad4ba8d71223505858bdbf1e0e /vendor/sabre/dav/docs/rfc6352.txt | |
| parent | f29f8a1b40ba68db66c22bbb824371296c86ac8c (diff) | |
| parent | 03b31d113ea316c8384a4cbf3d27ca22bb528eac (diff) | |
| download | volse-hubzilla-e228c2ed32593cdbf35992d60e7408dd2c0e33e0.tar.gz volse-hubzilla-e228c2ed32593cdbf35992d60e7408dd2c0e33e0.tar.bz2 volse-hubzilla-e228c2ed32593cdbf35992d60e7408dd2c0e33e0.zip | |
Merge pull request #513 from dawnbreak/master
Some documentation for include/reddav.php and a new tpl-file.
Diffstat (limited to 'vendor/sabre/dav/docs/rfc6352.txt')
| -rw-r--r-- | vendor/sabre/dav/docs/rfc6352.txt | 2691 |
1 files changed, 0 insertions, 2691 deletions
diff --git a/vendor/sabre/dav/docs/rfc6352.txt b/vendor/sabre/dav/docs/rfc6352.txt deleted file mode 100644 index cb03747b4..000000000 --- a/vendor/sabre/dav/docs/rfc6352.txt +++ /dev/null @@ -1,2691 +0,0 @@ - - - - - - -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] - |