One document matched: draft-ietf-sip-xcapevent-05.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc compact="yes"?>
<?rfc sortrefs="yes"?>
<?rfc linkmailto="yes"?>
<?rfc strict="no"?>
<?rfc subcompact="no"?>
<?rfc symrefs="yes"?>
<rfc category="std" docName="draft-ietf-sip-xcapevent-05" ipr="pre5378Trust200902">
<front>
<title abbrev="xcap diff event">An Extensible Markup Language (XML)
Configuration Access Protocol (XCAP) Diff Event Package</title>
<author fullname="Jari Urpalainen" initials="J." surname="Urpalainen">
<organization>Nokia</organization>
<address>
<postal>
<street>Itamerenkatu 11-13</street>
<code>00180</code>
<city>Helsinki</city>
<country>Finland</country>
</postal>
<phone>+358 7180 37686</phone>
<email>jari.urpalainen@nokia.com</email>
</address>
</author>
<author fullname="Dean Willis" initials="D. W." surname="Willis" role="editor">
<organization>Softarmor Systems LLC</organization>
<address>
<postal>
<street>3100 Independence Pk #311-164</street>
<code>75075</code>
<city>Plano, TX</city>
<country>USA</country>
</postal>
<phone>+1 214 504 19876</phone>
<email>dean.willis@softarmor.com</email>
</address>
</author>
<date />
<area>RAI</area>
<workgroup>SIP</workgroup>
<abstract>
<t>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.</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>The SIP Events framework <xref target="RFC3265"/> describes
subscription and notification conventions for the Session Initiation
Protocol (SIP) <xref target="RFC3261"/>. The Extensible Markup
Language (XML) <xref target="W3C.REC-xml-20060816" /> Configuration
Access Protocol (XCAP) <xref target="RFC4825"/> allows a client to
read, write and modify XML-formatted application usage data stored on an
XCAP server.</t>
<t>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 <xref target="RFC3265"/> and the XCAP diff
format <xref target="I-D.ietf-simple-xcap-diff"/>, allows a user
to subscribe to changes in an XML document, and to receive notifications
whenever the XML document changes.</t>
<t>There are three basic features that this event package enables:</t>
<t>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.</t>
<t>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 <xref
target="RFC2616" /> to retrieve the updated document. The
second mode includes document content or changes in notification
messages, using the XML-Patch-Ops <xref target="RFC5261" />
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.</t>
<t>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.</t>
</section>
<section anchor="Terminology" title="Terminology">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119, BCP 14 <xref
target="RFC2119" /> and indicate requirement levels for compliant
implementations.</t>
</section>
<section anchor="Definitions" title="Definitions">
<t>The following terms are used in this document:</t>
<t><list style="hanging">
<t hangText="XCAP Component:">An XML element or an attribute, which
can be updated, removed, or retrieved with XCAP.</t>
<!-- ajm: I improved the wording that was provided. It still doesn't make it a definition. The term "aggregating" is only used 3x in this doc (including this section). dwillis: I heavily rewrote the text rewritten by ajm.-->
<t hangText="Aggregating:">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.</t>
</list></t>
<t>This document reuses terminology mostly defined in XCAP <xref
target="RFC4825" /> and some in WebDAV <xref
target="RFC4918" />.</t>
</section>
<section anchor="Package" title="XCAP-Diff Event Package">
<section anchor="Requirements"
title="Overview of Operation With Basic Requirements">
<t>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 <xref target="RFC4918"/>.
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.</t>
<t>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 <xref
target="diff-processing-parameter" /></t>
</section>
<section anchor="event-name" title="Event Package Name">
<t>The name of this event package is "xcap-diff". As specified in
<xref target="RFC3265" />, this value appears in the
Event header field present in SUBSCRIBE and NOTIFY requests.</t>
</section>
<section anchor="diff-processing-parameter"
title="'diff-processing' Event Package Parameter">
<!-- ajm: I removed a normative "MAY be lost in some cases" here since intermediate states aren't even provided for "aggregate" mode, so they are hardly "lost". Clarifying... dwillis: cleaned up a it more.-->
<t>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.<list style="hanging">
<!-- ajm: I moved normative text from above to here: dwillis: added justification for MUST support no-patching,-->
<t>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. </t>
<!-- ajm: I removed Lisa's SHOULD that she had added on notifier actions, and made the default behavior here normative. It was odd that it wasn't normative at all. But should it be SHOULD? Should the ETag change history be normative? dwillis: no, ETag change history should not be normative. It's possible to have a cyclic exclusion; the state went from A to B and back to A while we weren't looking. If so, we don't need to know about B. Also, I moved the default behavior in the absence of a diff-processing parameter back to "no-patching", as that's the fail-safe alternative.-->
<t>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.</t>
<t>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 ( <xref
target="RFC5261" />) diff-generation, because this
can greatly reduce the number of notification operations
required.</t>
<!-- ajm: Lisa added normative SHOULD, dwillis: added justification for Lisa's SHOULD-->
</list> 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.</t>
<t><list style="hanging">
<t>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.</t>
</list></t>
<!-- *** Check cross ref -->
<t>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 <xref
target="notgen" />. During re-subscriptions, the subscriber MAY
change the diff-processing parameter.</t>
<t>The formal grammar <xref target="RFC5234" /> of the
"diff-processing" parameter:</t>
<t><figure>
<artwork>
diff-processing = "diff-processing" EQUAL
"no-patching" /
"xcap-patching" /
"aggregate" /
token
</artwork>
</figure> where EQUAL and token are defined in RFC 3261 <xref
target="RFC3261" />.</t>
</section>
<section anchor="subbody" title="SUBSCRIBE Bodies">
<!-- ajm: Lisa added the MUST -->
<t>The URI list is described by the XCAP resource list format
<xref target="RFC4826" />, 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.</t>
<t>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.</t>
<!-- ajm: I added the following since the notifier SHOULD handle conditional subscriptions. Don't know about the normative strength on this sentence, though: -->
<t>The SUBSCRIBE request MAY contain the Suppress-If-Match header
field <xref target="I-D.ietf-sipcore-subnot-etags" />, which directs
the notifier to suppress either the body of a subsequent notification,
or the entire notification if the ETag value matches.</t>
<!-- ajm: Lisa added the following MUST -->
<t>If the SUBSCRIBE body contains elements or attributes that the
notifier doesn't understand, the notifier MUST ignore them.</t>
<t>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.</t>
<!-- ajm: Lisa added normative text here -->
<t>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.</t>
<!-- ajm: Lisa removed the following note with this comment: LMD I don't see how it's possible for a single notifier to serve multiple XCAP servers unless there are actually several different URLs corresponding to each different XCAP Root. That's because according to the rest of this spec, the client would normally attempt to send relative R-URIs. -->
<!--
<t>
<list style="hanging">
<t>
Note: If the subscriber uses, for example, absolute URIs and the notifier is not able to access them, the notifications will not contain anything about them, similar to a case for example where the user has no read privilege to resources.
</t>
</list>
-->
<figure anchor="Figure" title="Example subscription body">
<preamble><xref target="Figure"></xref> 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".</preamble>
<artwork>
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>
</artwork>
</figure>
</section>
<section anchor="duration" title="Subscription Duration">
<!-- ajm: Why include this if there's not anything different from 3265?-->
<t>The default expiration time for subscriptions within this package
is 3600 seconds. As per RFC 3265 <xref target="RFC3265" />, the
subscriber MAY specify an alternative expiration timer in the Expires
header field.</t>
</section>
<section anchor="notbody" title="NOTIFY Bodies">
<!-- ajm: According to above, it has to be at least "application/xcap-diff+xml", so I removed the 3265 ref.-->
<t>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.</t>
<t>In this event package, notification messages contain an XCAP Diff
document <target="I-D.ietf-simple-xcap-diff" / >.</t>
<!-- ajm: How are collection selections handled? -->
<t>The XCAP Diff format <xref
target="I-D.ietf-simple-xcap-diff"></xref> 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.</t>
</section>
<section anchor="notgen" title="Notifier Generation of NOTIFY Requests">
<!-- ajm: Lisa removed a normative statement here (If the subscribed body contains elements or attributes that it doesn't understand, they MUST be ignored by the notifier.) It's covered in other specs. -->
<t>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.</t>
<t>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.</t>
<t>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.</t>
<!-- ajm: 2nd sentence doesn't make too much sense. I think it's trying to say that you maintain document order while maintaining chronological order for any changes to the components. dwillis: changed "MUST be follolwed" to "MUST be preserved", added justification.
-->
<t>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.</t>
<!-- ajm: Is this the right way to use MAY? dwillis: no, I changed it.-->
<t>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 <xref target="RFC5261" /> 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.,</t>
<!-- LMD Does this mean the client must refresh state by downloading documents? would be good to conclude. dwillis: added discussion thereof.-->
<!-- ajm: Lisa added normative text here. The second sentence is more like "no-patching" -->
<t>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.</t>
<!-- LMD I don't get the last sentence at all dwillis: commited surgery on text.-->
<t>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.</t>
<t><list style="hanging">
<!-- LMD I don't understand this following NOTE. Which XCAP HTTP request? A PUT? Can this be removed? -->
<!-- ajm: I don't think it adds anything to this spec as-is. I don't know if it can be better explained or if it should be removed. I would think that bandwidth is only an issue on mobile networks, otherwise I would think processing would be the main concern.
dwillis: This is suggesting that the XCAP client use patch-ops instead of bulk writes. I have adjusted the text to hopefully make more sense.-->
<t>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.</t>
</list></t>
<t>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.</t>
<!-- ajm: inconsistent normative text? Support of conditional subscriptions is a SHOULD, but the step upon receiving a Suppress-If-Match is a MUST.... dwillis: nope, it's a "must unless".-->
<t>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 <xref
target="I-D.ietf-sipcore-subnot-etags"></xref> 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.</t>
<!-- ajm: What if the subscription was originally set to aggregate and then the subscriber sets it to no-patching? If the immediate NOTIFY provides aggregate info, then it breaks the normative text on the complexity of modes dwillis: the reset to no-patching doesn't go into effect until AFTER The current NOTIFY has been sent, thus no conflict.-->
<t>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.</t>
<t>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 <xref target="RFC5263"></xref>, 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.</t>
<t><list style="hanging">
<!-- ajm: How do dialogs continue after non-resolvable failures? I think it's supposed to say "the dialog will not continue", but I haven't changed it yet. dwillis: yep, changed to "terminate"-->
<t>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.</t>
</list></t>
<!-- LMD This example seems inconsistent with the requirement that failed NOTIFY messages result in removing the subscription. dwillis: it hasn't failed; it has successfully indicated that content has not been conveyed and must be rerieved via another mechanism.-->
<!-- ajm: why doesn't it fall back to the "no-patching" mode if the NOTIFY is too large? dwillis: because no-patching mode can exclude state changes that some clients may need to see.-->
<t>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. </t>
<!-- ajm: Lisa's comments and changes stopped here. -->
</section>
<section anchor="subproc"
title="Subscriber Processing of NOTIFY Requests">
<!-- ajm: I made some assumptions when changing the passive voice in the paragraph below -->
<!-- ajm: According to above, the first NOTIFY contains URI references to all subscribed, existing documents for which the subscriber has read privileges, and typically XCAP component(s) of existing content -->
<t>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.</t>
<!-- ajm: rewrote the paragraph below to get the point right. I think the first sentence should be normative to help reduce sync issues. I've removed variations on the "MAY fail" theme since I don't want to confuse emphasis with normative statements. Changed "the sync algorithm breaks more easily" to "the subscriber may not be able to synchronize its local cache with the first notification" dwillis: made "should" into MAY. There are other approaches that work equally well for preventing synch errors.-->
<t>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.</t>
<t>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.</t>
<!-- ajm: I don't get the last sentence. Why is "no-patching" a last resort for a subscriber? I don't like the term "disable diff-processing" when I think "no-patching mode" is meant. Corrected error on which mode was being discussed (s/xcap-patching/no-patching) based on descriptions. I'm getting the impression that in one of the older versions of this draft, "no-patching" was the default, not "xcap-patching". -->
<t>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".</t>
<t>If a diff format cannot be applied due to patch processing and/or
programming errors (for a list, see Section 5.1 of <xref
target="RFC5261"></xref>), 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.</t>
<!-- ajm: This was originally a very passive paragraph, assuming we're talking about the subscriber here. -->
<t>During unconditional re-subscriptions, the subscriber MUST stamp
the received state of all previous resources as stale. However, if a
conditional <xref target="I-D.ietf-sipcore-subnot-etags"></xref>
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.</t>
</section>
<section anchor="fork" title="Handling of Forked Requests">
<t>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 <xref target="RFC3265"></xref> for handling
non-allowed forked requests.</t>
</section>
<section anchor="notrate" title="Rate of Notifications">
<t>Notifiers of "xcap-diff" event package SHOULD NOT generate
notifications for a single subscription at a rate of more than once
every five seconds.</t>
</section>
<section anchor="agents" title="State Agents">
<t>State agents play no role in this package.</t>
</section>
</section>
<section anchor="Example" title="An Initial Example NOTIFY document">
<!-- ajm: Above it says that a subscriber should use xcap-patching for the first subscription... Why is this example here and not with the other ones? -->
<t><xref target="Figureb"></xref> shows an example initial XCAP Diff
format document provided by the first NOTIFY request to the SUBSCRIBE
example in <xref target="Figure"></xref>. The following is an example
Event header field for this SUBSCRIBE request:</t>
<t>Event: xcap-diff; diff-processing=aggregate</t>
<t>The subscriber requests that the notifier "aggregate" XCAP component
updates and anticipates that the subsequent notifications will contain
aggregated patches to these documents.</t>
<t><vspace blankLines="0" /> <figure anchor="Figureb"
title="An example initial XCAP Diff format document">
<artwork>
<?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>
</artwork>
</figure> 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.</t>
</section>
<section anchor="IANA-Considerations" title="IANA Considerations">
<t>This specification instructs IANA to add a new event package to the
SIP Event Types Namespace registry. The new data to be added is:</t>
<figure>
<artwork>
Package Name Type Contact Reference
------------- -------- ------- ---------
xcap-diff package IETF SIP Working Group [RFCXXXX]
<sip@ietf.org>
</artwork>
</figure>
</section>
<section anchor="Security" title="Security Considerations">
<t>This document defines a new SIP event package for the SIP event
notification framework specified in RFC 3265 <xref
target="RFC3265"></xref>. 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 <xref
target="RFC3261"></xref>. The notifiers MUST be aware of XCAP User
identities (XUI) and how to map the authenticated SIP identities
unambiguously with XUIs.</t>
<t>Since XCAP <xref target="RFC4825"></xref> 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.</t>
<!-- ajm: switched MAY to may, seemed to be more for emphasis than normative dwillis: switche "my" to "can", in order to keep Keith from exploding.-->
<t>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.</t>
<t>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 <xref target="RFC3261"></xref>, SHOULD be used. If
that is not available, it is RECOMMENDED that TLS <xref
target="RFC4346"></xref> 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 <xref target="RFC3261"></xref>.</t>
</section>
<section anchor="Acknowledgments" title="Acknowledgments">
<t>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.</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='reference.RFC.2616'?>
<?rfc include='reference.RFC.3261'?>
<?rfc include='reference.RFC.3265'?>
<!-- <?rfc include='reference.RFC.3688'?> -->
<?rfc include='reference.RFC.5234'?>
<?rfc include='reference.RFC.2119'?>
<?rfc include='reference.RFC.4825'?>
<?rfc include='reference.RFC.4826'?>
<?rfc include='reference.RFC.4346'?>
<?rfc include="reference.RFC.5261"?>
<?rfc include="reference.I-D.ietf-simple-xcap-diff"?>
<?rfc include='reference.I-D.ietf-sipcore-subnot-etags'?>
</references>
<references title="Informative References">
<?rfc include='reference.W3C.REC-xml-20060816'?>
<?rfc include='reference.RFC.4918'?>
<?rfc include='reference.RFC.5263'?>
</references>
<section anchor="appendix" title="Informative Examples">
<t>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.</t>
<section title="Initial documents on an XCAP server">
<t>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).</t>
<t>http://xcap.example.com/tests/users/sip:joe@example.com/index: <!--<vspace blankLines="0"/>-->
<figure>
<artwork>
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<note>This is a sample document</note>
</doc>
</artwork>
</figure></t>
<t>and then</t>
<t>http://xcap.example.com/tests/users/sip:john@example.com/index:
<!--<vspace blankLines="0"/>--> <figure>
<artwork>
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<note>This is another sample document</note>
</doc>
</artwork>
</figure></t>
</section>
<section title="An Initial Subscription">
<t>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: <figure>
<artwork>
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>
</artwork>
</figure></t>
<t>In addition to the 200 (OK) response, the notifier sends the first
NOTIFY: <figure>
<artwork>
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"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<document new-etag="7ahggs"
sel="tests/users/sip:joe@example.com/index"/>
</xcap-diff>
</artwork>
</figure> The subscriber learns that the document on this "tests"
application usage is equivalent to its locally cached version, so it
does not act. If the local version had been different, the subscriber
would most likely re-fetch the document.</t>
<t>If the subscriber had requested the "tests/users/" collection, the
notification body would have been the same since Joe has no read
privilege to John's resources (XCAP default behavior).</t>
<t>If the Expires header field had a value "0", the request would be
similar to the PROPFIND method of WebDAV. The syntax and responses
differ, however.</t>
</section>
<section title="A Document Addition Into a Collection">
<t>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:
<figure>
<artwork>
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>
</artwork>
</figure> This HTTP PUT request results in the XCAP client receiving
a strong HTTP ETag "terteer" for this new document.</t>
<t>Then the subscriber receives a notification afterwards:</t>
<figure>
<artwork>
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"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<document new-etag="terteer"
sel="tests/users/sip:joe@example.com/another_document"/>
</xcap-diff>
</artwork>
</figure>
<t>Note that the result is "additive"; it doesn't indicate the already
indicated "index" document. Only the initial (or refreshed)
notification contains all document URI references.</t>
<t>If Joe's client both modifies the documents and refreshes the
subscriptions, it would typically ignore this notification, since its
modifications had caused the notification. If the client that received
this NOTIFY hadn't submitted the document change, it would probably
fetch this new document.</t>
<t>If Joe's client refreshes the subscription with the same request
body as in the initial subscription, the result will include these two
documents: "index" and "another_document" with their ETags.</t>
</section>
<section title="A Series of XCAP Component Modifications">
<t>Now Joe's client uses its XCAP patching capability by doing the
following: <figure>
<artwork>
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>
</artwork>
</figure> Since the insertion of the element is successful, Joe's
client receives the new HTTP ETag "fgherhryt3" of the updated "index"
document.</t>
<t>Immediately thereafter, Joe's client issues another HTTP request
(this request could even be pipe-lined): <figure>
<artwork>
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>
</artwork>
</figure> The reported new HTTP ETag of "index" is now
"dgdgdfgrrr".</t>
<t>And Joe's client issues yet another HTTP request: <figure>
<artwork>
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>
</artwork>
</figure> The reported new ETag of "index" is now "63hjjsll".</t>
<t>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: <figure>
<artwork>
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>
</artwork>
</figure> 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.</t>
<t>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.</t>
<t>Alternatively, if the notifier's operational mode been
"xcap-patching", the NOTIFY could have been the following: <figure>
<artwork>
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>
</artwork>
</figure> 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.</t>
<!-- ajm: Removed a MAY above, it was more emphasis dwillis" took out a bunch of "must and may".-->
<t>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: <figure>
<artwork>
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"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<document previous-etag="7ahggs3"
sel="tests/users/sip:joe@example.com/index"
new-etag="63hjjsll"/>
</xcap-diff>
</artwork>
</figure> At any time, the notifier may fall back to the
"no-patching" mode for some or all of the subscribed documents.</t>
</section>
<section title="An XCAP Component Subscription">
<t>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. <figure>
<artwork>
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>
</artwork>
</figure></t>
<t>The first NOTIFY looks like the following since there is nothing to
indicate: <figure>
<artwork>
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"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/"/>
</artwork>
</figure> Note that if the "index" document hadn't existed, the
first NOTIFY request would have been the same. The XCAP Diff document
format doesn't indicate reasons for non-existing resources.</t>
<t>Afterwards Joe's client updates the whole document root element
including the attribute "id" (not a typical XCAP operation nor a
preferred one, just an illustration here): <figure>
<artwork>
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>
</artwork>
</figure> The new HTTP ETag of the "index" document is now
"dwawrrtyy".</t>
<t>Then Joe's client gets a notification: <figure>
<artwork>
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"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id"
bar
</attribute>
</xcap-diff>
</artwork>
</figure> Note that the HTTP ETag value of the new document is not
shown as it is irrelevant for this use-case.</t>
<t>Then Joe's client removes the "id" attribute: <figure>
<artwork>
DELETE /tests/users/sip:joe@example.com/index/~~/doc/@id HTTP/1.1
Host: xcap.example.com
....
Content-Length: 0
</artwork>
</figure></t>
<t>And the subscriber gets a notification: <figure>
<artwork>
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"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id"
exists="0"/>
</xcap-diff>
</artwork>
</figure> The notification indicates that the subscribed attribute
was removed from the document. Naturally attributes are "removed" if
the element where they belong is removed, for example by an HTTP
DELETE request. The component selections indicate only the existence
of attributes or elements.</t>
</section>
<section title="A Conditional Subscription">
<t>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: <figure>
<artwork>
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>
</artwork>
</figure></t>
<t>Since there are now two documents in the repository, the first
NOTIFY looks like the following: <figure>
<artwork>
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>
</artwork>
</figure></t>
<t>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): <figure>
<artwork>
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>
</artwork>
</figure> 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 <xref
target="I-D.ietf-sipcore-subnot-etags"></xref>, 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.</t>
</section>
</section>
</back>
</rfc>| PAFTECH AB 2003-2026 | 2026-04-23 10:56:33 |