Introduction

Addressbook.app is among the first CardDAV clients, and it's shipped with OS/X since version 10.6 (Snow Leopard). There are many bugs in the 10.6 client though, most of which have been solved in 10.7.

Implementation notes

10.6

The CardDAV server must absolutely run on the root of the domain. Addressbook makes a lot of assumptions based around this, and running the CardDAV server anywhere else will simply break.

In some cases it was enough (for me) to simply specify the domainname of the CalDAV server, but I've also had cases where:

• I needed to specify a full principal url (e.g.: http://example.org/principals/username/)
• I needed to also include a HTTP port (e.g.: http://example.org:80/principals/username/)

Even after trying this, it seems to randomly forget the correct TCP port and default back to 8008 (which is the standard port for Darwin Calendar Server).

This client cannot list addressbooks, nor can it create new addressbooks. So to make this client work correctly, an addressbook must already be created for a user.

This client does not support the usage of the @-character in usernames. This means that it's not possible with this client to use email addresses as usernames. The actual underlying problem is actually that @ does not get urlencoded, and it will treat the part before the @ as the username, and prefix the hostname for HTTP requests with the domainname of the email address.

A workaround is to replace @ with an underscore() instead, but this is really only a good solution if you use HTTP Basic authentication, as with Digest using a different username will also alter the hash. It's best to simply not use email addresses for usernames if you plan to support (10.6) Addressbook.app.

This client can only use 1 addressbook. It will most likely use the first addressbook in a users' collection of addressbooks.

This client requires impementation of the proprietary '{http://calendarserver.org/ns/}getctag' property. Without it, it will simply not request the vcard.

10.7

No specific notes for OS/X 10.7 yet, but so far it appears that all bugs from 10.6 have been fixed, which is exciting.

Directory support

AddressBook.app has support for a global read-only directory. Addressbook.app does not allow simply browsing through the directory, it's used for searching only (using the addressbook-query REPORT).

SabreDAV does have (very minimal) support for CardDAVDirectory, by providing a simple interface Sabre_CardDAV_IDirectory.

= 'Me' card

AddressBook.app has the ability to mark a specific vcard as the users' own vcard. There is no native integration for this in SabreDAV.

The 'Me card' is simply a property on the users' addressbook-collection-set. In SabreDAV this would mean (in a default tree layout) that the property is set on /addressbooks/username.

This is a bit odd, considering that most properties like this are often stored on the principal url.

The request to set a "Me" card looks as follows:

PROPPATCH /addressbooks/evert/ HTTP/1.1
Host: ...
User-Agent: AddressBook/6.1 (1083) CardDAVPlugin/200 CFNetwork/520.3.2 Mac_OS_X/10.7.3 (11D50)
Content-Length: 280
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Content-Type: text/xml
Pragma: no-cache
Authorization: Digest ...
Connection: keep-alive

<?xml version="1.0" encoding="UTF-8"?>
<A:propertyupdate xmlns:A="DAV:"><A:set><A:prop><C:me-card xmlns:C="http://calendarserver.org/ns/"><A:href>/addressbooks/evert/book1/E7213AAA-7206-4B97-926A-CDFECBD91C26-ABSPlugin.vcf</A:href></C:me-card></A:prop></A:set></A:propertyupdate>

I've noticed that if the Me card is not supported, Addressbook.app may crash.

Protocol details

• Even though the client requests the current-user-principal and principal-URL properties, it doesn't seem to actually handle them correctly.
• addressbook.app supports the so-called 'ctag', and in general it's pretty good in caching and leveraging etags and ctags.
• At one point addressbook tried a custom report to find 'shared addressbooks'. The report-request body was an xml document in the http://calendarserver.org/ns/ namespace. I haven't been able to reproduce it since, but I think it's safe to assume there's some kind of addressbook-sharing mechanism built in.