ProPeler
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
opt
/
cpanel-ccs
/
doc
/
Extensions
/
Filename :
caldav-pubsubdiscovery.txt
back
Copy
M. Sagen Apple October 30, 2014 Discovery of CalDAV Push-Notification Settings caldav-pubsubdiscovery-02 Abstract This specification defines new WebDAV properties that allow clients to discover and subscribe to change notifications, eliminating the need for polling. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1 2. Conventions Used in This Document . . . . . . . . . . . . . . 2 3. New Properties . . . . . . . . . . . . . . . . . . . . . . . 2 3.1. Push Transports Property . . . . . . . . . . . . . . . . 2 3.2. Push Key Property . . . . . . . . . . . . . . . . . . . . 3 4. Subscription Process . . . . . . . . . . . . . . . . . . . . 4 4.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 4 4.2. Subscription . . . . . . . . . . . . . . . . . . . . . . 4 4.3. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 5 5. Normative References . . . . . . . . . . . . . . . . . . . . 5 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction The CalDAV [RFC4791] standard defines a way to access calendar data stored on a server. Clients typically poll the server for changes, which leads to unnecessary traffic and delays in propagating calendar updates. Having clients instead subscribe to calendar change notifications would allow near real time propagation of updates and potentially reduce the number of requests. The Apple Push Notification Service [APPLE.APNS] (APNs for short) is a service for propagating information to iOS and OS X devices in an efficient manner. A push-notification-capable CalDAV/CardDAV server advertises the capability via a DAV property ("push-transports") on calendar and addressbook home resources. Each calendar and addressbook collection resource has another DAV property ("pushkey") which is an opaque token a client can use to subscribe to change notifications for that collection. When the client receives such a notification, the client Sagen Expires May 3, 2015 [Page 1] CalDAV PubSub Discovery October 2014 queries the CalDAV/CardDAV server to see which resources have changed. 2. Conventions Used in This Document 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]. When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:caldav" are referenced in this document outside of the context of an XML fragment, the string "DAV:" and "CALDAV:" will be prefixed to the element type names respectively. The namespace "http://calendarserver.org/ns/" is used for XML elements defined in this specification. When XML element types in this namespace are referenced in this document outside of the context of an XML fragment, the string "CS:" will be prefixed to the element type names respectively. 3. New Properties 3.1. Push Transports Property Name: push-transports Namespace: http://calendarserver.org/ns/ Purpose: Advertises the list of push transports supported by the server. Protected: This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of [RFC4918]). COPY/MOVE behavior: This property value SHOULD be kept during a MOVE operation, but is normally re-initialized when a resource is created with a COPY. It should not be set in a COPY. Description: This property MUST be defined on a calendar or addressbook home collection and MUST NOT be defined on a calendar or addressbook collection. Its value is an XML element whose child elements each represent a supported push transport protocol. Definition: Sagen Expires May 3, 2015 [Page 2] CalDAV PubSub Discovery October 2014 <!ELEMENT push-transports (transport) > <!ELEMENT transport (subscription-url, apsbundleid, env, refresh-interval) > <!-- The transport element must have a 'type' attribute identifying the transport type. For Apple Push the attribute value should be 'APSD'. --> <!ELEMENT subscription-url (DAV:href) > <!-- The URL clients should send their subscription requests to. --> <!ELEMENT apsbundleid (CDATA) > <!-- The Apple Push "topic", which is extracted from the UID portion of the subject of the certificate acquired from Apple. The topic is currently the bundle identifier of the target app. --> <!ELEMENT env (CDATA) > <!-- "PRODUCTION" if the clients should talk to the production APNs servers or "SANDBOX" if the clients should talk to the sandbox APNs servers --> <!ELEMENT refresh-interval (CDATA) > <!-- An integer value indicating how often (in seconds) the client should refresh their subscriptions, since the server will remove subscriptions that are not refreshed within this time period --> Example: This example indicates the CalDAV/CardDAV server is using the production APNs service and clients should send their subscription requests to https://server.example.com:8443/apns at least every 172800 seconds (2 days). <push-transports xmlns='http://calendarserver.org/ns/'> <transport type='APSD'> <subscription-url> <href xmlns='DAV:'>https://server.example.com:8443/apns</href> </subscription-url> <apsbundleid>com.apple.calendar.XServer.934668ca-125e-4246-afee-8cf2df37aab8</apsbundleid> <env>PRODUCTION</env> <refresh-interval>172800</refresh-interval> </transport> </push-transports> 3.2. Push Key Property Name: pushkey Namespace: http://calendarserver.org/ns/ Purpose: Provides the push key to subscribe to in order to receive a notification whenever a resource within this collection has changed. Protected: This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of [RFC4918]). Sagen Expires May 3, 2015 [Page 3] CalDAV PubSub Discovery October 2014 COPY/MOVE behavior: This property value SHOULD be kept during a MOVE operation, but is normally re-initialized when a resource is created with a COPY. It should not be set in a COPY. Description: This property MUST be defined on calendar and addressbook home collections as well as calendar and addressbook collections. Its value is a server-generated string associated with a collection. The client must send a subscription request containing the "push key" string to subscribe to change notifications for the collection. The push key for a calendar or addressbook collection will normally be the same value as the containing home collection. However, there are circumstances (such as shared collections) where the push keys for collections are not the same as the containing home, and thus clients should subscribe to the push keys for the home collection and each contained collection. Definition: <!ELEMENT pushkey (CDATA) > Example: This example indicates the push key for a collection is the UUID '6D6241DC-5981-4D87-9B71-672203E81ACB'. <pushkey xmlns='http://calendarserver.org/ns/'>6D6241DC-5981-4D87-9B71-672203E81ACB/</pushkey> 4. Subscription Process 4.1. Discovery To subscribe to change notifications, the client must first fetch the "push-transports" property for the principal's calendar or addressbook home. The "transport" child element with type set to "APSD" identifies the APNs configuration. The "subscription-url" element identifies the URL clients will need to send subscription requests to. Next, for each home and collection the client is interested in receiving change notifications for, the client should fetch the "pushkey" property. Some collections' push keys will be the same as their parent collection, but not always. Each unique push key the client finds should be subscribed to at least every "refresh-interval" seconds. 4.2. Subscription As per the APNs documentation, the client must acquire a "device token" identifying the device to the APNs servers. Next, for each unique push key the client wants to subscribe to, the client must send an authenticated HTTP request including the device token and Sagen Expires May 3, 2015 [Page 4] CalDAV PubSub Discovery October 2014 push key values to the URL identified by subscription-url. The field names to use are "token" and "key", respectively. If the client uses GET, the token and key can be passed as query string parameters; if using POST they can be sent as form fields. The server will return an HTTP status code OK (200) if the subscription was successful, or BAD_REQUEST (400) with an explanation message in the response body otherwise. 4.3. Payload The payload of each push notification will contain: "key" - the push key of the collection "dataChangedTimestamp" - the unix epoch time (in seconds) when the change that triggered this notification took place "pushRequestSubmittedTimestamp" - the unix epoch time (in seconds) when the CalDAV/CardDAV server sent the notification to the APNs servers 5. Normative References [APPLE.APNS] Apple Inc., "Apple Push Notification Service", Apple Inc iOS Developer Library, October 2014, < https://developer.a pple.com/library/ios/documentation/NetworkingInternet/Conc eptual/RemoteNotificationsPG/Chapters/ ApplePushService.html>. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, March 2007. [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007. Author's Address Sagen Expires May 3, 2015 [Page 5] CalDAV PubSub Discovery October 2014 Morgen Sagen Apple Inc. 1 Infinite Loop Cupertino, CA 95014 USA Email: sagen@apple.com URI: http://www.apple.com/ Sagen Expires May 3, 2015 [Page 6]