rfc4660 functional description of event notification filtering.txt

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

   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.




Khartabil, et al.           Standards Track                    [Page 13]

RFC 4660          Functional Description of Filtering     September 2006


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:[e-mail]">
            <tuple id="432sd">
               <status>
                  <basic>closed</basic>
               </status>
               <rpid:class>IM</rpid:class>
               <contact>im:[e-mail]</contact>
            </tuple>
            <tuple id="thr76jk">
               <status>
                  <basic>open</basic>
               </status>
               <rpid:class>voice</rpid:class>
               <contact>tel:[e-mail]</contact>



Khartabil, et al.           Standards Track                    [Page 14]

RFC 4660          Functional Description of Filtering     September 2006


            </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:[e-mail]
   Via: SIP/2.0/TCP client.example.com:5060;branch=z9hG4bKxjfdsjfk
   To: <sip:[e-mail]>
   From: <sip:[e-mail]>;tag:12341111
   Call-ID: 32432udfidfjmk342
   Cseq: 1 SUBSCRIBE
   Expires: 3600
   Event: Presence
   Contact: <sip:[e-mail]>
   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:[e-mail]">
       <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



Khartabil, et al.           Standards Track                    [Page 15]

RFC 4660          Functional Description of Filtering     September 2006


       </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:[e-mail] SIP/2.0
   Via: SIP/2.0/TCP presence.example.com:5060;branch=z9hG4bKxjfder
   To: <sip:[e-mail]>;tag:12341111
   From: <sip:[e-mail]>;tag:232321
   Call-ID: 32432udfidfjmk342
   Cseq: 1 NOTIFY
   Event: Presence
   Subscription-State: active; expires=3599
   Contact: sip:[e-mail]
   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:[e-mail]">
         <tuple id="432sd">
            <status>
               <basic>closed</basic>
            </status>
            <rpid:class>IM</rpid:class>
            <contact>im:[e-mail]</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".




Khartabil, et al.           Standards Track                    [Page 16]

RFC 4660          Functional Description of Filtering     September 2006


   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:[e-mail] SIP/2.0
   Via: SIP/2.0/TCP client.example.com:5060;branch=z9hG4bKxjfdsjfk
   To: <sip:[e-mail]>
   From: <sip:[e-mail]>;tag:12341111
   Call-ID: 32432udfidfjmk342
   Cseq: 1 SUBSCRIBE
   Expires: 3600
   Event: Presence
   Contact: <sip:[e-mail]>
   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:[e-mail]">
       <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:[e-mail] SIP/2.0
   Via: SIP/2.0/TCP presence.example.com:5060;branch=z9hG4bKxjfder
   To: <sip:[e-mail]>;tag:12341111
   From: <sip:[e-mail]>;tag:232321
   Call-ID: 32432udfidfjmk342
   Cseq: 1 NOTIFY
   Event: Presence



Khartabil, et al.           Standards Track                    [Page 17]

RFC 4660          Functional Description of Filtering     September 2006


   Subscription-State: active; expires=3599
   Contact: sip:[e-mail]
   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:[e-mail]">
         <tuple id="thr76jk">
            <status>
               <basic>open</basic>
            </status>
               <rpid:class>voice</rpid:class>
               <contact>tel:[e-mail]</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:[e-mail]
   Via: SIP/2.0/TCP client.example.com:5060;branch=z9hG4bKxjfdsjfk
   To: <sip:[e-mail]>
   From: <sip:[e-mail]>;tag:12341111
   Call-ID: 32432udfidfjmk342
   Cseq: 1 SUBSCRIBE
   Expires: 3600
   Event: Presence
   Contact: <sip:[e-mail]>
   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:[e-mail]">
       <trigger>
         <changed from="closed" to="open">
           /pidf:presence/pidf:tuple/pidf:status/pidf:basic



Khartabil, et al.           Standards Track                    [Page 18]

RFC 4660          Functional Description of Filtering     September 2006


         </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:[e-mail]">
         <tuple id="432sd">
            <status>
              <basic>closed</basic>
            </status>
               <rpid:class>IM</rpid:class>
               <contact>im:[e-mail]</contact>
         </tuple>
         <tuple id="thr76jk">
            <status>
               <basic>closed</basic>
            </status>
            <rpid:class>voice</rpid:class>
            <contact>tel:[e-mail]</contact>
         </tuple>
      </presence>