The Apple iCal client

Connecting with iCal

• Go to preferences in the iCal menu
• Go to the Accounts tab
• Press the + button to add a new account
• Select 'CalDAV server' for account type
• Enter your username, password
• For server address, enter the full SabreDAV url, but add /principals/hank/. For example, for the user 'hank' you will want to use http://www.example.org/sabredav/calendarserver.php/principals/hank/. Do NOT forget the trailing slash

Creating new calendars is supported, but iCal will throw an error (which you can ignore safely)

Debugging

To enable the debug menu within ical, run the following on the command line (and restart):

defaults write com.apple.iCal IncludeDebugMenu 1

To enable logging:

defaults write com.apple.iCal LogHTTPActivity -boolean TRUE

Logging goes to 'Console.app'

Implementor notes

User agent

iCal sends the following user agent

• DAVKit/3.0.6 (661); CalendarStore/3.0.8 (860); iCal/3.0.8 (1287); Mac OS X/10.5.8 (9L31a)
• DAVKit/4.0.1 (730); CalendarStore/4.0.1 (973); iCal/4.0.1 (1374); Mac OS X/10.6.2 (10C540)

Properties

When setting up iCal the full url to the principal must be supplied. ICal 3.0 then requests the following properties:

<?xml version="1.0" encoding="utf-8"?>
<x0:propfind xmlns:x2="http://calendarserver.org/ns/" xmlns:x1="urn:ietf:params:xml:ns:caldav" xmlns:x0="DAV:">
 <x0:prop>
  <x1:calendar-home-set/>
  <x1:calendar-user-address-set/>
  <x1:schedule-inbox-URL/>
  <x1:schedule-outbox-URL/>
  <x2:dropbox-home-URL/>
  <x2:notifications-URL/>
  <x0:displayname/>
 </x0:prop>
</x0:propfind>

iCal 4 requests the following:

• DAV: principal-collection-set
• CalDAV: calendar-home-set
• CalDAV: calendar-user-address-set
• CalDAV: schedule-inbox-URL
• CalDAV: schedule-outbox-URL
• CalendarServer: dropbox-home-URL
• CalendarServer: xmpp-uri
• DAV: displayname
• DAV: principal-URL
• DAV: supported-report-set

On the calendar-home-set (collection with calendars) iCal 3.0 requests the following:

<?xml version="1.0" encoding="utf-8"?>
<x0:propfind xmlns:x1="http://calendarserver.org/ns/" xmlns:x0="DAV:" xmlns:x3="http://apple.com/ns/ical/" xmlns:x2="urn:ietf:params:xml:ns:caldav">
 <x0:prop>
  <x1:getctag/>
  <x0:displayname/>
  <x2:calendar-description/>
  <x3:calendar-color/>
  <x3:calendar-order/>
  <x0:resourcetype/>
  <x2:calendar-free-busy-set/>
 </x0:prop>
</x0:propfind>

iCal 4 requests:

<x0:propfind xmlns:x0="DAV:" xmlns:x3="http://apple.com/ns/ical/" 
  xmlns:x1="http://calendarserver.org/ns/" xmlns:x2="urn:ietf:params:xml:ns:caldav"> 
	<x0:prop> 
		<x1:xmpp-server /> 
		<x1:xmpp-uri /> 
		<x1:getctag /> 
		<x0:displayname /> 
		<x2:calendar-description /> 
		<x3:calendar-color /> 
		<x3:calendar-order /> 
		<x2:supported-calendar-component-set /> 
		<x0:resourcetype /> 
		<x2:calendar-free-busy-set /> 
		<x2:schedule-calendar-transp /> 
		<x2:schedule-default-calendar-URL /> 
		<x0:quota-available-bytes /> 
		<x0:quota-used-bytes /> 
		<x2:calendar-timezone /> 
		<x0:current-user-privilege-set /> 
	</x0:prop> 
</x0:propfind>

Changing todo/event's server-side

Overall iCal seems to respond well to Tasks and Events to be changed by the server, even if we immediately discard the original .ics file right after a PUT. (it must be noted that this behaviour is not recommended, but I needed it for a project).

There's one major exception. You can not changed events to todo's, and vice versa. This will leave iCal confused and causes it to ignore future updates from any calendarobject in the calendar.

If you must change an EVENT into a TODO object, make sure it gets a new uri.

Bugs

Assuming scheduling support

iCal appears to assume that any CalDAV server also supports from CalDAV-scheduling features out of the box. iCal will use this to let the server send emails, for things like an event invitation.

If this is not supported, no emails for these types of actions will be sent. This can be rather unexpected for users, as these expected emails just won't arrive.

Since version 1.6 SabreDAV has a workaround for this. Read IMipHandler for more details.

Trailing slash (3.0 & 4.0)

It was reported on several wiki's iCal needs a trailing slash for the url to connect to (the principal url). This is not enough however, the {DAV:}href element in the {DAV:}response element MUST also have this trailing url.

Without it errors such as the following can come up:

• "the server has not specified a calendar home ... "
• "here was an unexpected error with the request (domain CalDAVErrorDomain / error 5 / description 'The server has not specified a calendar home for the account at .."

Overwriting ACL (3.0 & 4.0)

When creating new calendars using MKCALENDAR, iCal will attempt to add permissions using the ACL method.

By doing this, it will overwrite any existing ACL entries. By doing this it effectively locks itself out of the calendar it just created.

ACL request from iCAL:

<x0:acl xmlns:x1="urn:ietf:params:xml:ns:caldav" xmlns:x0="DAV:">
  <x0:ace>
      <x0:principal>
          <x0:authenticated />
      </x0:principal>
      <x0:grant>
          <x0:privilege>
               <x1:read-free-busy />
          </x0:privilege>
      </x0:grant>
  </x0:ace>
</x0:acl>

SabreDAV ignores ACL requests for now, so this is an effective workaround. When ACL support is added to SabreDAV this might become a problem again.

Unsupported error message (3.0 & 4.0)

Note: This doesn't appear to be an issue anymore, for SabreDAV at least

For various operations (such as deleting a calendar) iCal will report that 'the server does not support this type of request', even though the operation succeeded.

This is because iCal is making a request is making a request to the root of the server, containing the following:

PROPFIND / HTTP/1.1
User-Agent: DAVKit/4.0.1 (730); CalendarStore/4.0.1 (973); iCal/4.0.1 (1374); Mac OS X/10.6.2 (10C540)
Depth: 0
Content-Type: text/xml
Content-Length: 178
Connection: keep-alive
Host: localhost:80

<?xml version="1.0" encoding="utf-8"?>
<x0:propfind xmlns:x1="urn:ietf:params:xml:ns:caldav" xmlns:x0="DAV:">
 <x0:prop>
  <x1:calendar-free-busy-set/>
 </x0:prop>
</x0:propfind>

If your root is not WebDAV aware, it will likely throw an error. Apache for instance will return '405 Method not supported'. The calendar-free-busy-set is a property from a CalDAV scheduling draft. Why iCal is making this request on the root is unknown.

iCal depends on a DAV: header to be set in all responses

Traditionally the DAV: header is only needed in the OPTIONS request. If calendar-proxy support is required, this header must also be set in other responses. In particular, iCal seems to pick up on it if it's set in a PROPFIND response.

Since 1.5 we always send along the DAV: header for PROPFIND responses.