Describe use of client probes.

xep-0318.xml

@@ -6,8 +6,8 @@
 <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
 <xep>
 <header>
-  <title>Last Presence using Delayed Delivery</title>
+  <title>Best Practices for Client Initiated Presence Probes</title>
-  <abstract>This specification defines a way to determine the time when a XMPP entity has last changed its presence.</abstract>
+  <abstract>This specification defines a way to determine the time when a XMPP entity has last changed its presence. Using client initiated presence probes the current presence of subscribed XMPP users can be requested. In addition a protocol to request the uptime of servers and components is defined herein.</abstract>
   &LEGALNOTICE;
   <number>0318</number>
   <status>Experimental</status>
@@ -24,6 +24,12 @@
   <supersededby/>
   <shortname>last-presence</shortname>
   &tobias;
+  <revision>
+    <version>0.2</version>
+    <date>2013-08-06</date>
+    <initials>tobias</initials>
+    <remark><p>Fix issues raised in XMPP Council meeting.</p></remark>
+  </revision>
   <revision>
     <version>0.1</version>
     <date>2013-03-04</date>
@@ -38,35 +44,52 @@
   </revision>
 </header>
 <section1 topic='Introduction' anchor='intro'>
-  <p>This protocol describes a way to communicate time of last presence change with other XMPP entities over presence stanzas. This is done extending presence stanzas with delayed delivery information according to &xep0203; and can be used to determine the time of last presence change for XMPP entities includeing servers. For users on the same server, the server also adds delyed delivery information to the presence responses.</p>
+<p>&rfc6121;, section 4.3, defines presence probes as a way for servers to actively ping for presence status of XMPP contacts. In some scenarios however, clients want to request an update on the status of a XMPP contact.</p>
-  <p>The time of the delayed delivery information attatched to the presence indicates the time a XMPP entity has last changed to this presence.</p>
+</section1>
+<section1 topic='Rationale' anchor='rationale'>
+<p>While &rfc6121; specifically advises against (SHOULD NOT) clients sending presence probes to XMPP contacts, there are valid scenarios where XMPP clients want to send presence probes.</p>
+<p>According to &rfc6121;, contacts a client doesn't have presence information on, are expected to be offline and server aren't mandated to explicitly send offline presence to the client for offline users.</p>
+<p>In addition, clients in constrained environments (i.e. mobile clients), could explicitly tell the server to filter out presence stanzas of certain kind, to keep communication to a minimum. One such protocol is &xep0273;.</p>
+<p>This causes presence information to be outdated and any information, that might have been attached to the offline presence, i.e. &xep0203;, to be missing at client side.</p>
+<p>Sending presence probes from the client should be based on human request, i.e. opening a chat dialog to an offline contact when messing full presence information for that contact. Clients MUST NOT send presence probes to all contacts that they think are offline after login.</p> 
 </section1>
 <section1 topic='Use Cases' anchor='usecases'>
-  <section2 topic='Last Presence of a XMPP Entity' anchor='case-xmpp-entity'>
+This section describes two major use cases of the described protocol, client initiated presence probes.
-    <p>This section describes how to determine the time a user when offline or, in general, changed to her current presence state. This is merly a description since the protocol is already described in &rfc6121;, section 4.3.2.</p>
+<section2 topic='Requesting up-to-date Presence of a XMPP Entity' anchor='presence-pull'>
-    <p>The following example show a possible incoming presence in response to going online by sending your own available presence.</p>
+<p>In some situations, after login, the client has incomplete presence information for offline contacts. The user might be interested in status text of the offline presence of a contact or when a contact went offline. This information can be requested, i.e. when the user opens a chat dialog to an offline user, using a client initiated presence probe and is described in the following two examples.</p>
-    <example caption='Incoming Presence with Delayed Delivery'><![CDATA[
+<p>Initialilly a client requests the current presence information of a contact by sending out a presence probe.</p> 
-<presence from='romeo@montague.com/kitchen' to='juliet@capulet.com/balcony' type'unavailable'>
+<example caption='Request for up-to-date Presence using Presence Probe'><![CDATA[
-  <delay xmlns='urn:xmpp:delay' stamp='2002-09-10T23:41:07Z'/>
+<presence from='juliet@capulet.com/balcony' to='romeo@montague.com' type='probe' />]]></example>
+<p>The other side's server, in this example montague.com, then responds with the last known presence of the user, including &xep0203; and other information provided by the user.</p>
+<example caption='Presence Reply in Response to Presence Probe'><![CDATA[
+<presence from='romeo@montague.com' to='juliet@capulet.com/balcony' type='unavailable'>
+  <status>Going offline. Out of battery.</status>
+  <delay xmlns='urn:xmpp:delay'
+     from='romeo@montague.com/balcony'
+     stamp='2012-09-10T23:41:07Z'/>
 </presence>]]></example>
-  </section2>
+</section2>
-  <section2 topic='Uptime Reporting of Servers and Components' anchor='case-uptime-report'>
+<section2 topic='Requesting Uptime of a XMPP Server' anchor='uptime-request'>
-    <p>Reqesting the uptime of a server or component is done by sending a directed presence probe to the XMPP entity of interest. The request is shown in the following example.</p>
+<p>XMPP servers typically don't have all the properties known from XMPP clients, like presence or rosters. However, &xep0267; for example added rosters to XMPP servers.</p>
-    <example caption='Request for Uptime Reporting using Presence Probe'><![CDATA[
+<p>In a similar manner, this extension describes the use of presence for XMPP servers and XMPP components. Basically, when a XMPP server or component starts up it's expected to set its presence to online.</p>
+<p>With this concept, any party could easily request the time a XMPP server or component went online, by sending a presence probe to it.</p>
+<example caption='Request for Presence of a XMPP Server'><![CDATA[
 <presence from='juliet@capulet.com/balcony' to='montague.com' type='probe' />]]></example>
-    <p>The server or component then responds with an available presence, extended with delayed delivery information, according to <cite>XEP-0203</cite>, indicating its startup time. This is shown below:</p>
+In response, the requester receives a presence stanza, which contains &xep0203; information, indicating the time the server went online.
-    <example caption='Response to the Presence Probe'><![CDATA[
+<example caption='Response from XMPP Server indicating uptime'><![CDATA[
 <presence from='montague.com' to='juliet@capulet.com/balcony'>
-  <delay xmlns='urn:xmpp:delay' stamp='2002-09-10T23:41:07Z'/>
+  <delay xmlns='urn:xmpp:delay'
+     from='montague.com'
+     stamp='2012-09-10T23:41:07Z'/>
 </presence>]]></example>
-  </section2>
+</section2>
 </section1>
 <section1 topic='Acknowledgements' anchor='ack'>
   <p>Thanks to Kim Alvefur and Lance Stout for their helpful comments.</p>
 </section1>
 <section1 topic='Security Considerations' anchor='security'>
-  <p>Adding delayed delivery notation to the presence probe responses exposes information a user might not expect to have exposed. However the information about last presence change is known to all entities subscribed to one's presence which are online. This extension just provides this information to XMPP entities which have been offline during the course of presence change.</p>
+  <p>Adding delayed delivery notation to the presence probe responses exposes information a user might not expect to have exposed. However, the information about last presence change is known to all entities subscribed to one's presence which are online. This extension just provides this information to XMPP entities which have been offline during the course of presence change.</p>
-  <p>It's worth to note that the security considerations of &xep0082; apply here.</p>
+  <p>The security considerations of &xep0082; apply here.</p>
 </section1>
 <section1 topic='IANA Considerations' anchor='iana'>
   <p>This document requires no interaction with &IANA;.</p>