xeps/xep-0230.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Service Discovery Notifications</title>
  <abstract>This specification defines a method for requesting and receiving notifications regarding XMPP service discovery items.</abstract>
  &LEGALNOTICE;
  <number>0230</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0030</spec>
    <spec>XEP-0060</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT YET ASSIGNED</shortname>
  &hildjj;
  &stpeter;
  <revision>
    <version>0.1</version>
    <date>2008-01-30</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2008-01-06</date>
    <initials>jjh/psa</initials>
    <remark><p>Corrected example to use full JIDs and SubIDs.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2008-01-03</date>
    <initials>jjh/psa</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>&xep0115; defines a way for entities to receive dynamically-updated information about &xep0030; capabilities, rather than polling for updates by sending repeated disco#info requests. However, there is no comparable method for receiving updated disco#items information (this might be helpful when the number of associated entities is large or dynamic, e.g., at a multi-user chat service). This document specifies such a method by re-using semantics from &xep0060;.</p>
</section1>

<section1 topic='Protocol' anchor='protocol'>
  <p>Before a requesting entity asks for service discovery items with notifications, it SHOULD send directed presence to the responding entity so that the responding entity knows when to stop sending notifications.</p>
  <example caption='Requesting entity sends presence'><![CDATA[
<presence from='bill@shakespeare.lit/globe' to='chat.shakespeare.lit'/>
  ]]></example>
  <p>The requesting entity then sends a disco#items request to the responding entity, including a &lt;subscribe/&gt; element qualified by the 'http://jabber.org/protocol/pubsub' namespace, which in turn specifies a node of 'http://jabber.org/protocol/disco#items'.</p>
  <example caption='Requesting all items'><![CDATA[
<iq type='get'
    from='bill@shakespeare.lit/globe'
    to='chat.shakespeare.lit'
    id='items1'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <subscribe xmlns='http://jabber.org/protocol/pubsub'/>
  </query>
</iq>
  ]]></example>
  <p>If the responding entity does not recognize inclusion of the &lt;subscribe/&gt; element as a child of the &lt;query/&gt; element, it MUST return the service discovery items but MUST NOT send subsequent notifications to the requesting entity.</p>
  <p>If the requesting entity did not share presence with the responding entity, the responding entity MUST return the service discovery items but SHOULD NOT send subsequent notifications to the requesting entity.</p>
  <p>If the responding entity recognizes inclusion of the &lt;subscribe/&gt; element as a child of the &lt;query/&gt; element and the requesting entity is allowed to receive notifications, the responding entity MUST return the service discovery items (including a &lt;subscriptions/&gt; element) and SHOULD send subsequent notifications to the requesting entity.</p>
  <example caption='Result-set for all items'><![CDATA[
<iq type='result'
    from='chat.shakespeare.lit'
    to='bill@shakespeare.lit/globe'
    id='items1'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='alls-well-that-ends-well@rooms.shakespeare.lit'/>
    <item jid='as-you-like-it@rooms.shakespeare.lit'/>
    <item jid='cleopatra@rooms.shakespeare.lit'/>
    <item jid='comedy-of-errors@rooms.shakespeare.lit'/>
    <item jid='coriolanus@rooms.shakespeare.lit'/>
    <item jid='cymbeline@rooms.shakespeare.lit'/>
    <item jid='hamlet@rooms.shakespeare.lit'/>
    <item jid='henry-the-fourth-one@rooms.shakespeare.lit'/>
    <item jid='henry-the-fourth-two@rooms.shakespeare.lit'/>
    <item jid='henry-the-fifth@rooms.shakespeare.lit'/>
    <subscription
        jid='bill@shakespeare.lit'
        subid='some-long-sub-id'
        subscription='subscribed'/>
  </query>
</iq>
  ]]></example>
  <p>The responding entity then SHOULD send subsequent notifications to the requesting entity when associated items are added to or deleted from the potential result set.</p>
  <example caption='A notification (new item)'><![CDATA[
<message from='chat.shakespeare.lit' to='bill@shakespeare.lit' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/disco#items'/>
      <item id='ae890ac52d0df67ed7cfdf51b644e901'>
        <item xmlns='http://jabber.org/protocol/disco#items'
              jid='henry-the-fifth@rooms.shakespeare.lit'/>
      </item>
    </items>
  </event>
</message>
  ]]></example>
  <example caption='A notification (deleted item)'><![CDATA[
<message from='chat.shakespeare.lit' to='bill@shakespeare.lit' id='bar'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/disco#items'/>
      <retract id='fa890ca52d0df67de7fcfd51b644c701'>
        <item xmlns='http://jabber.org/protocol/disco#items'
              jid='cardenio@rooms.shakespeare.lit'/>
      </item>
    </items>
  </event>
</message>
  ]]></example>
  <p>When the requesting entity goes offline, the responding entity will receive unavailable presence.</p>
  <example caption='Responding entity receives unavailable presence'><![CDATA[
<presence from='bill@shakespeare.lit/globe' 
          to='chat.shakespeare.lit' 
          type='unavailable'/>
  ]]></example>
  <p>The responding entity then MUST NOT send further notifications.</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>This document introduces no new security considerations above and beyond those already defined for service discovery and publish-subscribe.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p> 
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>This document requires no interaction with the &REGISTRAR;.</p> 
</section1>

</xep>