Update PowerSaving to the stable spec that will be in 0.21.5

Reviewed-by: Eitan Isaacson <eitan.isaacson@collabora.co.uk>

1 files changed, 28 insertions, 20 deletions

diff --git a/extensions/Connection_Interface_Power_Saving.xml b/extensions/Connection_Interface_Power_Saving.xml
index da1b6bc52..d96903251 100644
--- a/extensions/Connection_Interface_Power_Saving.xml
+++ b/extensions/Connection_Interface_Power_Saving.xml
@@ -2,7 +2,7 @@
 <node name="/Connection_Interface_Power_Saving"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
   >
-  <tp:copyright> Copyright (C) 2007 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright © 2007-2010 Collabora Limited </tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
     <p>This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -19,24 +19,28 @@ License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
   <interface
-    name="org.freedesktop.Telepathy.Connection.Interface.PowerSaving.DRAFT"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.19.UNRELEASED"/>
+    name="org.freedesktop.Telepathy.Connection.Interface.PowerSaving">
+    <tp:added version="0.21.UNRELEASED">(as stable API)</tp:added>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>An interface for telling the connection when to enter and
-      leave power saving mode.</p>
+      <p>Some protocols support mechanisms for reducing bandwidth usage—and
+        hence power usage, on mobile devices—when the user is not directly
+        interacting with their IM client. For instance, Google Talk's XMPP
+        server supports queueing incoming presence updates at the client's
+        instruction; the client can instruct the server to deliver all
+        outstanding presence updates at a later time. This interface may be
+        used to instruct the connection manager to enable and disable such
+        protocol-level features when a screensaver is activated, the device
+        screen is locked, and so on, by calling the
+        <tp:member-ref>SetPowerSaving</tp:member-ref> method.</p>
 
-      <p>Power saving mode should be used when the user is not
-        directly interacting with the interface. For example, when
-        the screen saver is active, or when device screen is
-        locked.</p>
-
-      <p>Connection managers should implement this feature in a way
-        that is not noticeable by end users. For example, a protocol
-        might allow server-side blocking presence updates from
-        contacts to reduce network chatter. This would not affect the
-        user, since they are not interacting with their device when it
-        is in power saving mode.</p>
+      <p>Enabling power saving SHOULD NOT change behaviour in any way
+        that is noticable to a user not actively interacting with their client.
+        For example, delaying presence updates somewhat is unlikely to be
+        noticed by a user not staring at their device waiting for a contact to
+        come online; on the other hand, requesting that the server queue
+        incoming messages would be noticable by the user, so is not an
+        acceptable effect of calling
+        <tp:member-ref>SetPowerSaving</tp:member-ref>.</p>
     </tp:docstring>
 
     <method name="SetPowerSaving" tp:name-for-bindings="Set_Power_Saving">
@@ -45,7 +49,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
         <tp:rationale>
           <p>Depending on the device's activity level, the
-            connection can have it's power saving mode turned on or off.</p>
+            connection can have its power saving mode turned on or off.</p>
         </tp:rationale>
 
         <p>Errors raised by this method indicate that power saving could not be
@@ -62,7 +66,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
       <arg direction="in" name="Activate" type="b">
         <tp:docstring>
-          True when activating power saving, false when deactivating.
+          <code>True</code> if protocol-level power saving features should be
+          activated; <code>False</code> if they should be de-activated.
         </tp:docstring>
       </arg>
 
@@ -79,7 +84,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     <property name="PowerSavingActive" type="b" access="read"
               tp:name-for-bindings="Power_Saving_Active">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The current state of power saving. Change notifications is via the
+        <p><code>True</code> if protocol-level power saving features are
+          currently activated. This property can be changed using the
+          <tp:member-ref>SetPowerSaving</tp:member-ref> method; change
+          notifications is via the
           <tp:member-ref>PowerSavingChanged</tp:member-ref> signal.</p>
       </tp:docstring>
     </property>