[telepathy-spec/master] fd.o#20905: Account.UpdateParameters: break API by returning a boolean: whether the update needs a reconnect

[Simon McVittie]

---
 spec/Account.xml |   39 ++++++++++++++++++++++++++++-----------
 1 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/spec/Account.xml b/spec/Account.xml
index 16aa698..fc42fe3 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -282,19 +282,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
     <method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        Change the value of the <tp:member-ref>Parameters</tp:member-ref>
-        property. If any of the changed parameters'
-        <tp:type>Conn_Mgr_Param_Flags</tp:type> include
-        <code>DBus_Property</code>, the change will be applied to the
-        corresponding D-Bus Property on the active
-        <tp:member-ref>Connection</tp:member-ref> if there is one; changes to
-        other parameters will not take effect until the next time the account
-        is disconnected and reconnected.
+        <p>Change the value of the <tp:member-ref>Parameters</tp:member-ref>
+          property.</p>
+
+        <p>If any of the changed parameters'
+          <tp:type>Conn_Mgr_Param_Flags</tp:type> include
+          <code>DBus_Property</code>, the change will be applied to the
+          corresponding D-Bus Property on the active
+          <tp:member-ref>Connection</tp:member-ref>, if there is one changes to
+          other parameters will not take effect until the next time the account
+          is disconnected and reconnected.</p>
 
         <tp:rationale>
-          Migration tools that twiddle the settings of all accounts shouldn't
-          cause an automatic disconnect and reconnect, probably. I could be
-          persuaded otherwise, though. Or we could add a Reconnect() method.
+          <p>In general, reconnecting is a destructive operation that shouldn't
+            happen as a side-effect. In particular, migration tools that
+            twiddle the settings of all accounts shouldn't cause an automatic
+            disconnect and reconnect.</p>
         </tp:rationale>
       </tp:docstring>
 
@@ -303,12 +306,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         existing Connections
       </tp:changed>
 
+      <tp:changed version="0.17.UNRELEASED">
+        return a boolean indicating whether to reconnect
+      </tp:changed>
+
       <arg name="Set" type="a{sv}" direction="in">
         <tp:docstring>
           A mapping from parameter names to their values. These parameters
           should be stored for future use.
         </tp:docstring>
       </arg>
+
       <arg name="Unset" type="as" direction="in">
         <tp:docstring>
           A list of the names of parameters to be removed from the set of
@@ -319,6 +327,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:docstring>
       </arg>
 
+      <arg name="Reconnect_Required" type="b" direction="out">
+        <tp:docstring>
+          If true, some or all of the parameter changes will not take effect
+          until the account is reconnected: user interfaces that require
+          "instant apply" semantics MAY call
+          <tp:member-ref>Reconnect</tp:member-ref> in response.
+        </tp:docstring>
+      </arg>
+
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
-- 
1.5.6.5