[Telepathy-commits] [telepathy-spec/master] Presence, SimplePresence: explicitly forbid setting offline statuses

[Simon McVittie]

---
 spec/Connection_Interface_Presence.xml        |   34 +++++++++++++++++--------
 spec/Connection_Interface_Simple_Presence.xml |   10 +++++++
 2 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
index 6d9b24a..e26bca6 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -249,17 +249,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           map optional parameter names to their variant-boxed values
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Request that the user's presence be changed to the given statuses and
-        desired parameters. Changes will be reflected by
-        <tp:member-ref>PresenceUpdate</tp:member-ref>
-        signals being emitted. On certain protocols, this method may be
-        called on a newly-created connection which is still in the
-        DISCONNECTED state, and will sign on with the requested status.
-        If the requested status is not available after signing on,
-        NotAvailable will be returned and the connection will remain
-        offline, or if the protocol does not support signing on with
-        a certain status, Disconnected will be returned.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request that the user's presence be changed to the given statuses
+          and desired parameters. Changes will be reflected by
+          <tp:member-ref>PresenceUpdate</tp:member-ref>
+          signals being emitted.</p>
+
+        <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+          is Offline, Error or Unknown MUST NOT be passed to this
+          function. Connection managers SHOULD reject these statuses.</p>
+
+        <tp:rationale>
+          <p>The same rationale as for <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref>
+            applies.</p>
+        </tp:rationale>
+
+        <p>On certain protocols, this method may be
+          called on a newly-created connection which is still in the
+          DISCONNECTED state, and will sign on with the requested status.
+          If the requested status is not available after signing on,
+          NotAvailable will be returned and the connection will remain
+          offline, or if the protocol does not support signing on with
+          a certain status, Disconnected will be returned.</p>
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml
index 16f3386..7e7d43f 100644
--- a/spec/Connection_Interface_Simple_Presence.xml
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -151,6 +151,16 @@
               the choices would be appropriate, and incorrect information
               about the user would be conveyed.</p>
           </tp:rationale>
+
+          <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+            is Offline, Error or Unknown MUST NOT be passed to this
+            function. Connection managers SHOULD reject these statuses.</p>
+
+          <tp:rationale>
+            <p>To go offline, call <tp:dbus-ref
+                namespace="org.freedesktop.Telepathy.Connection">Disconnect</tp:dbus-ref>
+            instead. The "error" and "unknown" statuses make no sense.</p>
+          </tp:rationale>
         </tp:docstring>
       </arg>
       <arg direction="in" name="Status_Message" type="s">
-- 
1.5.6.5