step, the filter applies to all the elements that are evaluated.
That is, if a filter including an element evaluates to 2 elements,
both elements are included as a result.
selection = reference [expression]
expression = "[" (elem-expr / attr-expr)
1*[oper (elem-expr / attr-expr)] "]"
elem-expr = (elem-path / "." / "..") compar value
elem-path = (element / "*") 1*["/" / "*" / element] ["*" / element]
attr-expr = [elem-path "/"] attribute compar value
reference = elem-reference / attr-reference
elem-reference = "/" 1*("/" / "/*" / ("/" element))
attr-reference = reference attribute
oper = "and" / "or"
compar = "=" / "<" / ">"
element = [ns] string
attribute = "@" [ns] string
ns = string ":"
string = <any sequence of data supported by XML in names of XML
element, and/or attribute or prefixes of namespaces>
value = <any sequence of data supported by XML as a value of the
XML element and/or attribute>
When identifying XML elements or attributes, the value may consist of
two parts: the XML element/attribute selector and the condition
(comparison and logical expressions). The XML element selector
appears first followed by the condition part in square brackets. In
the XML element selector part, the XML elements may be referenced by
giving the full hierarchical path as: "/presence/tuple/status/basic",
by denoting the selection to cover any hierarchical level by its name
as: "//tuple/status/basic", or using the wildcard "*", denoting any
value in a certain level as "/*/watcher".
Example references are listed as follows:
o Selecting an element by using an XML element as a condition:
* //*[status/basic="open"]
* /presence/tuple[*/basic="open"]
o Selecting an element by using XML attributes as a condition:
* //watcher[@duration-subscribed<500]
* /*/watcher[@event="rejected"]
o Selecting an element by using two XML elements as a condition:
* //tuple[status/basic="open" and type="device"]
o Selecting an attribute:
* //watcher/@duration-subscribed
In some cases, due to the design of the XML schema, the XPATH-like
expression results in identification of more than one element with
the same name (the XPATH expression may not have uniquely identified
an element at every step). In those cases, all elements identified
are selected.
When evaluating XPATH location steps, namespace expansion follows
XPATH 1.0 [9] semantics, i.e., if the QName does not have a prefix,
then the namespace URI in the expanded name is null. With
non-default namespaces, expansion is done according to the given
<ns-bindings> definitions. When a default namespace is used in the
document, the <ns-binding> element SHOULD be used to define an equal
URI with some prefix in order to have a valid XPATH evaluation in
location steps.
6. Examples
The XML Schema for the XML document examples is specified in
Section 7.
6.1. Filter Criteria Using <what> Element
A user wishes to get to know his friend’s availability and
willingness for messaging (SMS, IM, and MMS) in order to know whether
the friend is able to receive a message, the address to contact, and
the type of the message to be used.
This example shows how to define a content filter. The <basic>
element as well as all parent elements are selected based on a
condition defined by a logical expression. The condition is <class>
elements that have a value "MMS", "SMS", or "IM".
The <class> element is defined in [14] as an extension to PIDF [13].
<?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:presence/pidf:tuple[rpid:class="IM" or rpid:class="SMS"
or rpid:class="MMS"]/pidf:status/pidf:basic
</include>
</what>
</filter>
</filter-set>
6.2. Filter Criteria Using <trigger> Element
A user requires to be informed when his colleague becomes available
by some communication means. The user gets the full presence state
of the colleague when a certain PIDF [13] tuple <basic> status
changes from "closed" to "open".
<?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>
6.3. Filter Criteria Using <what> and <trigger> Elements
A user wishes to get information about pending and waiting
subscriptions in order to be able to authorise watchers to see his
presence information.
The filter selects watcher information notifications [16] to be sent
when a subscription status has changed to "pending" or "waiting". In
the notification, only the watchers that have a status of "pending"
or "waiting" are included.
<?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/wi:watcher[@status="pending"
or @status="waiting"]
</include>
</what>
<trigger>
<changed to="pending">
/wi:watcherinfo/wi:watcher-list/wi:watcher/@status
</changed>
</trigger>
<trigger>
<changed to="waiting">
/wi:watcherinfo/wi:watcher-list/wi:watcher/@status
</changed>
</trigger>
</filter>
</filter-set>
6.4. Content Filter Using Namespaces
A user turns her terminal on, and the terminal automatically fetches
general presence status and information about communication means
from a certain pre-defined set of her buddies.
The filter is defined to select XML elements belonging to the PIDF
namespace.
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<filter id="123" uri="sip:buddylist@example.com">
<what>
<include type="namespace">
urn:ietf:params:xml:ns:pidf
</include>
</what>
</filter>
</filter-set>
6.5. Content Filter Using Only <include> Elements
A user wants to know if a group of his friends is available for
gaming. He orders notifications about the current status and future
changes of the game-specific presence information.
This filter is defined to select the game-specific tuple to be
delivered.
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter" >
<ns-bindings>
<ns-binding prefix="game-ext"
urn="urn:ietf:params:xml:ns:game-ext"/>
</ns-bindings>
<filter id="123">
<what>
<include>
/pidf:presence/pidf:tuple/
pidf:status[game-ext:label="game-X"]
</include>
</what>
</filter>
</filter-set>
6.6. Two Content Filters as Filter Criteria
The user is interested in getting up-to-date information about the
communication means and contact addresses of his friends. The user
also wants to get more information (e.g., location) about one of the
friends in the list, named Bob. The PIDF element <note> is filtered
out, i.e., excluded. The list was predefined as buddies@example.com.
<?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="8439" uri="sip:buddies@example.com">
<what>
<include>
/pidf:presence/pidf:tuple[rpid:class="service"]/pidf:status/
pidf:basic
</include>
</what>
</filter>
<filter id="999" uri="sip:bob@example.com">
<what>
<include type="namespace">
urn:ietf:params:xml:ns:pidf
</include>
<exclude>
/pidf:presence/pidf:tuple/pidf:note
</exclude>
</what>
</filter>
</filter-set>
7. XML Schema for Filter Criteria
XML Schema Implementation (Normative)
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:simple-filter"
xmlns="urn:ietf:params:xml:ns:simple-filter"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<xs:annotation>
<xs:documentation xml:lang="en">
XML Schema Definition for Filter Criteria.
</xs:documentation>
</xs:annotation>
<xs:element name="filter-set" type="FilterSetType"/>
<xs:complexType name="FilterSetType">
<xs:sequence>
<xs:element name="ns-bindings" type="NSBindings"
minOccurs="0" maxOccurs="1"/>
<xs:element name="filter" type="FilterType"
minOccurs="1"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="package" type="xs:string" use="optional"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:complexType>
<xs:complexType name="NSBindings">
<xs:sequence>
<xs:element name="ns-binding" type="NSBinding"
minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="NSBinding">
<xs:attribute name="prefix" type="xs:string" use="required"/>
<xs:attribute name="urn" type="xs:anyURI" use="required"/>
</xs:complexType>
<xs:complexType name="FilterType">
<xs:sequence>
<xs:element name="what" type="WhatType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="trigger" type="TriggerType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="uri" type="xs:anyURI" use="optional"/>
<xs:attribute name="domain" type="xs:string" use="optional"/>
<xs:attribute name="remove" type="xs:boolean" use="optional"
default="false"/>
<xs:attribute name="enabled" type="xs:boolean" use="optional"
default="true"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:complexType>
<xs:complexType name="WhatType">
<xs:sequence>
<xs:element name="include" type="InclType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="exclude" type="ExclType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="InclType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="type" type="TypeType"
default="xpath" use="optional"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="ExclType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="type" type="TypeType"
default="xpath" use="optional"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:simpleType name="TypeType">
<xs:restriction base="xs:string">
<xs:enumeration value="xpath"/>
<xs:enumeration value="namespace"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="TriggerType">
<xs:sequence>
<xs:element name="changed" type="ChangedType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="added" type="xs:string"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="removed" type="xs:string"
minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ChangedType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="from" type="xs:anySimpleType"
use="optional"/>
<xs:attribute name="to" type="xs:anySimpleType"
use="optional"/>
<xs:attribute name="by" type="xs:decimal"
use="optional"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
8. Security Considerations
The filters in the body in a SIP message have a significant effect on
the ways in which the request is handled at a server. As a result,
it is especially important that messages containing this extension be
authenticated and authorised. Authentication can be achieved using
the Digest Authentication mechanism described in [12]. The
authorisation decision is based on the permissions that the resource
(notifier) has given to the watcher. An example of such an
auhorisation policy can be found in [18].
Requests can reveal sensitive information about a UA’s capabilities.
If this information is sensitive, it SHOULD be encrypted using SIP
S/MIME capabilities [11].
All filtering-related security measures discussed in [2] MUST be
followed along with package-specific security.
9. IANA Considerations
This document registers a new MIME type, "application/
simple-filter+xml", and registers a new XML namespace.
This specification follows the guidelines of RFC3023 [7].
9.1. application/simple-filter+xml MIME TYPE
MIME media type: application
MIME subtype name: simple-filter+xml
Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml, as
specified in RFC 3023 [7].
Encoding considerations: Same as encoding considerations of
application/xml, as specified in RFC 3023 [7].
Security considerations: See section 10 of RFC 3023 [7] and section
Section 8 of this document.
Interoperability considerations: none.
Published specification: This document.
Applications that use this media type: This document type has been
used to support the SIP-based Event notification framework and its
packages.
Additional information:
Magic number: None
File extension: .cl or .xml
Macintosh file type code: "TEXT"
Personal and email address for further information: Hisham Khartabil
(hisham.khartabil@telio.no)
Intended Usage: COMMON
Author/change controller: The IETF
9.2. URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:simple-filter
This section registers a new XML namespace, as per guidelines in the
IETF XML Registry [4].
URI: The URI for this namespace is
urn:ietf:params:xml:ns:simple-filter.
Registrant Contact: IETF, SIMPLE working group, Hisham Khartabil
(hisham.khartabil@telio.no)
9.3. Schema Registration
This section registers a new XML schema per the procedures in [4].
URI: urn:ietf:params:xml:ns:simple-filter
Registrant Contact: IETF, SIMPLE working group, Hisham Khartabil
(hisham.khartabil@telio.no).
The XML for this schema can be found as the sole content of
Section 7.
10. Acknowledgements
The authors would like to thank Jonathan Rosenberg, Henning
Schulzrinne, Tim Moran, Jari Urpalainen, Sreenivas Addagatla,
Miguel-Angel Garcia Martin, Mary Barnes, Paul Kyzivat, Robert Sparks,
and Elwyn Davies for their valuable input and comments.
11. References
11.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[2] Roach, A. B., "Session Initiation Protocol (SIP)-Specific Event
Notification", RFC 3265, June 2002.
[3] Khartabil, H., Leppanen, E., Lonnfors, M., and J. Costa-
Requena, "Functional Description of Event Notification
Filtering", RFC 4660, September 2006.
[4] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[5] Moats, R., "URN Syntax", RFC 2141, May 1997.
[6] Moats, R., "A URN Namespace for IETF Documents", RFC 2648,
August 1999.
[7] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types",
RFC 3023, January 2001.
[8] Bray, T., "Exensible Markup Language (XML) 1.0 (Second
Edition)", W3C CR CR-xml11-20011006, October 2000.
[9] Clark, J., "XML Path Language (XPath) Version 1.0", W3C REC
REC-xpath-19991116, November 1999.
[10] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.
[11] Ramsdell, B., "Secure/Multipurpose Internet Mail Extensions
(S/MIME) Version 3.1 Message Specification", RFC 3851, July
2004.
11.2. Informative References
[12] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002.
[13] Sugano, H., Fujimoto, S., Klyne, G., Bateman, A., Carr, W., and
J. Peterson, "Presence Information Data Format (PIDF)", RFC
3863, August 2004.
[14] Schulzrinne, H., Gurbani, V., Kyzivat, P., and J. Rosenberg,
"RPID -- Rich Presence Extensions to the Presence Information
Data Format (PIDF)", RFC 4480, July 2006.
[15] Rosenberg, J., "A Presence Event Package for the Session
Initiation Protocol (SIP)", RFC 3856, August 2004.
[16] Rosenberg, J., "An Extensible Markup Language (XML) Based
Format for Watcher Information", RFC 3858, August 2004.
[17] Roach, A. B., Campbell, B., and J. Rosenberg, "A Session
Initiation Protocol (SIP) Event Notification Extension for
Resource Lists", RFC 4663, September 2006.
[18] Rosenberg, J., "Presence Authorization Rules", Work in
Progress, June 2006.
Authors’ Addresses
Hisham Khartabil
Telio
P.O. Box 1203 Vika
Oslo
Norway
Phone: +47 2167 3544
EMail: hisham.khartabil@telio.no
Eva Leppanen
Nokia
P.O BOX 785
Tampere
Finland
Phone: +358 7180 77066
EMail: eva-maria.leppanen@nokia.com
Mikko Lonnfors
Nokia
P.O BOX 321
Helsinki
Finland
Phone: + 358 71800 8000
EMail: mikko.lonnfors@nokia.com
Jose Costa-Requena
Nokia
P.O. Box 321
FIN-00045 NOKIA GROUP
FINLAND
Phone: +358 71800 8000
EMail: jose.costa-requena@nokia.com
Full Copyright Statement
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).