added text about IQ delivery

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3469 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0060.xml

@@ -50,13 +50,13 @@
   &ralphm;
 
   <revision>
-    <version>1.13rc4</version>
+    <version>1.13rc5</version>
-    <date>in progress, 2009-09-18</date>
+    <date>in progress, 2009-09-29</date>
     <initials>psa</initials>
     <remark>
       <ul>
         <li>Corrected a large number of reported errata.</li>
-        <li>Removed delete-any and delete-node features.</li>
+        <li>Removed delete-any feature.</li>
         <li>Added missing delete-items feature.</li>
         <li>Removed replyto and replyroom config options.</li>
         <li>Removed multiple node discovery since it depended on the deprecated Service Discovery Publishing feature.</li>
@@ -71,7 +71,8 @@
         <li>Added retrieve-default-sub feature for retrieving default subscription configuration from a node (as you can retrieve default node configuration from the service).</li>
         <li>Clarified suggested rules for payload definitions.</li>
         <li>Mentioned that singleton pattern can be enforced by setting max_items to 1.</li>
-        <li>Removed subids from subscription approval forms because subscribers can have only one unapproved subscription request at a time.</li>
+        <li>Removed subids from subscription approval forms because subscribers can have only one unapproved subscription request per node at a given time.</li>
+        <li>Added optional support for delivery of notifications via XMPP IQ stanzas.</li>
       </ul>
     </remark>
   </revision>
@@ -1875,7 +1876,7 @@ And by opposing end them?
     from='francisco@denmark.lit/barracks'
     to='pubsub.shakespeare.lit'
     id='def1'>
-  <pubsub xmlns='http://jabber.org/protocol/pubsub'
+  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
     <default node='princely_musings'/>
   </pubsub>
 </iq>
@@ -1889,7 +1890,7 @@ And by opposing end them?
     from='pubsub.shakespeare.lit'
     to='francisco@denmark.lit/barracks'
     id='def1'>
-  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'
+  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
     <default node='princely_musings'>
       <x xmlns='jabber:x:data' type='result'>
         <field var='FORM_TYPE' type='hidden'>
@@ -2197,8 +2198,8 @@ O, what a rogue and peasant slave am I!
 </iq>
       ]]></example>
     </section3>
-    <section3 topic='Requesting Some Items' anchor='subscriber-retrieve-requestsome'>
+    <section3 topic='Requesting the Most Recent Items' anchor='subscriber-retrieve-requestrecent'>
-      <p>A service MAY allow entities to request the most recent N items by using the 'max_items' attribute. When max_items is used, implementations SHOULD return the N most recent (as opposed to the N oldest) items. (Note: A future version of this specification may recommend the use of &xep0059; instead of the 'max_items' attribute.)</p>
+      <p>A service MAY allow entities to request the most recent N items by using the 'max_items' attribute. When max_items is used, implementations SHOULD return the N most recent (as opposed to the N oldest) items. (Note: A future version of this specification may recommend the use of <cite>XEP-0059</cite> instead of the 'max_items' attribute.)</p>
       <example caption='Subscriber requests two most recent items'><![CDATA[
 <iq type='get'
     from='francisco@denmark.lit/barracks'
@@ -2266,6 +2267,7 @@ And by opposing end them?
   </pubsub>
 </iq>
       ]]></example>
+      <p>The service would then return that specific item, if available.</p>
     </section3>
     <section3 topic='Error Cases' anchor='subscriber-retrieve-error'>
       <p>There are several reasons why the items retrieval request might fail:</p>
@@ -3335,7 +3337,7 @@ And by opposing end them?
           <value>0</value>
         </field>
         <field var='pubsub#notification_type' type='list-single'
-               label='Specify the message type for notifications'>
+               label='Specify the delivery style for notifications'>
           <option><value>normal</value></option>
           <option><value>headline</value></option>
           <value>headline</value>
@@ -3676,7 +3678,7 @@ And by opposing end them?
           <value>0</value>
         </field>
         <field var='pubsub#notification_type' type='list-single'
-               label='Specify the message type for notifications'>
+               label='Specify the delivery style for notifications'>
           <option><value>normal</value></option>
           <option><value>headline</value></option>
           <value>headline</value>
@@ -5018,6 +5020,29 @@ And by opposing end them?
 
   <section2 topic='Presence-Based Delivery of Events' anchor='impl-presence'>
     <p>Implementations of pubsub MAY deliver event notifications only when the subscriber is online. In these cases, the option may be a node configuration option as shown in the examples above. To facilitate this, the pubsub service needs to subscribe to the subscriber's presence and check the subscriber's current presence information before sending any event notifications (as described in <cite>RFC 3921</cite>). Presence subscriptions MUST be based on the subscribed JID.</p>
+    <section3 topic='IQ Notifications' anchor='impl-presence-iq'>
+      <p>If the pubsub service supports presence-based delivery and a node is configured to enable such delivery, the service MAY offer a value of "iq" for the "pubsub#notification_type" node configuration option. If this value is chosen, the service shall deliver notifications in XMPP IQ stanzas instead of in XMPP message stanzas. Because IQ stanzas are addressed to full JIDs &LOCALFULL;, if the service does not know the full JID of a given subscriber then it MAY send notifications to the bare JID &LOCALBARE; of the subscriber via the usual message stanza, or MAY not send a notification at all. The IQ stanza containing a notification shall be of type "set", and in accordance with the semantics of the IQ stanza defined in <cite>RFC 3920</cite> the recipient MUST return either an IQ stanza of type "result" or an IQ stanza of type "error". An example follows</p>
+      <example caption='Service Notifies Subscriber via IQ'><![CDATA[
+<iq from='pubsub.shakespeare.lit'
+    id='jc9jn253'
+    to='francisco@denmark.lit/barracks'
+    type='set'>
+  <event xmlns='http://jabber.org/protocol/pubsub#event'>
+    <items node='princely_musings'>
+      <item id='ae890ac52d0df67ed7cfdf51b644e901'>
+        [ ... ENTRY ... ]
+      </item>
+    </items>
+  </event>
+</iq>
+      ]]></example>
+      <example caption='Subscriber Indicates Success'><![CDATA[
+<iq from='francisco@denmark.lit/barracks'
+    id='jc9jn253'
+    to='pubsub.shakespeare.lit'
+    type='result'/>
+      ]]></example>
+    </section3>
   </section2>
 
   <section2 topic='Not Routing Events to Offline Storage' anchor='impl-offline'>
@@ -5030,8 +5055,9 @@ And by opposing end them?
   </section2>
 
   <section2 topic='Including a Message Body' anchor='impl-body'>
-    <p>If a service understands the semantics for a particular payload type and an entity's subscription is so configured (via the "pubsub#include_body" option), the service SHOULD include an appropriate XMPP &BODY; child element along with the payloads it sends in event notifications for a given node, where the body's XML character data summarizes or represents the information contained in the payload (this enables clients that do not understand the payload format to present the appropriate information to an end user). For example, the Atom &lt;summary/&gt; element (see <cite>RFC 4287</cite>) could be mapped to the XMPP &BODY; element. A service MUST NOT provide the "pubsub#include_body" subscription option for a node if it does not have a defined way to transform part or all of the payload format into a sensible message body. A node owner MAY define an XSLT for transforming the payload format into a message body, via the "pubsub#body_xslt" node configuration option. This XSLT is applied by the pubsub service after receiving a publish request and before sending the appropriate notifications, not by the client before sending a publish request.</p>
+    <p>If a service understands the semantics for a particular payload type and an entity's subscription is so configured (by the "pubsub#include_body" subscription option to true), the service SHOULD include an appropriate XMPP &BODY; child element along with the payloads it sends in event notifications for a given node, where the body's XML character data summarizes or represents the information contained in the payload (this enables clients that do not understand the payload format to present the appropriate information to an end user). For example, the Atom &lt;summary/&gt; element (see <cite>RFC 4287</cite>) could be mapped to the XMPP &BODY; element. A service MUST NOT provide the "pubsub#include_body" subscription option for a node if it does not have a defined way to transform part or all of the payload format into a sensible message body. A node owner MAY define an XSLT for transforming the payload format into a message body, via the "pubsub#body_xslt" node configuration option. This XSLT is applied by the pubsub service after receiving a publish request and before sending the appropriate notifications, not by the client before sending a publish request.</p>
-    <p>If the service does not understand the semantics for a particular payload type, it MAY include a &lt;body/&gt; child whose XML character data informs the subscriber that the message contains an event notification (e.g., text such as "This message contains an event notification" would be appropriate).</p>
+    <p>If the service does not understand the semantics for a particular payload type and therefore cannot transform the payload into a human-readable message body, it SHOULD NOT include a &lt;body/&gt; child.</p>
+    <p>If a subscriber has multiple subscriptions to the same node, where some of the SubIDs have include_body set to true and others have include_body set to false, the service SHOULD include a body with all notifications.</p>
   </section2>
 
   <section2 topic='Node ID and Item ID Uniqueness' anchor='impl-uniqueness'>
@@ -6013,13 +6039,16 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=retrieve;node=princely_musings;item=ae
     </option>
   </field>
   <field var='pubsub#notification_type' type='list-single'
-         label='Specify the message type for notifications'>
+         label='Specify the delivery style for notifications'>
     <option label='Messages of type normal'>
       <value>normal</value>
     </option>
     <option label='Messages of type headline'>
       <value>headline</value>
     </option>
+    <option label='IQ stanzas (works only with presence-based delivery)'>
+      <value>iq</value>
+    </option>
   </field>
   <field var='pubsub#notify_config'
          type='boolean'
@@ -6166,7 +6195,7 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=retrieve;node=princely_musings
     <example caption='Pubsub Retrieve Action: Resulting Stanza'><![CDATA[
 <iq to='pubsub.shakespeare.lit' type='get'>
   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
-    <subscribe node='princely_musings'/>
+    <items node='princely_musings'/>
   </pubsub>
 </iq>
     ]]></example>