< draft-ietf-sip-xcapevent-07.txt   draft-ietf-sip-xcapevent-08.txt >
SIP J. Urpalainen SIP J. Urpalainen
Internet-Draft Nokia Internet-Draft Nokia
Intended status: Standards Track D. Willis, Ed. Intended status: Standards Track D. Willis, Ed.
Expires: November 28, 2009 Softarmor Systems LLC Expires: January 10, 2010 Softarmor Systems LLC
May 27, 2009 July 9, 2009
An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) An Extensible Markup Language (XML) Configuration Access Protocol (XCAP)
Diff Event Package Diff Event Package
draft-ietf-sip-xcapevent-07 draft-ietf-sip-xcapevent-08
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. This document may contain material provisions of BCP 78 and BCP 79. This document may contain material
from IETF Documents or IETF Contributions published or made publicly from IETF Documents or IETF Contributions published or made publicly
available before November 10, 2008. The person(s) controlling the available before November 10, 2008. The person(s) controlling the
copyright in some of this material may not have granted the IETF copyright in some of this material may not have granted the IETF
Trust the right to allow modifications of such material outside the Trust the right to allow modifications of such material outside the
IETF Standards Process. Without obtaining an adequate license from IETF Standards Process. Without obtaining an adequate license from
skipping to change at page 1, line 44 skipping to change at page 1, line 44
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on November 28, 2009. This Internet-Draft will expire on January 10, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info). publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 34 skipping to change at page 2, line 34
3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. XCAP-Diff Event Package . . . . . . . . . . . . . . . . . . . 4 4. XCAP-Diff Event Package . . . . . . . . . . . . . . . . . . . 4
4.1. Overview of Operation With Basic Requirements . . . . . . 4 4.1. Overview of Operation With Basic Requirements . . . . . . 4
4.2. Event Package Name . . . . . . . . . . . . . . . . . . . . 5 4.2. Event Package Name . . . . . . . . . . . . . . . . . . . . 5
4.3. 'diff-processing' Event Package Parameter . . . . . . . . 5 4.3. 'diff-processing' Event Package Parameter . . . . . . . . 5
4.4. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 6 4.4. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 6
4.5. Subscription Duration . . . . . . . . . . . . . . . . . . 8 4.5. Subscription Duration . . . . . . . . . . . . . . . . . . 8
4.6. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 8 4.6. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 8
4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 8 4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 8
4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 11 4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 11
4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 12 4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 13
4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 13 4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 13
4.11. State Agents . . . . . . . . . . . . . . . . . . . . . . . 13 4.11. State Agents . . . . . . . . . . . . . . . . . . . . . . . 13
5. An Initial Example NOTIFY document . . . . . . . . . . . . . . 13 5. An Initial Example NOTIFY document . . . . . . . . . . . . . . 13
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.1. Normative References . . . . . . . . . . . . . . . . . . . 16 9.1. Normative References . . . . . . . . . . . . . . . . . . . 16
9.2. Informative References . . . . . . . . . . . . . . . . . . 17 9.2. Informative References . . . . . . . . . . . . . . . . . . 17
Appendix A. Informative Examples . . . . . . . . . . . . . . . . 17 Appendix A. Informative Examples . . . . . . . . . . . . . . . . 17
A.1. Initial documents on an XCAP server . . . . . . . . . . . 17 A.1. Initial documents on an XCAP server . . . . . . . . . . . 17
A.2. An Initial Subscription . . . . . . . . . . . . . . . . . 18 A.2. An Initial Subscription . . . . . . . . . . . . . . . . . 18
A.3. A Document Addition Into a Collection . . . . . . . . . . 19 A.3. A Document Addition Into a Collection . . . . . . . . . . 19
A.4. A Series of XCAP Component Modifications . . . . . . . . . 20 A.4. A Series of XCAP Component Modifications . . . . . . . . . 20
A.5. An XCAP Component Subscription . . . . . . . . . . . . . . 23 A.5. An XCAP Component Subscription . . . . . . . . . . . . . . 24
A.6. A Conditional Subscription . . . . . . . . . . . . . . . . 26 A.6. A Conditional Subscription . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29
1. Introduction 1. Introduction
The SIP Events framework [RFC3265] describes subscription and The SIP Events framework [RFC3265] describes subscription and
notification conventions for the Session Initiation Protocol (SIP) notification conventions for the Session Initiation Protocol (SIP)
[RFC3261]. The Extensible Markup Language (XML) [RFC3261]. The Extensible Markup Language (XML)
[W3C.REC-xml-20060816] Configuration Access Protocol (XCAP) [RFC4825] [W3C.REC-xml-20060816] Configuration Access Protocol (XCAP) [RFC4825]
allows a client to read, write and modify XML-formatted application allows a client to read, write and modify XML-formatted application
usage data stored on an XCAP server. usage data stored on an XCAP server.
skipping to change at page 3, line 31 skipping to change at page 3, line 31
whenever the XML document changes. whenever the XML document changes.
There are three basic features that this event package enables: There are three basic features that this event package enables:
First, a client can subscribe to a list of XCAP documents' URLs in a First, a client can subscribe to a list of XCAP documents' URLs in a
collection located on an XCAP server. This allows a subscriber to collection located on an XCAP server. This allows a subscriber to
compare server resources with its local resources using the URLs and compare server resources with its local resources using the URLs and
the strong entity tag (ETag) values of XCAP documents, which are the strong entity tag (ETag) values of XCAP documents, which are
shown in the XCAP Diff format, and to synchronize them. shown in the XCAP Diff format, and to synchronize them.
Second, this event package can signal a change in those resources in Second, this event package can signal a change in those documents in
one of three ways. The first mode only indicates the event type and one of three ways. The first mode only indicates the event type and
does not include document contents, so the subscriber uses HTTP does not include document contents, so the subscriber uses HTTP
[RFC2616] to retrieve the updated document. The second mode includes [RFC2616] to retrieve the updated document. The second mode includes
document content or changes in notification messages, using the XML- document content changes in notification messages, using the XML-
Patch-Ops [RFC5261] format with minimal notification size. The third Patch-Ops [RFC5261] format with minimal notification size. The third
mode also includes document content or changes in notification mode also includes document content changes in notification messages
messages, but is more verbose, and shows the full HTTP version- with the same XML-Patch-Ops format, but is more verbose, and shows
history. the full HTTP version-history.
Third, the client can subscribe to changes in specific XML element or Third, the client can subscribe to specific XML elements or
attribute contents (XCAP components) and receive element or attribute attributes (XCAP components) showing their existing contents in the
contents in the resulting XCAP Diff format notification messages. If resulting XCAP Diff format notification messages. If the requested
the requested component does not exist but is later created, the component does not exist but is later created, the notifier sends a
notifier sends a notification with the component's content. The notification with the component's content. The notifier also sends
notifier also sends notifications when the subscribed XCAP components notifications when the subscribed XCAP components are removed, for
are removed, for example after a successful HTTP DELETE request. example after a successful HTTP DELETE request.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119, BCP 14 document are to be interpreted as described in RFC 2119, BCP 14
[RFC2119] and indicate requirement levels for compliant [RFC2119] and indicate requirement levels for compliant
implementations. implementations.
3. Definitions 3. Definitions
The following terms are used in this document: The following terms are used in this document:
XCAP Component: An XML element or an attribute, which can be XCAP Component: An XML element or an attribute, which can be
updated, removed, or retrieved with XCAP. updated, removed, or retrieved with XCAP.
Aggregating: An XCAP client can update only a single XCAP Component Aggregating: An XCAP client can update only a single XCAP Component
at a time using HTTP. However, a notifier may be able to at a time using HTTP. However, a notifier may be able to
aggregate a series of these modifications into a single aggregate a series of these modifications into a single
notification using XML-Patch- Ops semantics encoded in the XCAP- notification using XML-Patch-Ops semantics encoded in the XCAP-
Diff format. Diff format.
This document reuses terminology mostly defined in XCAP [RFC4825] and This document reuses terminology mostly defined in XCAP [RFC4825] and
some in WebDAV [RFC4918]. some in WebDAV [RFC4918].
4. XCAP-Diff Event Package 4. XCAP-Diff Event Package
4.1. Overview of Operation With Basic Requirements 4.1. Overview of Operation With Basic Requirements
To receive "xcap-diff" event package features, the subscriber To receive "xcap-diff" event package features, the subscriber
skipping to change at page 4, line 45 skipping to change at page 4, line 45
selection includes all documents in that collection and recursively selection includes all documents in that collection and recursively
all documents in sub-collections. The URL of an XCAP component all documents in sub-collections. The URL of an XCAP component
consists of the document URL with the XCAP Node Selector added. consists of the document URL with the XCAP Node Selector added.
Although the XCAP Node Selector allows requesting all in-scope Although the XCAP Node Selector allows requesting all in-scope
namespaces of an element, the client MUST NOT subscribe to namespaces of an element, the client MUST NOT subscribe to
namespaces. namespaces.
The notifier MUST support XCAP component subscriptions. The notifier The notifier MUST support XCAP component subscriptions. The notifier
sends the first notification in response to the subscription, and sends the first notification in response to the subscription, and
this first notification MUST contain the URLs of the documents and this first notification MUST contain the URLs of the documents and
XCAP components that are part of the subscription. The first XCAP component contents that are part of the subscription. The
notification SHOULD contain the contents of subscribed XCAP documents subsequent notifications MAY contain patches to these documents. The
and components. The subsequent notifications MAY contain patches to subscriber can specify how the notifier will signal the changes of
these documents. The subscriber can specify how the notifier will documents by using the 'diff-processing' event package parameter,
signal the changes of documents by using the 'diff-processing' event covered in the Section 4.3. Note that the existence of the "diff-
package parameter, covered in the section Section 4.3 processing" parameter or its value has no influence on XCAP component
subscriptions.
4.2. Event Package Name 4.2. Event Package Name
The name of this event package is "xcap-diff". As specified in The name of this event package is "xcap-diff". As specified in
[RFC3265], this value appears in the Event header field present in [RFC3265], this value appears in the Event header field present in
SUBSCRIBE and NOTIFY requests. SUBSCRIBE and NOTIFY requests.
4.3. 'diff-processing' Event Package Parameter 4.3. 'diff-processing' Event Package Parameter
With the aid of the optional "diff-processing" Event header field With the aid of the optional "diff-processing" Event header field
parameter, the subscriber indicates a preference as to how the parameter, the subscriber indicates a preference as to how the
notifier SHOULD indicate change notifications of documents. The notifier SHOULD indicate change notifications of documents. The
possible values are "no-patching", "xcap-patching", and "aggregate". possible values are "no-patching", "xcap-patching", and "aggregate".
All three modes provide information that allows the subscriber to All three modes provide information that allows the subscriber to
synchronize its local cache, but only the "xcap-patching" mode synchronize its local cache, but only the "xcap-patching" mode
provides intermediate states of the version history. The notifier provides intermediate states of the version history. The notifier
SHOULD use the indicated mode if it understands it (as such optimizes SHOULD use the indicated mode if it understands it (as such optimizes
network traffic within the capabilities of the receiver), but MAY use network traffic within the capabilities of the receiver).
"xcap-patching" as a matter of local policy, as all subscribers are
required to support that mode.
The "no-patching" value means that the notifier indicates only the The "no-patching" value means that the notifier indicates only the
document and the event type (creation, modification, and removal) document and the event type (creation, modification, and removal)
in the notification. The notification does not necessarily in the notification. The notification does not necessarily
indicate the full HTTP ETag change history. Subscribers and indicate the full HTTP ETag change history. Notifiers MUST
notifiers MUST support the "no-patching" mode as a base-line for support the "no-patching" mode as a base-line for
interoperability. The other, more complex modes are optional. interoperability. The other, more complex modes are optional.
The "xcap-patching" value means that the notifier includes all The "xcap-patching" value means that the notifier includes all
updated XCAP component contents and entity tag (ETag) changes. updated XCAP component contents and entity tag (ETag) changes made
The client receives the full (HTTP) ETag change history of a by XCAP clients (via HTTP). The client receives the full (HTTP)
document. This is equivalent to sending individual notifications ETag change history of a document.
for each change.
The "aggregate" value means that the notifier MAY aggregate The "aggregate" value means that the notifier MAY aggregate
several individual XCAP component updates into a single XCAP Diff several individual XCAP component updates into a single XCAP Diff
<document> element. The policy for determining whether or not to <document> element. The policy for determining whether or not to
apply aggregation or to determine how many updates to aggregate is apply aggregation or to determine how many updates to aggregate is
locally determined. The notifier SHOULD support the "aggregate" locally determined.
mode and implement XML-Patch-Ops ( [RFC5261]) diff-generation,
because this can greatly reduce the number of notification The notifier SHOULD support the "xcap-patching" and "aggregate"
operations required. modes, and thus implement XML-Patch-Ops ( [RFC5261]) diff-
generation, because this can greatly reduce the required number of
notifications and overall transmissions.
If the subscription does not contain the "diff-processing" header If the subscription does not contain the "diff-processing" header
field parameter, the notifier SHOULD default to the "no-patching" field parameter, the notifier MUST default to the "no-patching" mode.
mode, as this is the only mode for which implementation is required
in both subscribers and notifiers.
Note: To see the difference between "xcap-patching" and Note: To see the difference between "xcap-patching" and
"aggregate" modes, consider a document that has versions "a", "b" "aggregate" modes, consider a document that has versions "a", "b"
and "c" with corresponding ETag values "1", "2" and "3". The and "c" with corresponding ETag values "1", "2" and "3". The
"xcap-patching" mode will include first the change from version "xcap-patching" mode will include first the change from version
"a" to "b" with the versions' corresponding "1" and "2" ETags and "a" to "b" with the versions' corresponding "1" and "2" ETags and
then the change from version "b" to "c" with their "2" and "3" then the change from version "b" to "c" with their "2" and "3"
ETags. The "aggregate" mode optimizes the change and indicates ETags. The "aggregate" mode optimizes the change and indicates
only a single aggregated change from "a" to "c" with the old "1" only a single aggregated change from "a" to "c" with the old "1"
and new "3" ETags. If these changes are closely related, that is, and new "3" ETags. If these changes are closely related, that is,
skipping to change at page 7, line 24 skipping to change at page 7, line 24
document does not constrain that URI. It is assumed that the document does not constrain that URI. It is assumed that the
subscriber is provisioned with or has learned the URI of the notifier subscriber is provisioned with or has learned the URI of the notifier
of this event package. of this event package.
The XCAP server will usually be co-located with the SIP notifier, so The XCAP server will usually be co-located with the SIP notifier, so
the subscriber MAY use relative XCAP Request-URIs. Because relative the subscriber MAY use relative XCAP Request-URIs. Because relative
Request-URIs are allowed, the notifier MUST know how to resolve these Request-URIs are allowed, the notifier MUST know how to resolve these
against the correct XCAP Root URI value. against the correct XCAP Root URI value.
Figure 1 shows a SUBSCRIBE request and body covering several XCAP Figure 1 shows a SUBSCRIBE request and body covering several XCAP
resources: a "resource-list" document, a specific element in a "rls- resources: a "resource-list" document, a specific element (XCAP
services" document, and a collection in "pidf-manipulation" component) in a "rls-services" document, and a collection in "pidf-
application usage. The "Content-Type" header of this SUBSCRIBE manipulation" application usage. The "Content-Type" header of this
request is "application/resource-lists+xml". SUBSCRIBE request is "application/resource-lists+xml".
SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0
... ...
Accept: application/xcap-diff+xml Accept: application/xcap-diff+xml
Event: xcap-diff; diff-processing=aggregate Event: xcap-diff; diff-processing=aggregate
Content-Type: application/resource-lists+xml Content-Type: application/resource-lists+xml
Content-Length: [XXX] Content-Length: [XXX]
Expires: 4200 Expires: 4200
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists">
<list> <list>
<entry uri="resource-lists/users/sip:joe@example.com/index"/> <entry uri="resource-lists/users/sip:joe@example.com/index"/>
<entry uri="rls-services/users/sip:joe@example.com/index/ <entry uri="rls-services/users/sip:joe@example.com/index/
~~/*/service%5b@uri='sip:marketing@example.com'%5d"/> ~~/*/service%5b@uri='sip:marketing@example.com'%5d"/>
<entry uri="pidf-manipulation/"/> <entry uri="pidf-manipulation/"/>
</list> </list>
</resource-lists> </resource-lists>
Figure 1: Example subscription body Figure 1: Example subscription body
When subscribing to XCAP components, namespace prefixes of XCAP Node
Selectors MUST be properly resolved to namespace URIs. Section 6.4.
of RFC 4825 [RFC4825] describes the conventions when using prefixes
in XCAP Node Selectors. If only XCAP Default Document Namespace is
used, just like in the previous example (<service> element), the
query component of the "uri" value is not required.
4.5. Subscription Duration 4.5. Subscription Duration
The default expiration time for subscriptions within this package is The default expiration time for subscriptions within this package is
3600 seconds. As per RFC 3265 [RFC3265], the subscriber MAY specify 3600 seconds. As per RFC 3265 [RFC3265], the subscriber MAY specify
an alternative expiration timer in the Expires header field. an alternative expiration timer in the Expires header field.
4.6. NOTIFY Bodies 4.6. NOTIFY Bodies
The format of the NOTIFY message body is either the default of The format of the NOTIFY message body is either the default of
"application/xcap-diff+xml" or is a format listed in the Accept "application/xcap-diff+xml" or is a format listed in the Accept
header field of the SUBSCRIBE. header field of the SUBSCRIBE.
In this event package, notification messages contain an XCAP Diff In this event package, notification messages contain an XCAP Diff
document . document [I-D.ietf-simple-xcap-diff].
The XCAP Diff format [I-D.ietf-simple-xcap-diff] can include the full The XCAP Diff format [I-D.ietf-simple-xcap-diff] can include the
element and attribute content of XCAP documents and components. For subscribed XCAP component contents. For documents, the format can
documents, the format can also include corresponding URIs, ETag also include corresponding URIs, ETag values, and patching
values, and patching instructions from version "a" to "b". Removal instructions from version "a" to "b". Removal events (of documents,
events (of documents, elements, or attributes) can be identified too. elements, or attributes) can be identified too. Except for
Except for collection selections, the "sel" selector values of the collection selections, the "sel" selector values of the XCAP-Diff
XCAP-Diff format MUST be octet-by-octet equivalent to the relevant format MUST be octet-by-octet equivalent to the relevant "uri"
"uri" parameter values of the <entry> element of the "resource-list" parameter values of the <entry> element of the "resource-list"
document. document.
With XCAP component subscriptions, XCAP Node Selectors can contain
namespace prefixes. A notifier MUST then resolve these prefixes to
namespace URIs according to RFC 4825 [RFC4825] conventions. In other
words, notifiers MUST be aware of XCAP Default Document Namespaces
for Application Usages when they locate unprefixed qualified XCAP
elements. Note that the namespace resolving rules of Patch operation
elements: <add>, <replace> and <remove> are described in Section
4.2.1 of [RFC5261].
4.7. Notifier Generation of NOTIFY Requests 4.7. Notifier Generation of NOTIFY Requests
During the initial subscription, or if the URI list changes in During the initial subscription, or if the URI list changes in
SUBSCRIBE refresh requests, the notifier MUST resolve the requested SUBSCRIBE refresh requests, the notifier MUST resolve the requested
XCAP resources and their privileges. If there are superfluous XCAP resources and their privileges. If there are superfluous
resource selections in the requested URI list, the notifier SHOULD resource selections in the requested URI list, the notifier SHOULD
NOT provide overlapping similar responses for these resources. A NOT provide overlapping similar responses for these resources. A
resource for which an authenticated user does not have a read resource for which an authenticated user does not have a read
privilege MUST NOT be included in the XCAP-Diff format. Note that an privilege MUST NOT be included in the XCAP-Diff format. Note that an
XCAP component that could not be located with XCAP semantics does not XCAP component that could not be located with XCAP semantics does not
produce an error. Instead, the request remains in a "pending" state, produce an error. Instead, the request remains in a "pending" state,
that is, waiting for this resource to be created (or read access that is, waiting for this resource to be created (or read access
granted). Subscriptions to collections have a similar property: once granted if XCAP Application Usages utilize dynamic access control
a new document is created into the subscribed collection, the lists). Subscriptions to collections have a similar property: once a
creation of a new resource is signaled with the next NOTIFY request. new document is created into the subscribed collection, the creation
of a new resource is signaled with the next NOTIFY request.
After the notifier knows the list of authorized XCAP resources, it After the notifier knows the list of authorized XCAP resources, it
generates the first NOTIFY, which contains URI references to all generates the first NOTIFY, which contains URI references to all
subscribed, existing documents for which the subscriber has read subscribed, existing documents for which the subscriber has read
privileges, and typically XCAP component(s) of existing content. privileges, and typically XCAP component(s) of existing content.
After sending the initial notification, the notifier selects a diff- After sending the initial notification, the notifier selects a diff-
processing mode for reporting changes. If the subscriber suggested a processing mode for reporting changes. If the subscriber suggested a
mode in the "diff-processing" parameter of the SUBSCRIBE, the mode in the "diff-processing" parameter of the SUBSCRIBE, the
notifier MAY use that requested mode or MAY fall back to a simpler notifier MAY use that requested mode or MAY fall back to a simpler
skipping to change at page 9, line 19 skipping to change at page 9, line 35
patching", "aggregate". Thus, the notifier may respond to an patching", "aggregate". Thus, the notifier may respond to an
"aggregate" request using any mode, but cannot reply to an "xcap- "aggregate" request using any mode, but cannot reply to an "xcap-
patching" subscription using the "aggregate" mode. Naturally, the patching" subscription using the "aggregate" mode. Naturally, the
notifier MUST handle a "no-patching" request with the "no-patching" notifier MUST handle a "no-patching" request with the "no-patching"
mode. mode.
In all modes, the notifier MUST maintain the chronological order of In all modes, the notifier MUST maintain the chronological order of
XCAP changes. If several changes to a given resource are presented XCAP changes. If several changes to a given resource are presented
in a single notification, the chronological update order MUST be in a single notification, the chronological update order MUST be
preserved in the XML document order of the notification body. preserved in the XML document order of the notification body.
Preservation of chronological order is required to produce a correct Chronological order is preserved to simplify the required subscriber
document in the subscriber. If content modifications are made out- implementation logic.
of-order, an erroneous document would probably be formed.
While the "aggregate" mode uses bandwidth most efficiently, it While the "aggregate" mode uses bandwidth most efficiently, it
introduces other challenges. The initial synchronization might fail introduces other challenges. The initial synchronization might fail
with rapidly changing resources, because the "aggregate" mode with rapidly changing resources, because the "aggregate" mode
messages might not include the full version-history of a document and messages might not include the full version-history of a document and
the base XCAP protocol does not support version-history retrievals of the base XCAP protocol does not support version-history retrievals of
documents. When new documents are created in subscribed collections documents. When new documents are created in subscribed collections
and the notifier is aggregating patches, the same issue can occur. and the notifier is aggregating patches, the same issue can occur.
In a corner case, the notifier may not be able to provide patches In a corner case, the notifier may not be able to provide patches
with the XML-Patch-Ops [RFC5261] semantics. Therefore, if the with the XML-Patch-Ops [RFC5261] semantics.
notifier has to temporarily disable diff generation and send only the
URI references of some changed documents to the subscriber, it MUST If the notifier has to temporarily disable diff generation and send
continue with the "xcap-patching" mode afterwards for these only the URI references of some changed documents to the subscriber,
it MUST continue with the "xcap-patching" mode afterwards for these
resources, if the initial subscription also started with the "xcap- resources, if the initial subscription also started with the "xcap-
patching" mode. In other words, if the subscriber loses track of the patching" mode.
patching operations, the subscriber must refresh to a "known good"
state by downloading the current document. Once it has done so, it Note: The diff-generation may be disabled when the NOTIFY body
can resume using xcap-patching. becomes impractically large or an intermediate error has happened.
As the subscriber loses then track of the patching operations, it
must refresh to a "known good" state by downloading current
documents. Once it has done so, it can re-subscribe for example
with the "aggregate" mode.
In the "aggregate" mode, the notifier chooses how long to wait for In the "aggregate" mode, the notifier chooses how long to wait for
multiple patches to combine. Even with rapidly changing resources multiple patches to combine and how this combination is done.
the notifier MUST signal only the latest state: e.g. whether the XCAP
component exists or not.
In the "xcap-patching" mode, the notifier MAY disable the diff- In the "xcap-patching" mode, the notifier MAY try to optimize the
generation temporarily for certain resources, for example when the diff-generation, for example by eliminating redundant information
NOTIFY body becomes impractically large or an intermediate error has since some XCAP clients will probably not have completely optimized
happened. Some XCAP clients will probably not have completely their HTTP PUT request.
optimized their patch request, so even when acting in the "xcap-
patching" operational mode, the notifier MAY try to optimize the
diff-generation, for example by eliminating redundant patch
operations. Otherwise said: the notifier is not required to send
patch operations exactly as received by clients; rather it MAY notify
with a more efficient patch operation that MUST produce the same
result as the series of patch operations produced by the XCAP client.
Note: It is straightforward to change the XCAP client's change Note: It is straightforward to change the XCAP client's change
requests (sent via HTTP) to use XML-Patch-Ops semantics. While requests: PUT and DELETE (sent via HTTP) to use XML-Patch-Ops
XCAP does not support patching of all XML node types - for semantics. While XCAP does not support patching of all XML node
example, namespace declarations can not be added separately - types - for example, namespace declarations can not be added
utilization of XML-Patch-Ops can sometimes significantly reduce separately - efficient utilization of XML-Patch-Ops can sometimes
the bandwidth requirements at the expense of extra processing. significantly reduce the bandwidth requirements at the expense of
Extension of XCAP for this utilization of patch-ops is outside the extra processing.
scope of this document, but it is evident that XCAP clients that
produce efficient change requests using XML-Patch-Ops make it much
easier for the notifier to produce an efficient change
notification using XML-Patch-Ops.
After the notifier has reported the existence of an XCAP component, After the notifier has reported the existence of an XCAP component,
it MUST also report its removal consistently. For example, the it MUST also report its removal consistently. For example, the
removal of the parent element of the subscribed element requires the removal of the parent element of the subscribed element requires the
same signalling since the subscribed element ceases to exist. To same signalling since the subscribed element ceases to exist. To
signal the removal of an XCAP component, the notifier sets the signal the removal of an XCAP component, the notifier sets the
Boolean "exist" attribute value of the <element> or <attribute> Boolean "exist" attribute value of the <element> or <attribute>
elements to false. elements to false. Even with rapidly changing resources the notifier
MUST signal only the latest state: e.g. whether the XCAP component
exists or not.
When the notifier receives a re-subscription, it MUST re-send the When the notifier receives a re-subscription, it MUST re-send the
current full XML-Diff content unless the subscriber has requested a current full XML-Diff content unless the subscriber has requested a
conditional subscription [I-D.ietf-sipcore-subnot-etags] by using the conditional subscription [I-D.ietf-sipcore-subnot-etags] by using the
header field Suppress-If-Match: [ETag value]. With a conditional re- header field Suppress-If-Match: [ETag value]. With a conditional re-
subscription, the notifier MUST also inspect the subscription body subscription, the notifier MUST also inspect the subscription body
when determining the current subscription state. Since the when determining the current subscription state. Since the
subscription is based on a list of XCAP R-URIs, it is RECOMMENDED subscription is based on a list of XCAP R-URIs, it is RECOMMENDED
that the notifier does not consider the order of these URIs when that the notifier does not consider the order of these URIs when
determining the equivalence to "stored" previous states. If a match determining the equivalence to "stored" previous states. If a match
skipping to change at page 11, line 33 skipping to change at page 11, line 42
<element> element does not not have a child element which would show <element> element does not not have a child element which would show
the subscribed "full" element content. the subscribed "full" element content.
4.8. Subscriber Processing of NOTIFY Requests 4.8. Subscriber Processing of NOTIFY Requests
The first NOTIFY request will usually contain references to HTTP The first NOTIFY request will usually contain references to HTTP
resources including their strong ETag values. If the subscriber does resources including their strong ETag values. If the subscriber does
not have similar locally cached versions, it will typically start an not have similar locally cached versions, it will typically start an
unconditional HTTP GET request for those resources. During this HTTP unconditional HTTP GET request for those resources. During this HTTP
retrieval time, the subscriber MAY also receive patches to these retrieval time, the subscriber MAY also receive patches to these
documents (if it has requested them) if the documents are changing. documents (if it has requested them) and if the documents are
A subscriber can chain the modification list for the document and changing rapidly. It can happen that the version retrieved by HTTP
aggregate the changes itself if the notifications contain patches and is not the same than what is indicated in the initial notification.
indicate all atomic XCAP modifications with both previous and new A subscriber can then chain the modification list for each document,
ETags of each resource ("xcap-patching" mode). If the version and locate the position where the previous ETag value is equal to
received via HTTP is newer than any received via the notifications, that retrieved via HTTP. If an ETag match is not found from the
the subscriber may not find an equivalent match of an ETag value from first change, a subscriber MUST omit all changes up to the point
the chain of patches. This can happen since notifications are where it is the same. From that change onwards, the subscriber
reported after HTTP changes and preferably at some minimum intervals. applies all reported patches. If the version received via HTTP is
In such a case, the subscriber SHOULD either wait for subsequent newer than any received via the notifications, the subscriber may not
notifications or refresh the subscription and repeat the described find an equivalent match of an ETag value from the chain of patches.
"sync" algorithm until a match is achieved.
To avoid out-of-sync issues, the subscriber MAY start the This can happen since notifications are reported after HTTP changes
subscription with the "xcap-patching" mode, and then refresh the and preferably at some minimum intervals. Also document removals can
subscription with the "aggregate" mode. Syncs are successful if the be reported in notifications and/or HTTP retrievals may fail because
received HTTP ETag matches with either the previous or new ETag of of unexisting resources (rapidly changing). In any case, the
the reported aggregated patch. If the subscription is started with subscriber can re-fetch the possible out-of-sync document, wait for
the "aggregate" mode, which doesn't necessarily show the full subsequent notifications or refresh the subscription (with "xcap-
version-history information, the subscriber may not be able to patching") and repeat the described "sync" algorithm until a "full"
synchronize its local cache with the first notification. The sync is achieved.
subscriber MAY resolve this issue by doing one of the following: re-
fetching the out-of-sync document, waiting for subsequent If the notifier aggregates patches, the previous modification list
notifications, or by refreshing the subscription. However, the same may not contain the ETag value retrieved by HTTP simply because of
issue may still repeat. aggregation optimizations. A similar out-of-sync cycle can happen
when new (subscribed) documents are created which change rapidly. To
avoid such difficulties, the subscriber MAY start the subscription
with the "xcap-patching" mode, and then refresh the subscription with
the "aggregate" mode after the initial sync is achieved. Naturally,
the subscriber can revert back to the "xcap-patching" mode from
"aggregate" at anytime and vice versa.
If the subscriber has received a "full" sync and it has detected that If the subscriber has received a "full" sync and it has detected that
some of the resources are being served with the "xcap-patching" mode some of the resources are being served with the "xcap-patching" mode
while others are in the "aggregate" mode, it SHOULD refresh the while others are in the "aggregate" mode, it SHOULD refresh the
subscription to the "aggregate" mode. subscription to the "aggregate" mode.
The notifier MAY at any time temporarily use the "no-patching" mode The notifier MAY at any time temporarily use the "no-patching" mode
for some resources so that the subscriber receives only URI for some resources so that the subscriber receives only URI
references of modifications. When the notifier is acting in this references of modifications. When the notifier is acting in this
mode, several cycles MAY be needed before an initial "full" sync is mode, several cycles MAY be needed before an initial "full" sync is
skipping to change at page 14, line 5 skipping to change at page 14, line 5
by the first NOTIFY request to the SUBSCRIBE example in Figure 1. by the first NOTIFY request to the SUBSCRIBE example in Figure 1.
The following is an example Event header field for this SUBSCRIBE The following is an example Event header field for this SUBSCRIBE
request: request:
Event: xcap-diff; diff-processing=aggregate Event: xcap-diff; diff-processing=aggregate
The subscriber requests that the notifier "aggregate" XCAP component The subscriber requests that the notifier "aggregate" XCAP component
updates and anticipates that the subsequent notifications will updates and anticipates that the subsequent notifications will
contain aggregated patches to these documents. contain aggregated patches to these documents.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/root/"> xmlns:s="urn:ietf:params:xml:ns:rls-services"
<document new-etag="7ahggs" xcap-root="http://xcap.example.com/root/">
sel="resource-lists/users/sip:joe@example.com/index"/>
<document new-etag="30376adf" <d:document new-etag="7ahggs"
sel="pidf-manipulation/users/sip:joe@example.com/index"/> sel="resource-lists/users/sip:joe@example.com/index"/>
<d:element sel="rls-services/users/sip:joe@example.com/index/
~~/*/service%5b@uri='sip:marketing@example.com'%5d" <d:document new-etag="30376adf"
xmlns:d="urn:ietf:params:xml:ns:xcap-diff" sel="pidf-manipulation/users/sip:joe@example.com/index"/>
xmlns="urn:ietf:params:xml:ns:rls-services"
xmlns:rl="urn:ietf:params:xml:ns:resource-lists"> <d:element sel="rls-services/users/sip:joe@example.com/index/
<service uri="sip:marketing@example.com"> ~~/*/service%5b@uri='sip:marketing@example.com'%5d"
<list name="marketing"> xmlns:rl="urn:ietf:params:xml:ns:resource-lists"
<rl:entry uri="sip:joe@example.com"/> ><s:service uri="sip:marketing@example.com">
<rl:entry uri="sip:sudhir@example.com"/> <s:list name="marketing">
</list> <rl:entry uri="sip:joe@example.com"/>
<packages> <rl:entry uri="sip:sudhir@example.com"/>
<package>presence</package> </s:list>
</packages> <s:packages>
</service> <s:package>presence</s:package>
</d:element> </s:packages>
</xcap-diff> </s:service></d:element>
</d:xcap-diff>
Figure 2: An example initial XCAP Diff format document Figure 2: An example initial XCAP Diff format document
Note that the resource-list "index" document included only the new Note that the resource-list "index" document included only the new
ETag value, as the document existed during the subscription time. In ETag value, as the document existed during the subscription time. In
the "pidf-manipulation" collection, there is only a single document the "pidf-manipulation" collection, there is only a single document
for which the user has read privilege. The <services> element exists for which the user has read privilege. The <services> element exists
within the rls-services "index" document and its content is shown. within the rls-services "index" document and its content is shown.
Note also that the <services> element was located using the Default
Document Namespace (no prefix in XCAP Node Selector value) although
it has an "s" prefix in the source document.
6. IANA Considerations 6. IANA Considerations
This specification instructs IANA to add a new event package to the This specification instructs IANA to add a new event package to the
SIP Event Types Namespace registry. The new data to be added is: SIP Event Types Namespace registry. The new data to be added is:
Package Name Type Contact Reference Package Name Type Contact Reference
------------- -------- ------- --------- ------------- -------- ------- ---------
xcap-diff package IETF SIP Working Group [RFCXXXX] xcap-diff package IETF SIP Working Group [RFCXXXX]
<sip@ietf.org> <sip@ietf.org>
skipping to change at page 16, line 14 skipping to change at page 16, line 14
comments and cleaning up the technical English usage. comments and cleaning up the technical English usage.
9. References 9. References
9.1. Normative References 9.1. Normative References
[I-D.ietf-simple-xcap-diff] [I-D.ietf-simple-xcap-diff]
Rosenberg, J. and J. Urpalainen, "An Extensible Markup Rosenberg, J. and J. Urpalainen, "An Extensible Markup
Language (XML) Document Format for Indicating A Change in Language (XML) Document Format for Indicating A Change in
XML Configuration Access Protocol (XCAP) Resources", XML Configuration Access Protocol (XCAP) Resources",
draft-ietf-simple-xcap-diff-09 (work in progress), draft-ietf-simple-xcap-diff-13 (work in progress),
May 2008. June 2009.
[I-D.ietf-sipcore-subnot-etags] [I-D.ietf-sipcore-subnot-etags]
Niemi, A., "An Extension to Session Initiation Protocol Niemi, A., "An Extension to Session Initiation Protocol
(SIP) Events for Conditional Event Notification", (SIP) Events for Conditional Event Notification",
draft-ietf-sipcore-subnot-etags-02 (work in progress), draft-ietf-sipcore-subnot-etags-02 (work in progress),
April 2009. April 2009.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
skipping to change at page 17, line 18 skipping to change at page 17, line 18
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918, June 2007. Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
[RFC5263] Lonnfors, M., Costa-Requena, J., Leppanen, E., and H. [RFC5263] Lonnfors, M., Costa-Requena, J., Leppanen, E., and H.
Khartabil, "Session Initiation Protocol (SIP) Extension Khartabil, "Session Initiation Protocol (SIP) Extension
for Partial Notification of Presence Information", for Partial Notification of Presence Information",
RFC 5263, September 2008. RFC 5263, September 2008.
[W3C.REC-xml-20060816] [W3C.REC-xml-20060816]
Sperberg-McQueen, C., Paoli, J., Bray, T., Maler, E., and Maler, E., Paoli, J., Bray, T., Yergeau, F., and C.
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth Sperberg-McQueen, "Extensible Markup Language (XML) 1.0
Edition)", World Wide Web Consortium FirstEdition REC-xml- (Fourth Edition)", World Wide Web Consortium
20060816, August 2006, Recommendation REC-xml-20060816, August 2006,
<http://www.w3.org/TR/2006/REC-xml-20060816>. <http://www.w3.org/TR/2006/REC-xml-20060816>.
Appendix A. Informative Examples Appendix A. Informative Examples
These examples illustrate the basic features of the xcap-diff event These examples illustrate the basic features of the xcap-diff event
package. Only the relevant header fields are shown. Note also that package. Only the relevant header fields are shown. Note also that
the SIP R-URIs of these examples don't correspond to reality. the SIP R-URIs of these examples don't correspond to reality.
A.1. Initial documents on an XCAP server A.1. Initial documents on an XCAP server
The following documents exist on an XCAP server (xcap.example.com) The following documents exist on an XCAP server (xcap.example.com)
with an imaginary "tests" application usage (there's no default with an imaginary "tests" application usage (there's no default
document namespace defined in this imaginary application usage). document namespace defined in this imaginary application usage).
http://xcap.example.com/tests/users/sip:joe@example.com/index: http://xcap.example.com/tests/users/sip:joe@example.com/index:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
</doc> </doc>
and then and then
http://xcap.example.com/tests/users/sip:john@example.com/index: http://xcap.example.com/tests/users/sip:john@example.com/index:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is another sample document</note> <note>This is another sample document</note>
</doc> </doc>
A.2. An Initial Subscription A.2. An Initial Subscription
The following demonstrates the listing of a collection contents and The following demonstrates the listing of a collection contents and
it shows only resources where the user has read privilege. The user it shows only resources where the user has read privilege. The user
Joe, whose XUI is "sip:joe@example.com", sends an initial Joe, whose XUI is "sip:joe@example.com", sends an initial
subscription: subscription:
SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0
... ...
Accept: application/xcap-diff+xml Accept: application/xcap-diff+xml
Event: xcap-diff; diff-processing=aggregate Event: xcap-diff; diff-processing=aggregate
Content-Type: application/resource-lists+xml Content-Type: application/resource-lists+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists">
<list> <list>
<entry uri="tests/users/sip:joe@example.com/"/> <entry uri="tests/users/sip:joe@example.com/"/>
</list> </list>
</resource-lists> </resource-lists>
In addition to the 200 (OK) response, the notifier sends the first In addition to the 200 (OK) response, the notifier sends the first
NOTIFY: NOTIFY:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"> xcap-root="http://xcap.example.com/">
<document new-etag="7ahggs"
sel="tests/users/sip:joe@example.com/index"/> <document new-etag="7ahggs"
</xcap-diff> sel="tests/users/sip:joe@example.com/index"/>
</xcap-diff>
The subscriber learns that the document on this "tests" application The subscriber learns that the document on this "tests" application
usage is equivalent to its locally cached version, so it does not usage is equivalent to its locally cached version, so it does not
act. If the local version had been different, the subscriber would act. If the local version had been different, the subscriber would
most likely re-fetch the document. most likely re-fetch the document.
If the subscriber had requested the "tests/users/" collection, the If the subscriber had requested the "tests/users/" collection, the
notification body would have been the same since Joe has no read notification body would have been the same since Joe has no read
privilege to John's resources (XCAP default behavior). privilege to John's resources (XCAP default behavior).
skipping to change at page 19, line 29 skipping to change at page 19, line 33
either the same client or another client running on a different either the same client or another client running on a different
device. He does an HTTP PUT to his application usage collection: device. He does an HTTP PUT to his application usage collection:
PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1 PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1
Host: xcap.example.com Host: xcap.example.com
.... ....
Content-Type: application/xml Content-Type: application/xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is another sample document</note> <note>This is another sample document</note>
</doc> </doc>
This HTTP PUT request results in the XCAP client receiving a strong This HTTP PUT request results in the XCAP client receiving a strong
HTTP ETag "terteer" for this new document. HTTP ETag "terteer" for this new document.
Then the subscriber receives a notification afterwards: Then the subscriber receives a notification afterwards:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"> xcap-root="http://xcap.example.com/">
<document new-etag="terteer"
sel="tests/users/sip:joe@example.com/another_document"/>
</xcap-diff> <document new-etag="terteer"
sel="tests/users/sip:joe@example.com/another_document"/>
</xcap-diff>
Note that the result is "additive"; it doesn't indicate the already Note that the result is "additive"; it doesn't indicate the already
indicated "index" document. Only the initial (or refreshed) indicated "index" document. Only the initial (or refreshed)
notification contains all document URI references. notification contains all document URI references.
If Joe's client both modifies the documents and refreshes the If Joe's client both modifies the documents and refreshes the
subscriptions, it would typically ignore this notification, since its subscriptions, it would typically ignore this notification, since its
modifications had caused the notification. If the client that modifications had caused the notification. If the client that
received this NOTIFY hadn't submitted the document change, it would received this NOTIFY hadn't submitted the document change, it would
probably fetch this new document. probably fetch this new document.
skipping to change at page 20, line 46 skipping to change at page 21, line 15
document. document.
Immediately thereafter, Joe's client issues another HTTP request Immediately thereafter, Joe's client issues another HTTP request
(this request could even be pipe-lined): (this request could even be pipe-lined):
PUT /tests/users/sip:joe@example.com/index/~~/doc/bar HTTP/1.1 PUT /tests/users/sip:joe@example.com/index/~~/doc/bar HTTP/1.1
Host: xcap.example.com Host: xcap.example.com
.... ....
Content-Type: application/xcap-el+xml Content-Type: application/xcap-el+xml
Content-Length: [XXX] Content-Length: [XXX]
<bar>this is a bar element
</bar> <bar>this is a bar element
</bar>
The reported new HTTP ETag of "index" is now "dgdgdfgrrr". The reported new HTTP ETag of "index" is now "dgdgdfgrrr".
And Joe's client issues yet another HTTP request: And Joe's client issues yet another HTTP request:
PUT /tests/users/sip:joe@example.com/index/~~/doc/foobar HTTP/1.1 PUT /tests/users/sip:joe@example.com/index/~~/doc/foobar HTTP/1.1
Host: xcap.example.com Host: xcap.example.com
.... ....
Content-Type: application/xcap-el+xml Content-Type: application/xcap-el+xml
Content-Length: [XXX] Content-Length: [XXX]
skipping to change at page 21, line 30 skipping to change at page 22, line 12
patch since it has requested "aggregate" diff-processing and the patch since it has requested "aggregate" diff-processing and the
notifier is capable of producing them: notifier is capable of producing them:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff" <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"> xcap-root="http://xcap.example.com/">
<d:document previous-etag="7ahggs3"
sel="tests/users/sip:joe@example.com/index" <d:document previous-etag="7ahggs3"
new-etag="63hjjsll"> sel="tests/users/sip:joe@example.com/index"
<d:add sel="*"> new-etag="63hjjsll">
<foo>this is a new element</foo> <d:add sel="*"
<bar>this is a bar element ><foo>this is a new element</foo><bar>this is a bar element
</bar> </bar><foobar>this is a foobar element</foobar></d:add>
<foobar>this is a foobar element</foobar> </d:document>
</d:add>
</d:document> </d:xcap-diff>
</d:xcap-diff>
Joe's client applies this patch to the locally cached "index" Joe's client applies this patch to the locally cached "index"
document, detects the ETag update, and stores the last ETag value. document, detects the ETag update, and stores the last ETag value.
Note how several XCAP component modifications were aggregated. Note how several XCAP component modifications were aggregated.
Note also that, if Joe's client did not have a locally cached version Note also that, if Joe's client did not have a locally cached version
of the reference document, it would have needed to do a HTTP GET of the reference document, it would have needed to do a HTTP GET
request after the initial notification. If the ETag of the received request after the initial notification. If the ETag of the received
resource by HTTP did not match either the previous or new ETag of resource by HTTP did not match either the previous or new ETag of
this aggregated patch, an out-of-sync condition would be probable. this aggregated patch, an out-of-sync condition would be probable.
skipping to change at page 22, line 25 skipping to change at page 23, line 13
patching", the NOTIFY could have been the following: patching", the NOTIFY could have been the following:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff" <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"> xcap-root="http://xcap.example.com/">
<d:document previous-etag="7ahggs"
sel="tests/users/sip:joe@example.com/index" <d:document previous-etag="7ahggs"
new-etag="fgherhryt3"> sel="tests/users/sip:joe@example.com/index"
<d:add sel="*"> new-etag="fgherhryt3">
<foo>this is a new element</foo> <d:add sel="*"
</d:add> ><foo>this is a new element</foo></d:add></d:document>
</d:document>
<d:document previous-etag="fgherhryt3" <d:document previous-etag="fgherhryt3"
sel="tests/users/sip:joe@example.com/index" sel="tests/users/sip:joe@example.com/index"
new-etag="dgdgdfgrrr"> new-etag="dgdgdfgrrr">
<d:add sel="*"> <d:add sel="*"
<bar>this is a bar element ><bar>this is a bar element
</bar> </bar></d:add></d:document>
</d:add>
</d:document> <d:document previous-etag="dgdgdfgrrr"
<d:document previous-etag="dgdgdfgrrr" sel="tests/users/sip:joe@example.com/index"
sel="tests/users/sip:joe@example.com/index" new-etag="63hjjsll">
new-etag="63hjjsll"> <d:add sel="*"
<d:add sel="*"> ><foobar>this is a foobar element</foobar></d:add></d:document>
<foobar>this is a foobar element</foobar>
</d:add>
</d:document>
</d:xcap-diff> </d:xcap-diff>
If the client had to re-fetch the "index" document after the initial If the client had to re-fetch the "index" document after the initial
notification, it could have skipped some or all of these patches, notification, it could have skipped some or all of these patches,
depending on whether the HTTP ETag matched some of these ETags in the depending on whether the HTTP ETag matched some of these ETags in the
chain of patches. If the HTTP ETag did not match and the received chain of patches. If the HTTP ETag did not match and the received
HTTP version is a newer version indicated in later notification(s) HTTP version is a newer version indicated in later notification(s)
then the sync may then be achieved since the notifier provided the then the sync may then be achieved since the notifier provided the
full change history in the "xcap-patching" mode. full change history in the "xcap-patching" mode.
Lastly, the notifier could (temporarily) fall back to the "no- Lastly, the notifier could (temporarily) fall back to the "no-
patching" mode, which allows the notifier to keep the dialog alive patching" mode, which allows the notifier to keep the dialog alive
when there are too many updates: when there are too many updates:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"> xcap-root="http://xcap.example.com/">
<document previous-etag="7ahggs3"
sel="tests/users/sip:joe@example.com/index" <document previous-etag="7ahggs3"
new-etag="63hjjsll"/> sel="tests/users/sip:joe@example.com/index"
</xcap-diff> new-etag="63hjjsll"/>
</xcap-diff>
At any time, the notifier may fall back to the "no-patching" mode for At any time, the notifier may fall back to the "no-patching" mode for
some or all of the subscribed documents. some or all of the subscribed documents.
A.5. An XCAP Component Subscription A.5. An XCAP Component Subscription
The user Joe sends an initial subscription for the "id" affribute of The user Joe sends an initial subscription for the "id" affribute of
a <doc> element. The "index" document exists, but the <doc> root a <doc> element. The "index" document exists, but the <doc> root
element does not contain the "id" attribute at the time of the element does not contain the "id" attribute at the time of the
subscription. subscription.
SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0
... ...
Accept: application/xcap-diff+xml Accept: application/xcap-diff+xml
Event: xcap-diff Event: xcap-diff
Content-Type: application/resource-lists+xml Content-Type: application/resource-lists+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists">
<list> <list>
<entry uri="tests/users/sip:joe@example.com/index/~~/doc/@id"/> <entry uri="tests/users/sip:joe@example.com/index/~~/doc/@id"/>
</list> </list>
</resource-lists> </resource-lists>
The first NOTIFY looks like the following since there is nothing to The first NOTIFY looks like the following since there is nothing to
indicate: indicate:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"/> xcap-root="http://xcap.example.com/"/>
Note that if the "index" document hadn't existed, the first NOTIFY Note that if the "index" document hadn't existed, the first NOTIFY
request would have been the same. The XCAP Diff document format request would have been the same. The XCAP Diff document format
doesn't indicate reasons for non-existing resources. doesn't indicate reasons for non-existing resources.
Afterwards Joe's client updates the whole document root element Afterwards Joe's client updates the whole document root element
including the attribute "id" (not a typical XCAP operation nor a including the attribute "id" (not a typical XCAP operation nor a
preferred one, just an illustration here): preferred one, just an illustration here):
PUT /tests/users/sip:joe@example.com/index/~~/doc HTTP/1.1 PUT /tests/users/sip:joe@example.com/index/~~/doc HTTP/1.1
skipping to change at page 25, line 4 skipping to change at page 25, line 30
including the attribute "id" (not a typical XCAP operation nor a including the attribute "id" (not a typical XCAP operation nor a
preferred one, just an illustration here): preferred one, just an illustration here):
PUT /tests/users/sip:joe@example.com/index/~~/doc HTTP/1.1 PUT /tests/users/sip:joe@example.com/index/~~/doc HTTP/1.1
Host: xcap.example.com Host: xcap.example.com
.... ....
Content-Type: application/xcap-el+xml Content-Type: application/xcap-el+xml
Content-Length: [XXX] Content-Length: [XXX]
<doc id="bar">This is a new root element</doc> <doc id="bar">This is a new root element</doc>
The new HTTP ETag of the "index" document is now "dwawrrtyy". The new HTTP ETag of the "index" document is now "dwawrrtyy".
Then Joe's client gets a notification: Then Joe's client gets a notification:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"> xcap-root="http://xcap.example.com/">
<attribute
sel="tests/users/sip:joe@example.com/index/~~/doc/@id"> <attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id"
bar >bar</attribute>
</attribute>
</xcap-diff> </xcap-diff>
Note that the HTTP ETag value of the new document is not shown as it Note that the HTTP ETag value of the new document is not shown as it
is irrelevant for this use-case. is irrelevant for this use-case.
Then Joe's client removes the "id" attribute: Then Joe's client removes the "id" attribute:
DELETE /tests/users/sip:joe@example.com/index/~~/doc/@id HTTP/1.1 DELETE /tests/users/sip:joe@example.com/index/~~/doc/@id HTTP/1.1
Host: xcap.example.com Host: xcap.example.com
.... ....
Content-Length: 0 Content-Length: 0
And the subscriber gets a notification: And the subscriber gets a notification:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"> xcap-root="http://xcap.example.com/">
<attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id"
exists="0"/>
</xcap-diff>
<attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id"
exists="0"/>
</xcap-diff>
The notification indicates that the subscribed attribute was removed The notification indicates that the subscribed attribute was removed
from the document. Naturally attributes are "removed" if the element from the document. Naturally attributes are "removed" if the element
where they belong is removed, for example by an HTTP DELETE request. where they belong is removed, for example by an HTTP DELETE request.
The component selections indicate only the existence of attributes or The component selections indicate only the existence of attributes or
elements. elements.
A.6. A Conditional Subscription A.6. A Conditional Subscription
The last example is a conditional subscription where a full refresh The last example is a conditional subscription where a full refresh
can be avoided when there are no changes in resources. Joe's client can be avoided when there are no changes in resources. Joe's client
sends an initial subscription: sends an initial subscription:
SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0
... ...
Accept: application/xcap-diff+xml Accept: application/xcap-diff+xml
Event: xcap-diff; diff-processing=xcap-patching Event: xcap-diff; diff-processing=xcap-patching
Content-Type: application/resource-lists+xml Content-Type: application/resource-lists+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists">
<list> <list>
<entry uri="tests/users/sip:joe@example.com/"/> <entry uri="tests/users/sip:joe@example.com/"/>
</list> </list>
</resource-lists> </resource-lists>
Since there are now two documents in the repository, the first NOTIFY Since there are now two documents in the repository, the first NOTIFY
looks like the following: looks like the following:
NOTIFY sip:joe@userhost.example.com SIP/2.0 NOTIFY sip:joe@userhost.example.com SIP/2.0
... ...
Event: xcap-diff Event: xcap-diff
SIP-ETag: xggfefe54 SIP-ETag: xggfefe54
Content-Type: application/xcap-diff+xml Content-Type: application/xcap-diff+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"> xcap-root="http://xcap.example.com/">
<document new-etag="63hjjsll"
sel="tests/users/sip:joe@example.com/index"/> <document new-etag="63hjjsll"
<document new-etag="terteer" sel="tests/users/sip:joe@example.com/index"/>
sel="tests/users/sip:joe@example.com/another_document"/>
</xcap-diff> <document new-etag="terteer"
sel="tests/users/sip:joe@example.com/another_document"/>
</xcap-diff>
Note that the NOTIFY request contains the SIP-ETag "xggfefe54". This Note that the NOTIFY request contains the SIP-ETag "xggfefe54". This
SIP-ETag is placed in the Suppress-If-Match header field of the SIP-ETag is placed in the Suppress-If-Match header field of the
conditional subscription. The "diff-processing" mode also is changed conditional subscription. The "diff-processing" mode also is changed
(or is requested to change): (or is requested to change):
SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0
... ...
Suppress-If-Match: xggfefe54 Suppress-If-Match: xggfefe54
Accept: application/xcap-diff+xml Accept: application/xcap-diff+xml
Event: xcap-diff; diff-processing=aggregate Event: xcap-diff; diff-processing=aggregate
Content-Type: application/resource-lists+xml Content-Type: application/resource-lists+xml
Content-Length: [XXX] Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists">
<list> <list>
<entry uri="tests/users/sip:joe@example.com/"/> <entry uri="tests/users/sip:joe@example.com/"/>
</list> </list>
</resource-lists> </resource-lists>
If the notifier finds a match to the previous stored state when it If the notifier finds a match to the previous stored state when it
evaluates this request, it responds with 204 (No Notification). If evaluates this request, it responds with 204 (No Notification). If
there are no reportable changes as per there are no reportable changes as per
[I-D.ietf-sipcore-subnot-etags], NOTIFY request generation is [I-D.ietf-sipcore-subnot-etags], NOTIFY request generation is
suppressed. When the notifier can aggregate several modifications, suppressed. When the notifier can aggregate several modifications,
this re-subscription enables the processing of that mode thereafter. this re-subscription enables the processing of that mode thereafter.
Indeed, the re-subscription may be quite process-intensive, Indeed, the re-subscription may be quite process-intensive,
especially when there are a large number of relevant reported especially when there are a large number of relevant reported
resources. resources.
 End of changes. 57 change blocks. 
260 lines changed or deleted 287 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/