An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Diff Event Package

An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Diff Event Package Nokia

Itamerenkatu 11-13 00180 Helsinki Finland +358 7180 37686 jari.urpalainen@nokia.com

Softarmor Systems LLC

3100 Independence Pk #311-164 75075 Plano, TX USA +1 214 504 19876 dean.willis@softarmor.com

RAI SIP This document describes an "xcap-diff" SIP (Session Initiation Protocol) event package for the SIP Event Notification Framework, which clients can use to receive notifications of changes to Extensible Markup Language (XML) Configuration Access Protocol (XCAP) resources. The initial synchronization information exchange and document updates are based on the XCAP Diff format.

The SIP Events framework describes subscription and notification conventions for the Session Initiation Protocol (SIP) . The Extensible Markup Language (XML) Configuration Access Protocol (XCAP) allows a client to read, write and modify XML-formatted application usage data stored on an XCAP server. While XCAP allows authorized users or devices to modify the same XML document, XCAP does not provide an effective mechanism (beyond polling) to keep resources synchronized between a server and a client. This memo defines an "xcap-diff" event package that, together with the SIP event notification framework and the XCAP diff format , allows a user to subscribe to changes in an XML document, and to receive notifications whenever the XML document changes. There are three basic features that this event package enables: 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 compare server resources with its local resources using the URLs and the strong entity tag (ETag) values of XCAP documents, which are shown in the XCAP Diff format, and to synchronize them. Second, this event package can signal a change in those resources in one of three ways. The first mode only indicates the event type and does not include document contents, so the subscriber uses HTTP to retrieve the updated document. The second mode includes document content or changes in notification messages, using the XML-Patch-Ops format with minimal notification size. The third mode also includes document content or changes in notification messages, but is more verbose, and shows the full HTTP version-history. Third, the client can subscribe to changes in specific XML element or attribute contents (XCAP components) and receive element or attribute contents in the resulting XCAP Diff format notification messages. If the requested component does not exist but is later created, the notifier sends a notification with the component's content. The notifier also sends notifications when the subscribed XCAP components are removed, for example after a successful HTTP DELETE request.

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 RFC 2119, BCP 14 and indicate requirement levels for compliant implementations.

The following terms are used in this document: An XML element or an attribute, which can be updated, removed, or retrieved with XCAP. An XCAP client can update only a single XCAP Component at a time using HTTP. However, a notifier may be able to aggregate a series of these modifications into a single notification using XML-Patch- Ops semantics encoded in the XCAP-Diff format. This document reuses terminology mostly defined in XCAP and some in WebDAV .

To receive "xcap-diff" event package features, the subscriber indicates its interest in certain resources by including a URI list in the subscription body to the notifier. Each URL in this list MUST be a HTTP URL that identifies a collection, an XCAP document, or an XCAP component. Collection URLs MUST have a trailing forward slash "/", following the conventions of WebDAV . A collection selection includes all documents in that collection and recursively all documents in sub-collections. The URL of an XCAP component consists of the document URL with the XCAP Node Selector added. Although the XCAP Node Selector allows requesting all in-scope namespaces of an element, the client MUST NOT subscribe to namespaces. The notifier MUST support XCAP component subscriptions. The notifier sends the first notification in response to the subscription, and this first notification MUST contain the URLs of the documents and XCAP components that are part of the subscription. The first notification SHOULD contain the contents of subscribed XCAP documents and components. The subsequent notifications MAY contain patches to these documents. The subscriber can specify how the notifier will signal the changes of documents by using the 'diff-processing' event package parameter, covered in the section

The name of this event package is "xcap-diff". As specified in , this value appears in the Event header field present in SUBSCRIBE and NOTIFY requests.

With the aid of the optional "diff-processing" Event header field parameter, the subscriber indicates a preference as to how the notifier SHOULD indicate change notifications of documents. The possible values are "no-patching", "xcap-patching", and "aggregate". All three modes provide information that allows the subscriber to synchronize its local cache, but only the "xcap-patching" mode provides intermediate states of the version history. The notifier SHOULD use the indicated mode if it understands it (as such optimizes network traffic within the capabilities of the receiver), but MAY use "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 document and the event type (creation, modification, and removal) in the notification. The notification does not necessarily indicate the full HTTP ETag change history. Subscribers and notifiers MUST support the "no-patching" mode as a base-line for interoperability. The other, more complex modes are optional. The "xcap-patching" value means that the notifier includes all updated XCAP component contents and entity tag (ETag) changes. The client receives the full (HTTP) ETag change history of a document. This is equivalent to sending individual notifications for each change. The "aggregate" value means that the notifier MAY aggregate several individual XCAP component updates into a single XCAP Diff <document> element. The policy for determining whether or not to apply aggregation or to determine how many updates to aggregate is locally determined. The notifier SHOULD support the "aggregate" mode and implement XML-Patch-Ops ( ) diff-generation, because this can greatly reduce the number of notification operations required. If the subscription does not contain the "diff-processing" header field parameter, the notifier SHOULD default to the "no-patching" 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 "aggregate" modes, consider a document that has versions "a", "b" and "c" with corresponding ETag values "1", "2" and "3". The "xcap-patching" mode will include first the change from version "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" ETags. The "aggregate" mode optimizes the change and indicates 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, the same element has been updated many times, the bandwidth savings are larger. This "diff-processing" parameter is a subscriber hint to the notifier. The notifier may respond using a simpler mode, but not a more complex one. Notifier selection of a mode is covered in . During re-subscriptions, the subscriber MAY change the diff-processing parameter. The formal grammar of the "diff-processing" parameter:

diff-processing = "diff-processing" EQUAL "no-patching" / "xcap-patching" / "aggregate" / token where EQUAL and token are defined in RFC 3261 .

The URI list is described by the XCAP resource list format , and is included as a body of the initial SUBSCRIBE request. Only a simple subset of that format is required, a flat list of XCAP R-URIs. The "uri" attribute of the <entry> element contains these URI values. The subscriber MUST NOT use hierarchical lists or <entry-ref> references, etc., (though in the future, semantics may be expanded thanks to the functionality in the resource list format). In subsequent SUBSCRIBE requests, such as those used for refreshing the expiration timer, the subscribed URI list MAY change, in which case the notifier MUST use the new list. The SUBSCRIBE request MAY contain an Accept header field. If no such header field is present, it has a default value of "application/xcap-diff+xml". If the header field is present, it MUST include "application/xcap-diff+xml", and MAY include any other types. The SUBSCRIBE request MAY contain the Suppress-If-Match header field , which directs the notifier to suppress either the body of a subsequent notification, or the entire notification if the ETag value matches. If the SUBSCRIBE body contains elements or attributes that the notifier doesn't understand, the notifier MUST ignore them. Subscribers need to appropriately populate the Request-URI of the SUBSCRIBE request, typically set to the URI of the notifier. This document does not constrain that URI. It is assumed that the subscriber is provisioned with or has learned the URI of the notifier of this event package. The XCAP server will usually be co-located with the SIP notifier, so the subscriber MAY use relative XCAP Request-URIs. Because relative Request-URIs are allowed, the notifier MUST know how to resolve these against the correct XCAP Root URI value.

shows a SUBSCRIBE request and body covering several XCAP resources: a "resource-list" document, a specific element in a "rls-services" document, and a collection in "pidf-manipulation" application usage. The "Content-Type" header of this SUBSCRIBE request is "application/resource-lists+xml". SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 ... Accept: application/xcap-diff+xml Event: xcap-diff; diff-processing=aggregate Content-Type: application/resource-lists+xml Content-Length: [XXX] Expires: 4200 <?xml version="1.0" encoding="UTF-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <list> <entry uri="resource-lists/users/sip:joe@example.com/index"/> <entry uri="rls-services/users/sip:joe@example.com/index/ ~~/*/service%5b@uri='sip:marketing@example.com'%5d"/> <entry uri="pidf-manipulation/"/> </list> </resource-lists>

The default expiration time for subscriptions within this package is 3600 seconds. As per RFC 3265 , the subscriber MAY specify an alternative expiration timer in the Expires header field.

The format of the NOTIFY message body is either the default of "application/xcap-diff+xml" or is a format listed in the Accept header field of the SUBSCRIBE. In this event package, notification messages contain an XCAP Diff document . The XCAP Diff format can include the full element and attribute content of XCAP documents and components. For documents, the format can also include corresponding URIs, ETag values, and patching instructions from version "a" to "b". Removal events (of documents, elements, or attributes) can be identified too. Except for collection selections, the "sel" selector values of the XCAP-Diff format MUST be octet-by-octet equivalent to the relevant "uri" parameter values of the <entry> element of the "resource-list" document.

During the initial subscription, or if the URI list changes in SUBSCRIBE refresh requests, the notifier MUST resolve the requested XCAP resources and their privileges. If there are superfluous resource selections in the requested URI list, the notifier SHOULD NOT provide overlapping similar responses for these resources. A resource for which an authenticated user does not have a read 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 produce an error. Instead, the request remains in a "pending" state, that is, waiting for this resource to be created (or read access granted). Subscriptions to collections have a similar property: once a 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 generates the first NOTIFY, which contains URI references to all subscribed, existing documents for which the subscriber has read privileges, and typically XCAP component(s) of existing content. After sending the initial notification, the notifier selects a diff-processing mode for reporting changes. If the subscriber suggested a mode in the "diff-processing" parameter of the SUBSCRIBE, the notifier MAY use that requested mode or MAY fall back to a simpler operational mode, but the notifier MUST NOT use a more complex mode than the one chosen by the subscriber. From least to most complex, the order of the modes is the following: "no-patching", "xcap-patching", "aggregate". Thus, the notifier may respond to an "aggregate" request using any mode, but cannot reply to an "xcap-patching" subscription using the "aggregate" mode. Naturally, the notifier MUST handle a "no-patching" request with the "no-patching" mode. In all modes, the notifier MUST maintain the chronological order of XCAP changes. If several changes to a given resource are presented in a single notification, the chronological update order MUST be preserved in the XML document order of the notification body. Preservation of chronological order is required to produce a correct document in the subscriber. If content modifications are made out-of-order, an erroneous document would probably be formed. While the "aggregate" mode uses bandwidth most efficiently, it introduces other challenges. The initial synchronization might fail with rapidly changing resources, because the "aggregate" mode messages might not include the full version-history of a document and the base XCAP protocol does not support version-history retrievals of documents. When new documents are created in subscribed collections and the notifier is aggregating patches, the same issue can occur. In a corner case, the notifier may not be able to provide patches with the XML-Patch-Ops semantics. Therefore, if the notifier has to temporarily disable diff generation and send 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-patching" mode. Recovery from this error condition therefore means that the subscriber must refresh to a "known good" state by downloading the current document if it has lost track of the patching operations as indicated by mismatching ETags., In the "aggregate" mode, the notifier chooses how long to wait for multiple patches to combine. Even with rapidly changing resources 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-generation temporarily for certain resources, for example when the NOTIFY body becomes impractically large or an intermediate error has happened. Some XCAP clients will probably not have completely optimized their patchrequest, 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 producd by the XCAP client. Note: It is straightforward to change the XCAP client's change requests (sent via HTTP) to use XML-Patch-Ops semantics. While XCAP does not support patching of all XML node types - for example, namespace declarations can not be added separately - utilization of XML-Patch-Ops can sometimes significantly reduce the bandwidth requirements at the expense of extra processing. Extension of XCAP for this utilization of patch-ops is outside the 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, it MUST also report its removal consistently. For example, the removal of the parent element of the subscribed element requires the same signalling since the subscribed element ceases to exist. To signal the removal of an XCAP component, the notifier sets the Boolean "exist" attribute value of the <element> or <attribute> elements to false. When the notifier receives a re-subscription, it MUST re-send the current full XML-Diff content unless the subscriber has requested a conditional subscription by using the header field Suppress-If-Match: [ETag value]. With a conditional re-subscription, the notifier MUST also inspect the subscription body when determining the current subscription state. Since the 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 determining the equivalence to "stored" previous states. If a match to the previous state is not found, the NOTIFY message MUST contain the full XML-Diff state (similar to the initial notification). The notifiers SHOULD implement the conditional subscription handling with this event package. During re-subscriptions, the subscriber may change the value of the diff-processing parameter. The value change influences only subsequent notifications, not the notification (if generated) followed immediately after the (re-)SUBSCRIBE request. Event packages like this require reliable transfer of NOTIFY messages. This means that all messages MUST successfully be transferred or the document will become out of synch, and then patches will most likely fail (or worse, have unintended consequences). This "xcap-diff" event package requires, similar to Partial-PIDF-Notify RFC 5263 , that a notifier MUST NOT send a new NOTIFY request to the same dialog unless a successful 200-response has been received for the last sent NOTIFY request. If the NOTIFY request fails due to a timeout, the notifier MUST remove the subscription. Note: This requirement ensures that out-of-order events will not happen or that the dialog will terminate after non-resolvable NOTIFY request failures. In addition, some of the probable NOTIFY error responses (for example, 401, 407, 413) can possibly be handled gracefully without tearing down the dialog. If, for example, the subscriber has selected too many elements to which to subscribe, such that the notification body would be impractically large (that is, an intermediate NOTIFY failure), the notifier MAY discard the <element> element content. The existence of elements is then indicated with an empty <element> element, and the content is not shown for those resources. In other words, the <element> element does not not have a child element which would show the subscribed "full" element content.

The first NOTIFY request will usually contain references to HTTP resources including their strong ETag values. If the subscriber does not have similar locally cached versions, it will typically start an unconditional HTTP GET request for those resources. During this HTTP retrieval time, the subscriber MAY also receive patches to these documents (if it has requested them) if the documents are changing. A subscriber can chain the modification list for the document and aggregate the changes itself if the notifications contain patches and indicate all atomic XCAP modifications with both previous and new ETags of each resource ("xcap-patching" mode). If the version received via HTTP is newer than any received via the notifications, the subscriber may not find an equivalent match of an ETag value from the chain of patches. This can happen since notifications are reported after HTTP changes and preferably at some minimum intervals. In such a case, the subscriber SHOULD either wait for subsequent notifications or refresh the subscription and repeat the described "sync" algorithm until a match is achieved. To avoid out-of-sync issues, the subscriber MAY start the subscription with the "xcap-patching" mode, and then refresh the subscription with the "aggregate" mode. Syncs are successful if the received HTTP ETag matches with either the previous or new ETag of the reported aggregated patch. If the subscription is started with the "aggregate" mode, which doesn't necessarily show the full version-history information, the subscriber may not be able to synchronize its local cache with the first notification. The subscriber MAY resolve this issue by doing one of the following: re-fetching the out-of-sync document, waiting for subsequent notifications, or by refreshing the subscription. However, the same issue may still repeat. 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 while others are in the "aggregate" mode, it SHOULD refresh the subscription to the "aggregate" mode. The notifier MAY at any time temporarily use the "no-patching" mode for some resources so that the subscriber receives only URI references of modifications. When the notifier is acting in this mode, several cycles MAY be needed before an initial "full" sync is achieved. As the notifier MAY change modes in the middle of a dialog, the subscriber is always responsible for taking appropriate actions. Also, as the last resort, the subscriber MAY always disable the usage of diff-processing by setting the "diff-processing" parameter to "no-patching". If a diff format cannot be applied due to patch processing and/or programming errors (for a list, see Section 5.1 of ), the subscriber SHOULD refresh the subscription and disable patching by setting the "diff-processing" parameter to "no-patching". The subscriber SHOULD NOT reply with a non-200 response since the notifier cannot make corrections. During unconditional re-subscriptions, the subscriber MUST stamp the received state of all previous resources as stale. However, if a conditional re-subscription is successful, the subscriber MUST preserve the current state of resources unless the subscribed URI list has changed. That is, the subscriber MUST fetch the resource's state, for example, from some local cache.

This specification allows only a single dialog to be constructed from an initial SUBSCRIBE request. If the subscriber receives forked responses to a SUBSCRIBE, the subscriber MUST apply the procedures in Section 4.4.9 of RFC 3265 for handling non-allowed forked requests.

Notifiers of "xcap-diff" event package SHOULD NOT generate notifications for a single subscription at a rate of more than once every five seconds.

State agents play no role in this package.

shows an example initial XCAP Diff format document provided by the first NOTIFY request to the SUBSCRIBE example in . The following is an example Event header field for this SUBSCRIBE request: Event: xcap-diff; diff-processing=aggregate The subscriber requests that the notifier "aggregate" XCAP component updates and anticipates that the subsequent notifications will contain aggregated patches to these documents.

<?xml version="1.0" encoding="UTF-8"?> <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" xcap-root="http://xcap.example.com/root/"> <document new-etag="7ahggs" sel="resource-lists/users/sip:joe@example.com/index"/> <document new-etag="30376adf" sel="pidf-manipulation/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" xmlns:d="urn:ietf:params:xml:ns:xcap-diff" xmlns="urn:ietf:params:xml:ns:rls-services" xmlns:rl="urn:ietf:params:xml:ns:resource-lists" <service uri="sip:marketing@example.com"> <list name="marketing"> <rl:entry uri="sip:joe@example.com"/> <rl:entry uri="sip:sudhir@example.com"/> </list> <packages> <package>presence</package> </packages> </service> </d:element> </xcap-diff> Note that the resource-list "index" document included only the new ETag value, as the document existed during the subscription time. In the "pidf-manipulation" collection, there is only a single document for which the user has read privilege. The <services> element exists within the rls-services "index" document and its content is shown.

This specification instructs IANA to add a new event package to the SIP Event Types Namespace registry. The new data to be added is:

Package Name Type Contact Reference ------------- -------- ------- --------- xcap-diff package IETF SIP Working Group [RFCXXXX] <sip@ietf.org>

This document defines a new SIP event package for the SIP event notification framework specified in RFC 3265 . As such, all the security considerations of RFC 3265 apply. The configuration data can contain sensitive information, and both the client and the server need to authenticate each other. The notifiers MUST authenticate the "xcap-diff" event package subscriber using the normal SIP authentication mechanisms, for example Digest as defined in Section 22 of RFC 3261 . The notifiers MUST be aware of XCAP User identities (XUI) and how to map the authenticated SIP identities unambiguously with XUIs. Since XCAP provides a basic authorization policy for resources and since notifications contain content similar to XCAP resources, the security considerations of XCAP also apply. The notifiers MUST obey the XCAP authorization rules when signalling resource changes. In practice, this means following the read privilege rules of XCAP resources. Denial-of-Service attacks against notifiers deserve special mention. The following can cause denial of service due to intensive processing: subscriptions to a long list of URIs, "pending" subscriptions to non-existent documents or XCAP components, and diff-generation algorithms that try to optimize the required bandwidth usage to extremes. The mechanism used for conveying xcap-diff event information MUST ensure integrity and SHOULD ensure confidentially of the information. An end-to-end SIP encryption mechanism, such as S/MIME described in Section 26.2.4 of RFC 3261 , SHOULD be used. If that is not available, it is RECOMMENDED that TLS be used between elements to provide hop-by-hop authentication and encryption mechanisms described in Section 26.2.2 "SIPS URI Scheme" and Section 26.3.2.2 "Interdomain Requests" of RFC 3261 .

The author would like to thank Jonathan Rosenberg for his valuable comments and providing the initial event package, and Aki Niemi, Pekka Pessi, Miguel Garcia, Pavel Dostal, Krisztian Kiss, Anders Lindgren, Sofie Lassborn, Keith Drage, Stephen Hinton, Byron Campen, Avshalom Houri, Ben Campbell, Paul Kyzivat, Spencer Dawkins, Pasi Eronen and Chris Newman for their valuable comments. Lisa Dusseault critiqued the document during IESG review, raising numerous issues that resulted in improved document quality. Further, technical writer A. Jean Mahoney devoted countless hours to integrating Lisa's comments and cleaning up the technical English usage.

These examples illustrate the basic features of the xcap-diff event package. Only the relevant header fields are shown. Note also that the SIP R-URIs of these examples don't correspond to reality.

The following documents exist on an XCAP server (xcap.example.com) with an imaginary "tests" application usage (there's no default document namespace defined in this imaginary application usage). http://xcap.example.com/tests/users/sip:joe@example.com/index:

<?xml version="1.0" encoding="UTF-8"?> <doc> <note>This is a sample document</note> </doc> and then http://xcap.example.com/tests/users/sip:john@example.com/index:

<?xml version="1.0" encoding="UTF-8"?> <doc> <note>This is another sample document</note> </doc>

The following demonstrates the listing of a collection contents and it shows only resources where the user has read privilege. The user Joe, whose XUI is "sip:joe@example.com", sends an initial subscription:

SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 ... Accept: application/xcap-diff+xml Event: xcap-diff; diff-processing=aggregate Content-Type: application/resource-lists+xml Content-Length: [XXX] <?xml version="1.0" encoding="UTF-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <list> <entry uri="tests/users/sip:joe@example.com/"/> </list> </resource-lists> In addition to the 200 (OK) response, the notifier sends the first NOTIFY:

Let's say that Joe adds a new document to his collection, using either the same client or another client running on a different device. He does an HTTP PUT to his application usage collection:

PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1 Host: xcap.example.com .... Content-Type: application/xml Content-Length: [XXX] <?xml version="1.0" encoding="UTF-8"?> <doc> <note>This is another sample document</note> </doc> This HTTP PUT request results in the XCAP client receiving a strong HTTP ETag "terteer" for this new document. Then the subscriber receives a notification afterwards:

Now Joe's client uses its XCAP patching capability by doing the following:

PUT /tests/users/sip:joe@example.com/index/~~/doc/foo HTTP/1.1 Host: xcap.example.com .... Content-Type: application/xcap-el+xml Content-Length: [XXX] <foo>this is a new element</foo> Since the insertion of the element is successful, Joe's client receives the new HTTP ETag "fgherhryt3" of the updated "index" document. Immediately thereafter, Joe's client issues another HTTP request (this request could even be pipe-lined):

PUT /tests/users/sip:joe@example.com/index/~~/doc/bar HTTP/1.1 Host: xcap.example.com .... Content-Type: application/xcap-el+xml Content-Length: [XXX] <bar>this is a bar element </bar> The reported new HTTP ETag of "index" is now "dgdgdfgrrr". And Joe's client issues yet another HTTP request:

PUT /tests/users/sip:joe@example.com/index/~~/doc/foobar HTTP/1.1 Host: xcap.example.com .... Content-Type: application/xcap-el+xml Content-Length: [XXX] <foobar>this is a foobar element</foobar> The reported new ETag of "index" is now "63hjjsll". After awhile, Joe's client receives a notification with an embedded patch since it has requested "aggregate" diff-processing and the notifier is capable of producing them:

NOTIFY sip:joe@userhost.example.com SIP/2.0 ... Event: xcap-diff Content-Type: application/xcap-diff+xml Content-Length: [XXX] <?xml version="1.0" encoding="UTF-8"?> <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff" xcap-root="http://xcap.example.com/"> <d:document previous-etag="7ahggs3" sel="tests/users/sip:joe@example.com/index" new-etag="63hjjsll"> <d:add sel="*" <foo>this is a new element</foo> <bar>this is a bar element </bar> <foobar>this is a foobar element</foobar> </d:add> </d:document> </d:xcap-diff> Joe's client applies this patch to the locally cached "index" document, detects the ETag update, and stores the last ETag value. Note how several XCAP component modifications were aggregated. 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 request after the initial notification. If the ETag of the received 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 issue is not typical, but it can happen. To resolve the issue, the client could re-fetch the "index" document and/or wait for subsequent notifications to detect a match. A better and simpler way to avoid the issue is to refresh the subscription with the "xcap-patching" mode and later refresh with the "aggregate" mode. Alternatively, if the notifier's operational mode been "xcap-patching", the NOTIFY could have been the following:

NOTIFY sip:joe@userhost.example.com SIP/2.0 ... Event: xcap-diff Content-Type: application/xcap-diff+xml Content-Length: [XXX] <?xml version="1.0" encoding="UTF-8"?> <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff" xcap-root="http://xcap.example.com/"> <d:document previous-etag="7ahggs" sel="tests/users/sip:joe@example.com/index" new-etag="fgherhryt3"> <d:add sel="*" <foo>this is a new element</foo> </d:add> </d:document> <d:document previous-etag="fgherhryt3" sel="tests/users/sip:joe@example.com/index" new-etag="dgdgdfgrrr"> <d:add sel="*" <bar>this is a bar element </bar> </d:add> </d:document> <d:document previous-etag="dgdgdfgrrr" sel="tests/users/sip:joe@example.com/index" new-etag="63hjjsll"> <d:add sel="*" <foobar>this is a foobar element</foobar> </d:add> </d:document> </d:xcap-diff> If the client had to re-fetch the "index" document after the initial notification, it could have skipped some or all of these patches, 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 HTTP version is a newer version indicated in later notification(s) then the sync may then be achieved since the notifier provided the full change history in the "xcap-patching" mode. Lastly, the notifier could (temporarily) fall back to the "no-patching" mode, which allows the notifier to keep the dialog alive when there are too many updates:

The user Joe sends an initial subscription for the "id" affribute of a <doc> element. The "index" document exists, but the <doc> root element does not contain the "id" attribute at the time of the subscription.

SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 ... Accept: application/xcap-diff+xml Event: xcap-diff Content-Type: application/resource-lists+xml Content-Length: [XXX] <?xml version="1.0" encoding="UTF-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <list> <entry uri="tests/users/sip:joe@example.com/index/~~/doc/@id"/> </list> </resource-lists> The first NOTIFY looks like the following since there is nothing to indicate:

PUT /tests/users/sip:joe@example.com/index/~~/doc HTTP/1.1 Host: xcap.example.com .... Content-Type: application/xcap-el+xml Content-Length: [XXX] <doc id="bar">This is a new root element</doc> The new HTTP ETag of the "index" document is now "dwawrrtyy". Then Joe's client gets a notification:

DELETE /tests/users/sip:joe@example.com/index/~~/doc/@id HTTP/1.1 Host: xcap.example.com .... Content-Length: 0 And the subscriber gets a notification:

The last example is a conditional subscription where a full refresh can be avoided when there are no changes in resources. Joe's client sends an initial subscription:

SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 ... Accept: application/xcap-diff+xml Event: xcap-diff; diff-processing=xcap-patching Content-Type: application/resource-lists+xml Content-Length: [XXX] <?xml version="1.0" encoding="UTF-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <list> <entry uri="tests/users/sip:joe@example.com/"/> </list> </resource-lists> Since there are now two documents in the repository, the first NOTIFY looks like the following:

NOTIFY sip:joe@userhost.example.com SIP/2.0 ... Event: xcap-diff SIP-ETag: xggfefe54 Content-Type: application/xcap-diff+xml Content-Length: [XXX] <?xml version="1.0" encoding="UTF-8"?> <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" xcap-root="http://xcap.example.com/"> <document new-etag="63hjjsll" sel="tests/users/sip:joe@example.com/index"/> <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 SIP-ETag is placed in the Suppress-If-Match header field of the conditional subscription. The "diff-processing" mode also is changed (or is requested to change):

SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 ... Suppress-If-Match: xggfefe54 Accept: application/xcap-diff+xml Event: xcap-diff; diff-processing=aggregate Content-Type: application/resource-lists+xml Content-Length: [XXX] <?xml version="1.0" encoding="UTF-8"?> <resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists"> <list> <entry uri="tests/users/sip:joe@example.com/"/> </list> </resource-lists> If the notifier finds a match to the previous stored state when it evaluates this request, it responds with 204 (No Notification). If there are no reportable changes as per , NOTIFY request generation is suppressed. When the notifier can aggregate several modifications, this re-subscription enables the processing of that mode thereafter. Indeed, the re-subscription may be quite process-intensive, especially when there are a large number of relevant reported resources.