Peler

: / opt / cpanel-ccs / doc / Extensions /
Filename : caldav-pubsubdiscovery.xml
back
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
<!ENTITY rfc4918 PUBLIC '' 'bibxml/reference.RFC.4918.xml'>
]>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc strict="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private="Calendar Server Extension"?>
<rfc ipr="none" docName='caldav-pubsubdiscovery-02'>
    <front>
        <title abbrev="CalDAV PubSub Discovery">Discovery of CalDAV Push-Notification Settings</title>
        <author initials="M." surname="Sagen" fullname="Morgen Sagen">
            <organization abbrev="Apple">
                Apple Inc.
            </organization>
            <address>
                <postal>
                    <street>1 Infinite Loop</street>
                    <city>Cupertino</city>
                    <region>CA</region>
                    <code>95014</code>
                    <country>USA</country>
                </postal>
                <email>sagen@apple.com</email>
                <uri>http://www.apple.com/</uri>
            </address>
        </author>
        <date/>
        <abstract>
            <t>
                This specification defines new WebDAV properties that allow clients to discover and subscribe to change notifications, eliminating the need for polling.
            </t>
        </abstract>
    </front>
    <middle>
        <section title='Introduction'>
            <t>
            The <xref target="RFC4791">CalDAV</xref> 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.
            </t>
            <t>
            The <xref target="APPLE.APNS">Apple Push Notification Service</xref> (APNs for short)
			is a service for propagating information to iOS and OS X devices in
            an efficient manner.
			</t>
			<t>
			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 queries the CalDAV/CardDAV server to see which resources have changed.
            </t>
        </section>
        <section title='Conventions Used in This Document'>
            <t>
                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 <xref target='RFC2119' />.
            </t>
            <t>
                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.
            </t>
            <t>
                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.
            </t>
        </section>

        <section title='New Properties'>
            <section title="Push Transports Property">
                <t>
<?rfc compact="no" ?>
                    <list style="hanging">
                        <t hangText="Name:">push-transports</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Advertises the list of push transports supported by the server.</t>
                        <t hangText="Protected:">This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
                        <t hangText="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.</t>
                        <t hangText="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.</t>
                        <t hangText="Definition:">
                            <figure>
                                <artwork><![CDATA[
<!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 -->

]]></artwork>

                            </figure>
                        </t>
                        <t hangText="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).
                            <figure>
                                <artwork><![CDATA[
<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>  ]]></artwork>
                            </figure>
                        </t>
					</list>
				</t>
			</section>

            <section title="Push Key Property">
                <t>
<?rfc compact="no" ?>
                    <list style="hanging">
                        <t hangText="Name:">pushkey</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Provides the push key to subscribe to in order to receive a notification whenever a resource within this collection has changed.</t>
                        <t hangText="Protected:">This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
                        <t hangText="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.</t>
                        <t hangText="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.</t>
                        <t hangText="Definition:">
                            <figure>
                                <artwork><![CDATA[
<!ELEMENT pushkey (CDATA) >
]]></artwork>
                            </figure>
                        </t>
                        <t hangText="Example:">
							This example indicates the push key for a collection is the UUID '6D6241DC-5981-4D87-9B71-672203E81ACB'.
                            <figure>
                                <artwork><![CDATA[
<pushkey xmlns='http://calendarserver.org/ns/'>6D6241DC-5981-4D87-9B71-672203E81ACB/</pushkey>
                   ]]></artwork>
                            </figure>
                        </t>
					</list>
				</t>
			</section>

        </section>
        <section title='Subscription Process'>
            <section title="Discovery">
                <t>
                    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.
                </t>
            </section>
            <section title="Subscription">
                <t>
                    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 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.
                </t>
            </section>
            <section title="Payload">
                <t>
                    The payload of each push notification will contain:
                    <list style="hanging">
                        <t>"key" - the push key of the collection</t>
                        <t>"dataChangedTimestamp" - the unix epoch time (in seconds) when the change that triggered this notification took place</t>
                        <t>"pushRequestSubmittedTimestamp" - the unix epoch time (in seconds) when the CalDAV/CardDAV server sent the notification to the APNs servers</t>
                    </list>
                </t>
            </section>

        </section>

    </middle>
    <back>
        <references title='Normative References'>
            &rfc2119;
            &rfc4791;
            &rfc4918;
    <reference anchor='APPLE.APNS' target=' https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html'>
      <front>
      <title>Apple Push Notification Service</title>
      <author>
          <organization>Apple Inc.</organization>
      </author>
      <date month='October' day='16' year='2014' />
      </front>

      <seriesInfo name='Apple Inc' value='iOS Developer Library'/>
      <format type='HTML' target='https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html' />
    </reference>
        </references>
    </back>
</rfc>