1.1rc1: added use case for initial presence

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

xep-0256.xml

@@ -22,6 +22,12 @@
   <supersededby/>
   <shortname>N/A</shortname>
   &stpeter;
+  <revision>
+    <version>1.1rc1</version>
+    <date>in progress, last updated 2009-05-27</date>
+    <initials>psa</initials>
+    <remark><p>Added use case for initial presence.</p></remark>
+  </revision>
   <revision>
     <version>1.0</version>
     <date>2009-05-06</date>
@@ -41,16 +47,34 @@
     <remark><p>Rough draft based on list discussion.</p></remark>
   </revision>
 </header>
-<section1 topic='Use Case' anchor='usecase'>
+<section1 topic='Use Cases' anchor='usecases'>
-  <p>&xep0012; defines a method for determining the last time that an XMPP entity was active. This document specifies that an online client MAY include last activity information when sending presence updates. The prototypical use case is including the idle time when automatically setting the user's &SHOW; value to "away" or "xa" (extended away). For example, consider a user who has configured her client to automatically change her presence to "away" after 10 minutes of inactivity. The client could include an iq:last flag to specify how long the user has been idle.</p>
+  <p>&xep0012; defines a method for determining the last time that an XMPP entity was active. This document specifies that an online client MAY include last activity information when sending a presence update. Including such information essentially means "when I sent this presence notification I had last been active at time T".</p>
-  <example caption='Last Indication in Auto-Away'><![CDATA[
+  <p>There are two primary use cases:</p>
+  <ol start='1'>
+    <li>When a client sends initial presence to start a presence session, the last activity notation indicates when that client terminated its previous presence session.</li>
+    <li>When a client changes from available to "away" or "xa", the last activity notation indicates when that client was last active during the current presence session.</li>
+  </ol>
+  <p>The following sections show examples of each use case.</p>
+  <section2 topic='Initial Presence' anchor='initial'>
+    <p>When a client begins a presence session, it can indicate when that particular client was last online. It does this by sending initial presence with a last activity notation.</p>
+    <example caption='Last Indication in Initial Presence'><![CDATA[
+<presence from='juliet@capulet.com/balcony'>
+  <query xmlns='jabber:iq:last' seconds='86511'/>
+</presence>
+    ]]></example>
+    <p>This can be read as "I'm now online and I was last online at this client 24 hours and 111 seconds ago".</p>
+  </section2>
+  <section2 topic='Away and Extended Away' anchor='away'>
+    <p>When a client automatically sets the user's &SHOW; value to "away" or "xa" (extended away), it can indicate when that particular was last active during the current presence session.</p>
+    <example caption='Last Indication in Auto-Away'><![CDATA[
 <presence from='juliet@capulet.com/balcony'>
   <show>away</show>
   <query xmlns='jabber:iq:last' seconds='600'/>
 </presence>
-  ]]></example>
+    ]]></example>
-  <p>If one of the user's contacts receives that presence notification with delayed delivery (see &xep0203;) on login in response to a presence probe as described in &xmppim;, the contact will then know how long the user has been idle (i.e., the number of seconds since the delayed delivery timestamp, plus the iq:last seconds). Thus the contact does not need to send an iq:last query.</p>
+    <p>This can be read as "I just went away and I was last active 10 minutes ago".</p>
-  <example caption='Last Indication in Auto-Away With Delayed Delivery'><![CDATA[
+    <p>If one of the user's contacts receives that presence notification with delayed delivery (see &xep0203;) on login in response to a presence probe as described in &xmppim;, the contact will then know how long the user has been idle (i.e., the number of seconds since the delayed delivery timestamp, plus the iq:last seconds). Thus the contact does not need to send an iq:last query.</p>
+    <example caption='Last Indication in Auto-Away With Delayed Delivery'><![CDATA[
 <presence from='juliet@capulet.com/balcony' to='romeo@montague.net'>
   <show>away</show>
   <query xmlns='jabber:iq:last' seconds='600'/>
@@ -58,7 +82,8 @@
      from='capulet.com'
      stamp='2002-09-10T23:41:07Z'/>
 </presence>
-  ]]></example>
+    ]]></example>
+  </section2>
 </section1>
 <section1 topic='Security Considerations' anchor='security'>
   <p>Including a last activity notation in presence notifications can enable those who receive such notifications to determine exactly when a user has stopped interacting with his or her XMPP client, but this information is in essence already available if the user publishes timely presence updates. Therefore, this specification introduces no new vulnerabilities.</p>