rfc4661 an extensible markup language (xml)-based format for.txt

有关IMS SIP及Presence应用的RFC文档包


RFC 4661             XML Based Format for Filtering       September 2006


   The syntax defined in Section 5 (see the definition of "selection")
   MUST be used.  The following example selects the <basic> element
   defined in the PIDF [13].  This results in the selection of the
   <basic> element as well as all the ancestors, i.e., <status> and
   <tuple>.

   <include type="xpath">/presence/tuple/status/basic</include>.

3.5.2.  The <exclude> Element

   The <exclude> element is used to define exceptions to the set of XML
   elements and/or attributes selected by the <include> elements.  Thus,
   XML elements (including their lower-level "child" elements) and/or
   attributes defined by the <exclude> element are not delivered.  This
   is most useful when an <include> element identifies a namespace.

   The <exclude> element has the optional 'type' attribute (see the
   definition of the 'type' in Section 3.5.3).

   Note that the resulting XML document MUST be valid.  Therefore, if
   the step in applying the <exclude> element value to an XML document
   results in an invalid document according to the schema, that step
   MUST be reversed, resulting in the elements and/or attributes being
   re-introduced into the resulting XML document with their previous
   values in order to make it valid.  This, in practice, means that a
   subscriber defining a filter only needs to <exclude> optional
   elements and/or attributes, but SHOULD NOT <exclude> mandatory
   elements and/or attributes.

   The syntax MUST follow Section 5.

3.5.3.  The 'type' Attribute

   The 'type' attribute is used to describe the value of the <include>
   and <exclude> elements.  The following values are pre-defined:
   "xpath" and "namespace".  The 'type' attribute is optional, and, if
   omitted, the default value is "xpath".

   The "xpath" value is used when the <include> or <exclude> element
   contains a value following the syntax in Section 5 that selects an
   element or an attribute.

   The "namespace" value is used when the <include> or <exclude> element
   contains a value of a namespace.  The value is the URI of the
   namespace.  The resulting XML document is comprised of the elements
   defined within the namespace.





Khartabil, et al.           Standards Track                     [Page 7]

RFC 4661             XML Based Format for Filtering       September 2006


3.6.  The <trigger> Element

   The <trigger> element is used to identify the package-specific
   changes that a resource has to encounter before the content is
   delivered to the subscriber.  It can appear more than once in a
   <filter> element.  Multiple appearances of this element denote the
   "OR" operation.  This means that updates to a resource that satisfy
   any of the <trigger> elements criteria constitute the content to be
   delivered.

   The <trigger> element MAY contain the <changed>, <added>, or
   <removed> elements, but it MUST contain at least one of the three
   elements.  Any combination of the 3 elements is possible.  Multiple
   appearances of those elements within a <trigger> element denotes the
   "AND" operation.  This means that updates to a resource that satisfy
   ALL of the <changed>, <added>, and <removed> elements' criteria
   within the <trigger> element constitute the content to be delivered.

3.6.1.  The <changed> Element

   The <changed> element is used to identify the XML element or
   attribute, from the package-specific XML document, whose value MUST
   change from that of the "previous XML document", in order to activate
   the trigger and cause the content to be delivered.  Previous XML
   document" in this context refers to the raw version of the most
   recent XML document that was sent to the subscriber, before the
   filters were applied to it.  The XML element or attribute MUST be
   expressed using the syntax defined in Section 5 for the "reference"
   ABNF.

   The <changed> element MAY contain the 'from' attribute, the 'to'
   attribute, the 'by' attribute, or any combination of the three.  The
   absence of all of those attributes means a change of any sort to the
   value of the element or attribute activates the trigger.  An update
   to the element or attribute value with an identical value is not a
   change.

   Comparison of a change is done according to the element or
   attribute's lexical rules.

3.6.1.1.  The 'from' Attribute

   A trigger is active when the XML element or attribute identified with
   the <changed> element has changed from the value indicated by this
   attribute to a different value.






Khartabil, et al.           Standards Track                     [Page 8]

RFC 4661             XML Based Format for Filtering       September 2006


3.6.1.2.  The 'to' Attribute

   A trigger is active when the XML element or attribute identified with
   the <changed> element has changed to the value indicated by this
   attribute from a different value.

3.6.1.3.  The 'by' Attribute

   A trigger is active when the XML element or attribute identified with
   the <changed> element has changed by at least the amount indicated by
   this attribute from a different value.  That is, the 'by' attribute
   applies only to numerical values and indicates a delta with respect
   to the current value that an attribute or element (identified in the
   <changed> element) needs to change before it is selected.  For
   example, if the 'by' attribute is set to 2 and the current value of
   the element/attribute is 6, the element/attribute is selected when it
   reaches (or exceeds) the value 8 or when it decreases to 4 or a lower
   value.

3.6.1.4.  Combination of Attributes

   Any combination of the 'from', 'to', and 'by' attributes in the
   <changed> element is possible.  For example, if the 'from' attribute
   is combined with the 'to' attribute, it is interpreted to mean that
   the trigger is active when the XML element or attribute identified
   with the <changed> element has changed from the 'from' value to the
   'to' value.  Note that if the 'by' attribute is used in combination
   with the other attributes, the other attribute types MUST match the
   'by' type of decimal.

3.6.2.  The <added> Element

   The <added> element triggers content delivery when the XML element it
   identifies has been added to the document being filtered (that is,
   this instance of that element appears in the current document, but
   not in the previous document).  It can be used, for example, to learn
   of new services and/or capabilities subscribed to by the user, or
   services and/or capabilities that the user has now allowed the
   subscriber to see.  The XML element or attribute MUST be expressed
   using the syntax defined in Section 5 for the "reference" ABNF.

   Note that if a filter includes both the content filter (<what>) part
   and the <added> element, then the definitions of the <what> part
   SHOULD also cover the added elements.  Otherwise, the content is
   delivered without the items defined in the <added> element.






Khartabil, et al.           Standards Track                     [Page 9]

RFC 4661             XML Based Format for Filtering       September 2006


3.6.3.  The <removed> Element

   The <removed> element triggers content delivery when the XML element
   it identifies has been removed from the document being filtered (that
   is, this instance of that element appeared in the previous document,
   but not in this document).  The XML element or attribute MUST be
   expressed using the syntax defined in Section 5 for the "reference"
   ABNF.

4.  XML Schema Extensibility

   The simple-filter document is meant to be extended.  An extension
   takes place by defining a new set of elements in a new namespace,
   governed by a new schema.  Every extension MUST have an appropriate
   XML namespace assigned to it.  The XML namespace of the extension
   MUST be different from the namespaces defined in this specification.
   The extension MUST NOT change the syntax or semantics of the schemas
   defined in this document.  All XML tags and attributes that are part
   of the extension MUST be appropriately qualified so as to place them
   within that namespace and MUST be designed such that receivers can
   safely ignore such extensions.

   This specification defines explicit places where new elements or
   attributes from an extension can be placed.  These are explicitly
   indicated in the schemas by the <any> and <anyAttribute> elements.
   Extensions to this specification MUST specify where their elements
   can be placed within the document.

   As a result, a document that contains extensions will require
   multiple schemas in order to determine its validity - a schema
   defined in this document, along with those defined by extensions
   present in the document.  Because extensions occur by adding new
   elements and attributes governed by new schemas, the schemas defined
   in this document are fixed and would only be changed by a revision to
   this specification.  Such a revision, should it take place, would
   endeavor to allow documents compliant to the previous schema to
   remain compliant to the new one.  As a result, the schemas defined
   here don't provide explicit schema versions, as this is not expected
   to be needed.

5.  Syntax for Referencing XML Items and Making Logical Expressions

   The ABNF [10] is used to describe the syntax for the expressions.
   The syntax is defined to be XPATH [9] compatible but has only a
   restricted set of capabilities of the XPATH.  More information about
   the meaning of the items of the syntax can be found in [9].  The
   "abbreviated syntax" of the "node test" is used in the references
   ("reference").  The expression in the syntax relates to the



Khartabil, et al.           Standards Track                    [Page 10]

RFC 4661             XML Based Format for Filtering       September 2006


   predicate, comparison, and logical expressions of the XPATH.  If an
   XPATH expression evaluates to more than one element at a certain
   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"]





Khartabil, et al.           Standards Track                    [Page 11]

RFC 4661             XML Based Format for Filtering       September 2006


   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:[e-mail]">



Khartabil, et al.           Standards Track                    [Page 12]