As described in [3], the NOTIFY message MAY contain a body that
describes the state of the resource. This body is in one of the
formats listed in the Accept header field of the SUBSCRIBE, or in the
package-specific default if the Accept header field is omitted.
Based on the contents of a filter, the following processing occurs:
o A filter with only a <what> element will result in sending the
requested resource state information in that <what> element
whenever there is a change in the resource state.
o A filter with only a <trigger> element will result in sending all
resource state information whenever there is a change in the
resource state that matches the triggers.
o A filter with <what> and <trigger> elements will result in sending
the requested resource state information in that <what> element
whenever there is a change in the resource state that matches the
triggers.
When a filter is disabled (by setting the ’enabled’ attribute to
"false"), it means the same thing as the absence of that filter.
That is, all state and state changes are reported by issuing a
notification to the subscriber (assuming there are no other filters).
When a filter is re-enabled (by setting the ’enabled’ attribute to
"true" or by omitting the ’enabled’ attribute), the notifier behaves
as if the filter has just been placed by the SUBSCRIBE request
enabling it. Immediate NOTIFY rules, as stated in Section 5.3.1,
apply.
5.3.1. Generation of NOTIFY Contents
If the NOTIFY being sent is the one sent immediately after a 2xx
response to the original SUBSCRIBE, its contents MUST be populated
according to the filter <what> element, unless the processing of the
filters will take too long or the NOTIFY request is following a "202"
response to the SUBSCRIBE request and is terminating the
subscription. In the case that the filter is taking too long to
process, the NOTIFY request being sent may be empty or may be
populated with a pre-configured value as authorised to that
subscriber. If applying the filter results in no content to be
delivered, the NOTIFY MUST be sent with empty contents. If the
filter contains <trigger> elements, the notifier ignores the trigger
values when generating the first NOTIFY request.
The input to the content filter is a package-specific XML document
(e.g., [7] and [9]) derived according to the package-specific
specifications, (e.g., [8] and [10]).
The content is filtered according to the expressions in the <what>
element of the filter. The expression indicates the delivered XML
elements and/or attributes. Prefixes of the namespaces of the items
of the XML document to be filtered must be expanded before applying
the filter to the items.
The expression directly states the XML elements and attributes to be
delivered in the NOTIFY, along with their values. In addition to the
selected contents, the namespaces of all the selected items are also
included in the NOTIFY. The XML elements and/or attributes indicated
by the expression in the <what> element must be items that the
subscriber is authorised to see. If they are not, the notifier
policy dictates the behaviour of the notifier (which can ignore the
filter, parts of the filter, or reject the filter completely).
Implementers need to carefully consider such an implementation
decision; the subscriber may not be aware of the authorised contents
and therefore most likely will include a filter requesting
unauthorised contents. It is therefore RECOMMENDED that notifiers
just ignore the parts of the filter that are requesting unauthorised
info (i.e., the filter in the <filter> element where the unauthorised
contents are requested is ignored). If polite blocking is used by
the notifier, the notifier may choose to deliver notifications
containing bogus information in the unauthorised elements or
attributes and applying the filter afterwards.
The resultant XML document MUST be well formed and valid according to
the XML schema. This means that all mandatory elements and
attributes, along with their values, MUST be included in the XML
document regardless of the expression. In other words, if the result
of applying a filter on an XML document is a non-valid XML document,
the notifier MUST add elements and attributes, along with their
values, from the original XML document into the newly formulated one
in order for it to be valid.
5.3.2. Handling of Notification Triggering Rules
There can be several <trigger> elements inside one <filter> element.
If the criteria for any of the <trigger> elements are satisfied, a
NOTIFY SHOULD be generated.
The items (XML elements and/or attributes) indicated by the
expression in the <changed> element, <added> element, or <removed>
element must be items that the subscriber is authorised to access.
If they are not, the notifier policy dictates the behaviour of the
notifier (which can ignore the filter, parts of the filter, or reject
the filter completely).
5.4. Handling Abnormal Cases
In case of an invalid filter definition where the XML document of the
filter is not aligned with the XML schema of the filter format [5],
the notifier rejects the SUBSCRIBE request with a "488" response. A
Warning header field in the response may give a better indication as
to why the filters were not accepted. If the subscription was
accepted with a "202" response but the invalid filter was discovered
after that, a NOTIFY with a subscription-state of value ’terminated’
is sent. An event-reason-value "badfilter", introduced here, of
subexp-params [3] MAY be included.
In case of an erroneous expression in the filter definition, the
notifier either ignores the filter definition or terminates the
subscription.
If a <what> or <trigger> element is empty, the notifier proceeds as
if the element did not exist.
6. XML Document Validation
The subscriber of the filter MUST ensure that the XML document
inserted as the SUBSCRIBE request body is well formed and valid. The
subscriber MUST NOT insert any extension elements or attributes into
the XML document unless it has access to the extension schema and can
validate the XML document. The XML document notifier MAY validate
the XML document according to the schemas, including extension
schemas, to which it has access that are applicable to this XML
document.
7. Examples
The following sections include filtering examples for Presence and
Watcher Information. The format of filter is according to [5].
7.1. Presence Specific Examples
This section describes three use cases where the presence information
filtering solution is utilised [8]. In the first use case, the
watcher is interested in getting messaging-specific information of a
certain presentity. In the second use case, the watcher is
interested in getting information about the communication means and
contact addresses on which the presentity is currently available for
communication. The third case shows how a presentity can request
triggers to receive notifications.
Below is the presentity’s presence information in PIDF [7]. It
includes two tuples: one for the instant messaging and another for
the voice-related information.
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:rpid="urn:ietf:params:xml:ns:pidf:rpid"
entity="sip:presentity@example.com">
<tuple id="432sd">
<status>
<basic>closed</basic>
</status>
<rpid:class>IM</rpid:class>
<contact>im:presentity@example.com</contact>
</tuple>
<tuple id="thr76jk">
<status>
<basic>open</basic>
</status>
<rpid:class>voice</rpid:class>
<contact>tel:2224055555@example.com</contact>
</tuple>
</presence>
7.1.1. Subscriber Requests Messaging-Related Information
The subscriber initiates a subscription to the presentity’s messaging
(MMS, IM, and SMS) related presence information. The subscription
includes the content limiting filter.
The filtered content is indicated with an expression. This
expression selects the <basic> element and all the parent elements
(i.e., the <status>, the <tuple>, and its root element), the <class>
element, and the <contact> element. The filter matches if the
<class> element contains "MMS", "SMS", or "IM".
In this case, the notification includes the contents of the tuple
that has the value "IM" in its <class> element.
SUBSCRIBE request from the subscriber including filter:
SUBSCRIBE sip:presentity@example.com
Via: SIP/2.0/TCP client.example.com:5060;branch=z9hG4bKxjfdsjfk
To: <sip:presentity@example.com>
From: <sip:watcher@example.com>;tag:12341111
Call-ID: 32432udfidfjmk342
Cseq: 1 SUBSCRIBE
Expires: 3600
Event: Presence
Contact: <sip:watcher@client.example.com>
Content-Type: application/simple-filter+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="pidf" urn="urn:ietf:params:xml:ns:pidf"/>
<ns-binding prefix="rpid"
urn="urn:ietf:params:xml:ns:pidf:rpid"/>
</ns-bindings>
<filter id="123" uri="sip:presentity@example.com">
<what>
<include type="xpath">
//pidf:tuple[rpid:class="IM" or rpid:class="SMS"
or rpid:class="MMS"]/pidf:status/pidf:basic
</include>
<include type="xpath">
//pidf:tuple[rpid:class="IM" or rpid:class="SMS"
or rpid:class="MMS"]/rpid:class
</include>
<include type="xpath">
//pidf:tuple[rpid:class="IM" or rpid:class="SMS"
or rpid:class="MMS"]/pidf:contact
</include>
</what>
</filter>
</filter-set>
Notification to the subscriber:
NOTIFY sip:watcher@client.example.com SIP/2.0
Via: SIP/2.0/TCP presence.example.com:5060;branch=z9hG4bKxjfder
To: <sip:watcher@example.com>;tag:12341111
From: <sip:presentity@example.com>;tag:232321
Call-ID: 32432udfidfjmk342
Cseq: 1 NOTIFY
Event: Presence
Subscription-State: active; expires=3599
Contact: sip:presentity@server.example.com
Content-Type: application/pidf+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:rpid="urn:ietf:params:xml:ns:pidf:rpid"
entity="sip:presentity@example.com">
<tuple id="432sd">
<status>
<basic>closed</basic>
</status>
<rpid:class>IM</rpid:class>
<contact>im:presentity@example.com</contact>
</tuple>
</presence>
7.1.2. Subscriber Fetches Information about "Open" Communication Means
The subscriber makes a subscription to the presentity’s available
communication means. The subscription includes the content-limiting
filter.
The filtered content is indicated with an expression. This
expression selects the <basic> element and all the parent elements
(i.e., the <status>, the <tuple>, and its root element), the <class>
element, and the <contact> element. The filter matches if the
<basic> element’s value is "open".
In this case, the notification returns the contents of the tuple that
has the value "open" inside the <status> element.
SUBSCRIBE request from the subscriber including filter:
SUBSCRIBE sip:presentity@example.com SIP/2.0
Via: SIP/2.0/TCP client.example.com:5060;branch=z9hG4bKxjfdsjfk
To: <sip:presentity@example.com>
From: <sip:watcher@example.com>;tag:12341111
Call-ID: 32432udfidfjmk342
Cseq: 1 SUBSCRIBE
Expires: 3600
Event: Presence
Contact: <sip:watcher@client.example.com>
Content-Type: application/simple-filter+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="pidf" urn="urn:ietf:params:xml:ns:pidf"/>
<ns-binding prefix="rpid"
urn="urn:ietf:params:xml:ns:pidf:rpid"/>
</ns-bindings>
<filter id="123" uri="sip:presentity@example.com">
<what>
<include type="xpath">
//pidf:tuple/pidf:status[pidf:basic="open"]/pidf:basic
</include>
<include type="xpath">
//pidf:tuple[pidf:status/pidf:basic="open"]/rpid:class
</include>
<include type="xpath">
//pidf:tuple[pidf:status/pidf:basic="open"]/pidf:contact
</include>
</what>
</filter>
</filter-set>
Notification to the subscriber:
NOTIFY sip:watcher@client.example.com SIP/2.0
Via: SIP/2.0/TCP presence.example.com:5060;branch=z9hG4bKxjfder
To: <sip:watcher@example.com>;tag:12341111
From: <sip:presentity@example.com>;tag:232321
Call-ID: 32432udfidfjmk342
Cseq: 1 NOTIFY
Event: Presence
Subscription-State: active; expires=3599
Contact: sip:presentity@server.example.com
Content-Type: application/pidf+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:rpid="urn:ietf:params:xml:ns:pidf:rpid"
entity="sip:presentity@example.com">
<tuple id="thr76jk">
<status>
<basic>open</basic>
</status>
<rpid:class>voice</rpid:class>
<contact>tel:2224055555@example.com</contact>
</tuple>
</presence>
7.1.3. Subscriber Requests Notifications When Presentity’s Status
Changes
The subscriber subscribes to the presentity, specifying in the filter
that it wants notifications only when the <basic> element has changed
to value "open".
SUBSCRIBE request from the subscriber including filter:
SUBSCRIBE sip:presentity@example.com
Via: SIP/2.0/TCP client.example.com:5060;branch=z9hG4bKxjfdsjfk
To: <sip:presentity@example.com>
From: <sip:watcher@example.com>;tag:12341111
Call-ID: 32432udfidfjmk342
Cseq: 1 SUBSCRIBE
Expires: 3600
Event: Presence
Contact: <sip:watcher@client.example.com>
Content-Type: application/simple-filter+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="pidf" urn="urn:ietf:params:xml:ns:pidf"/>
</ns-bindings>
<filter id="123" uri="sip:presentity@example.com">
<trigger>
<changed from="closed" to="open">
/pidf:presence/pidf:tuple/pidf:status/pidf:basic
</changed>
</trigger>
</filter>
</filter-set>
At some point during the subscription, a second PIDF document is
created with both tuples having a status of "closed":
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:rpid="urn:ietf:params:xml:ns:pidf:rpid"
entity="sip:presentity@example.com">
<tuple id="432sd">
<status>
<basic>closed</basic>
</status>
<rpid:class>IM</rpid:class>
<contact>im:presentity@example.com</contact>
</tuple>
<tuple id="thr76jk">
<status>
<basic>closed</basic>
</status>
<rpid:class>voice</rpid:class>
<contact>tel:2224055555@example.com</contact>
</tuple>
</presence>
A NOTIFY is not sent to the subscriber in this case.
Now, a third PIDF document is created when the IM status changes to
"open":
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:rpid="urn:ietf:params:xml:ns:pidf:rpid"
entity="sip:presentity@example.com">
<tuple id="432sd">
<status>
<basic>open</basic>
</status>
<rpid:class>IM</rpid:class>
<contact>im:presentity@example.com</contact>
</tuple>
<tuple id="thr76jk">
<status>
<basic>closed</basic>
</status>
<rpid:class>voice</rpid:class>
<contact>tel:2224055555@example.com</contact>
</tuple>
</presence>
Notification containing both tuples is sent to the subscriber in this
case:
NOTIFY sip:watcher@client.example.com SIP/2.0
Via: SIP/2.0/TCP presence.example.com:5060;branch=z9hG4bKxjfder
To: <sip:watcher@example.com>;tag:12341111
From: <sip:presentity@example.com>;tag:232321
Call-ID: 32432udfidfjmk342
Cseq: 1 NOTIFY
Event: Presence
Subscription-State: active; expires=3599
Contact: sip:presentity@server.example.com
Content-Type: application/pidf+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:rpid="urn:ietf:params:xml:ns:pidf:rpid"
entity="sip:presentity@example.com">
<tuple id="432sd">
<status>
<basic>closed</basic>
</status>
<rpid:class>IM</rpid:class>
<contact>im:presentity@example.com</contact>
</tuple>
<tuple id="thr76jk">
<status>
<basic>open</basic>
</status>
<rpid:class>voice</rpid:class>
<contact>tel:2224055555@example.com</contact>
</tuple>
</presence>
7.2. Watcher Information Specific Examples
The examples in this section use the winfo template-package with the
presence event package [10].
Watcher information to a Presentity:
<?xml version="1.0"?>
<watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo"
version="0" state="full">
<watcher-list resource="sip:presentity@example.com"
package="presence">
<watcher status="active"
id="sr8fdsj"
duration-subscribed="509"
expiration="20"
event="approved">sip:watcherA@example.com"</watcher>
<watcher status="pending"
id="sr8fdsj"
duration-subscribed="501"
expiration="100"
event="subscribe">sip:watcherB@example.com"</watcher>
<watcher status="terminated"
id="sr8fdsj"
duration-subscribed="500"
expiration="0"
event="rejected">sip:watcherC@example.com"</watcher>
<watcher status="active"
id="sr8fdsj"
duration-subscribed="20"
expiration="30"
event="approved">sip:watcherD@example.com"</watcher>
</watcher-list>
</watcherinfo>
7.2.1. Watcher Subscriber Makes Subscription to Get All the Information
about Active Watchers
SUBSCRIBE request from the presentity including the filter:
SUBSCRIBE sip:presentity@example.com
Via: SIP/2.0/TCP client.example.com:5060;branch=z9hG4bKxjfdsjfk
To: <sip:presentity@example.com>
From: <sip:presentity@example.com>;tag:12341111
Call-ID: 32432udfidfjmk342
Cseq: 1 SUBSCRIBE
Expires: 3600
Event: Presence.winfo
Contact: sip:presentity@client.example.com
Content-Type: application/simple-filter+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="wi"
urn="urn:ietf:params:xml:ns:watcherinfo"/>
</ns-bindings>
<filter id="123" uri="sip:presentity@example.com">
<what>
<include>
/wi:watcherinfo/wi:watcher-list[@package="presence"]/
wi:watcher[@status="active"]
</include>
</what>
</filter>
</filter-set>
Notification to the subscriber:
NOTIFY sip:presentity@client.example.com SIP/2.0
Via: SIP/2.0/TCP presence.example.com:5060;branch=z9hG4bKxjfder
To: sip:presentity@example.com;tag:12341111
From: sip:presentity@example.com;tag:232321
Call-ID: 32432udfidfjmk342
Cseq: 1 NOTIFY
Contact: sip:presentity@server.example.com
Event: Presence.winfo
Content-Type: application/watcherinfo+xml
Content-Length: ...
<?xml version="1.0"?>
<watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo"
version="0" state="full">
<watcher-list resource="sip:presentity@example.com"
package="presence">
<watcher status="active"
id="sr8fdsj"
duration-subscribed="509"
expiration="20"
event="approved">sip:watcherA@example.com"</watcher>
<watcher status="active"
id="sr8fdsj"
duration-subscribed="20"
expiration="30"
event="approved">sip:watcherD@example.com"</watcher>
</watcher-list>
</watcherinfo>
7.2.2. Watcher Subscriber Requests Information of Watchers with
Specific Subscription Duration Conditions
SUBSCRIBE request from the presentity including the filter:
SUBSCRIBE sip:presentity@example.com
Via: SIP/2.0/TCP client.example.com:5060;branch=z9hG4bKxjfdsjfk
To: <sip:presentity@example.com>;tag:12341111
From: <sip:presentity@example.com>
Call-ID: 32432udfidfjmk342
Cseq: 1 SUBSCRIBE
Expires: 0
Event: Presence.winfo
Contact: <sip:presentity@client.example.com>
Content-Type: application/simple-filter+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="wi"
urn="urn:ietf:params:xml:ns:watcherinfo"/>
</ns-bindings>
<filter id="123" uri="sip:presentity@example.com">
<what>
<include>
/wi:watcherinfo/wi:watcher-list[@package="presence"]/
wi:watcher[@duration-subscribed>500]
</include>
</what>
</filter>
</filter-set>
Notification to the subscriber:
NOTIFY sip:presentity@client.example.com SIP/2.0
Via: SIP/2.0/TCP presence.example.com:5060;branch=z9hG4bKxjfder
To: sip:presentity@example.com;tag:12341111
From: sip:presentity@example.com;tag:232321
Call-ID: 32432udfidfjmk342
Cseq: 1 NOTIFY
Contact: sip:presentity@server.example.com
Event: Presence.winfo
Content-Type: application/watcherinfo+xml
Content-Length: ...
<?xml version="1.0"?>
<watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo"
version="0" state="full">
<watcher-list resource="sip:presentity@example.com"
package="presence">
<watcher status="active"
id="sr8fdsj"
duration-subscribed="509"
expiration="20"
event="approved">sip:watcherA@example.com"</watcher>