📄 rfc4661 an extensible markup language (xml)-based format for.txt
字号:
Network Working Group H. Khartabil
Request for Comments: 4661 Telio
Category: Standards Track E. Leppanen
M. Lonnfors
J. Costa-Requena
Nokia
September 2006
An Extensible Markup Language (XML)-Based Format for
Event Notification Filtering
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
The SIP event notification framework describes the usage of the
Session Initiation Protocol (SIP) for subscriptions and notifications
of changes to a state of a resource. The document does not describe
a mechanism whereby filtering of event notification information can
be achieved. Filtering is a mechanism for defining the preferred
notification information to be delivered and for specifying triggers
that cause that information to be delivered. In order to enable
this, a format is needed to enable the subscriber to describe the
state changes of a resource that cause notifications to be sent to it
and what those notifications are to contain. This document presents
a format in the form of an XML document.
Khartabil, et al. Standards Track [Page 1]
RFC 4661 XML Based Format for Filtering September 2006
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Structure of XML-Encoded Simple-Filter . . . . . . . . . . . . 4
3.1. MIME Type for Simple-Filter Document . . . . . . . . . . 4
3.2. The <filter-set> Root Element . . . . . . . . . . . . . 4
3.3. The <ns-bindings> Element . . . . . . . . . . . . . . . 4
3.4. The <filter> Element . . . . . . . . . . . . . . . . . . 5
3.5. The <what> Element . . . . . . . . . . . . . . . . . . . 6
3.5.1. The <include> Element . . . . . . . . . . . . . 6
3.5.2. The <exclude> Element . . . . . . . . . . . . . 7
3.5.3. The 'type' Attribute . . . . . . . . . . . . . . 7
3.6. The <trigger> Element . . . . . . . . . . . . . . . . . 8
3.6.1. The <changed> Element . . . . . . . . . . . . . 8
3.6.2. The <added> Element . . . . . . . . . . . . . . 9
3.6.3. The <removed> Element . . . . . . . . . . . . . 10
4. XML Schema Extensibility . . . . . . . . . . . . . . . . . . . 10
5. Syntax for Referencing XML Items and Making Logical
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 10
6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Filter Criteria Using <what> Element . . . . . . . . . . 12
6.2. Filter Criteria Using <trigger> Element . . . . . . . . 13
6.3. Filter Criteria Using <what> and <trigger> Elements . . 13
6.4. Content Filter Using Namespaces . . . . . . . . . . . . 14
6.5. Content Filter Using Only <include> Elements . . . . . . 14
6.6. Two Content Filters as Filter Criteria . . . . . . . . . 15
7. XML Schema for Filter Criteria . . . . . . . . . . . . . . . . 16
8. Security Considerations . . . . . . . . . . . . . . . . . . . 18
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
9.1. application/simple-filter+xml MIME TYPE . . . . . . . . 19
9.2. URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:simple-filter . . . . . . . . . . . 20
9.3. Schema Registration . . . . . . . . . . . . . . . . . . 20
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
11.1. Normative References . . . . . . . . . . . . . . . . . . 20
11.2. Informative References . . . . . . . . . . . . . . . . . 21
Khartabil, et al. Standards Track [Page 2]
RFC 4661 XML Based Format for Filtering September 2006
1. Introduction
The SIP event notification framework [2] describes the usage of the
Session Initiation Protocol (SIP) for subscriptions and notifications
of changes to a state of a resource. The document does not describe
a mechanism whereby filtering of event notification information can
be achieved.
Filtering is a mechanism for defining the preferred notification
information, referred to as content, to be delivered and for
specifying the rules for when that information should be delivered.
The filtering mechanism is expected to be particularly valuable and
primarily applicable to users of mobile wireless access devices. The
characteristics of the devices typically include high latency, low
bandwidth, low data processing capabilities, small display, and
limited battery power. Such devices can benefit from the ability to
filter the amount of information generated at the source of the event
notification. However, implementers need to be aware of the
computational burden on the source of the event notification. This
is discussed further in Section 8.
The structure of the filter criteria is described using the XML
schema. The filter criteria is presented as an XML document. The
XML document contains the user's preference as to when notifications
are to be sent to it and what they are to contain. The scope of the
"when" part is triggering.
The triggering is defined as enabling a subscriber to specify
triggering rules for notifications where the criteria are based on
changes of the event package [2] specific state information, e.g.,
for the presence information document [15], the change in the value
of the <status> element.
The functionality of the filtering regarding the SIP event
notifications is specified in [3].
2. Conventions
In this document, the key words 'MUST', 'MUST NOT', 'REQUIRED',
'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY',
and 'OPTIONAL' are to be interpreted as described in RFC 2119 [1] and
indicate requirement levels for compliant implementations.
Throughout the document, the "resulting XML document" refers to the
final XML document that carries state information to be delivered to
the subscriber after the filters have been applied to it.
Khartabil, et al. Standards Track [Page 3]
RFC 4661 XML Based Format for Filtering September 2006
"Content" refers to the XML document that appears in a notification
reflecting the state of a resource.
3. Structure of XML-Encoded Simple-Filter
A simple-filter is an XML document [8] that MUST be well formed and
MUST be valid according to schemas, including extension schemas,
available to the validater, and applicable to the XML document. The
simple-filter documents MUST be based on XML 1.0 and MUST be encoded
using UTF-8.
The namespace identifier for elements defined by this specification
is a URN [5], which uses the namespace identifier 'ietf' defined by
[6] and extended by [4]. This urn is:
urn:ietf:params:xml:ns:simple-filter.
This namespace declaration indicates the namespace on which the
filter criteria are based.
3.1. MIME Type for Simple-Filter Document
The MIME type for the simple-filter document is "application/
simple-filter+xml". Any transport protocol (SIP [12], for example)
used to carry the filters that also carries payload type information
MUST identify the payload as MIME type
"application/simple-filter+xml" (for example, a Content-Type header
field).
3.2. The <filter-set> Root Element
The root element of the filter criteria is <filter-set>.
The <filter-set> element contains the namespace definition mentioned
above. With the optional 'package' attribute, it is possible to
define the package to which the filter criteria is applied. This
might be especially useful in cases where the XML document containing
the filter criteria is separated from the events that make use of it
or from the protocol that usually carries it.
The <filter-set> element may contain one <ns-bindings> element.
The <filter-set> element contains one or more <filter> elements.
3.3. The <ns-bindings> Element
The <ns-bindings> element is used to bind namespaces to local
prefixes used in expressions that select elements or attributes using
Khartabil, et al. Standards Track [Page 4]
RFC 4661 XML Based Format for Filtering September 2006
the syntax in Section 5. Those prefixes apply to the <include>,
<exclude>, <changed>, <added>, and <removed> elements.
The <ns-bindings> element contains one or more <ns-binding> elements.
Each <ns-binding> element has a 'prefix' attribute. The value of the
'prefix' attribute is a prefix used to qualify the elements pointed
to by the expression. The <ns-binding> element also has a 'urn'
attribute that identifies the namespace that the prefix represents.
3.4. The <filter> Element
The <filter> element is used to specify the content of an individual
filter.
The <filter> element has an 'id' attribute. The value of the 'id'
attribute MUST be unique within the <filter-set> element. The
<filter> MAY have a 'uri' attribute. The value of the 'uri'
attribute is the URI of the resource to which the filter applies.
The <filter> MAY have a 'domain' attribute. The value of the
'domain' attribute is the domain of the resources to which the filter
applies. The 'uri' attribute and the 'domain' attribute MUST NOT
appear together in the <filter>.
The URI of the resource is useful in cases where the 'event list'
extension [17] is used with a package. Since a subscription to an
event package may be addressed to an event list, the 'uri' attribute
allows the subscriber to define a filter specific to an individual
resource within that list. That resource may be another list. The
'uri' attribute may, of course, carry the URI of the list itself. If
the <filter> does not contain the 'uri' attribute, the filter applies
to the resource identified in the subscription request.
The 'domain' attribute carries a domain. In this case, the filter
applies to resources whose URI has a domain part matching that
domain. This can be used when a subscription is for a resource that
is an event list with many resources from differing domains.
URI matching is done according to the matching rules defined for a
particular scheme. When matching domains, the user part of the URI
is ignored for matching purposes.
The <filter> MAY have a 'remove' attribute that together with the
'id' attribute indicates the existing filter to be removed. The
value of the 'remove' attribute is of the type "Boolean". The
default value is "false".
Khartabil, et al. Standards Track [Page 5]
RFC 4661 XML Based Format for Filtering September 2006
The <filter> MAY have an 'enabled' attribute that indicates whether a
filter is enabled or disabled. The value of the 'enabled' attribute
is of the type "Boolean". The default value is "true".
The <filter> element MAY contain a <what> element and MAY contain one
or more <trigger> elements, but it MUST contain either the <what>
element or the <trigger> element when the filter is being enabled for
the first time. When a filter is disabled by setting the 'enabled'
attribute to "false", the <what> and <trigger> elements MAY be
omitted. Similarly, when a filter is re-enabled by setting the
'enabled' attribute to "true", the <what> and <trigger> elements MAY
be omitted.
Filter contents can be changed by changing the contents in the <what>
and <trigger> elements and maintaining the value of the filter 'id'
attribute.
3.5. The <what> Element
The <what> element is used to specify the content to be delivered to
the user. It does not specify the exact content but the rules that
are used to construct that information.
The <what> element may contain one or more <include> elements and one
or more <exclude> elements. When more than one <include> element has
been defined, the results are additive. That is, each <include>
element adds an element or attribute to the resulting XML document.
When more than one <exclude> element has been defined, each <exclude>
element value depletes the contents of the resulting XML document.
3.5.1. The <include> Element
The <include> element is used to select the content to be delivered.
Its value can identify an XML element, an attribute, or a namespace
of an XML document to be filtered. This is indicated using the
'type' attribute.
Note that the resulting XML document MUST be valid. Therefore, in
addition to including the elements identified with the <include>
element value, all other mandatory XML elements and/or attributes
must be incorporated in the resulting XML document in order to make
it valid. This, in practice, means that a subscriber defining a
filter only needs to <include> optional elements and/or attributes,
but may <include> mandatory elements and/or attributes as well.
There are also cases where a filter selects an attribute that belongs
to an optional element. In this case, the optional element needs to
appear in the resulting XML document.
Khartabil, et al. Standards Track [Page 6]
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -