update to spec 0.23.1

Generate API for:
 - Channel.Interface.SMS.GetSMSLength()
 - ChannelDispatcher.DelegateChannels()
 - ChannelDispatcher.PresentChannel()

4 files changed, 215 insertions, 14 deletions

diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 2dd000b40..2de528001 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -168,10 +168,10 @@
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
           <tp:docstring>
-            The Preferred_Handler is syntactically invalid or does
+            The <var>Preferred_Handler</var> is syntactically invalid or does
             not start with <code>org.freedesktop.Telepathy.Client.</code>,
-            the Account does not exist, or one of the Requested_Properties
-            is invalid
+            the <var>Account</var> does not exist, or one of the
+            <var>Requested_Properties</var> is invalid
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
@@ -240,10 +240,10 @@
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
           <tp:docstring>
-            The Preferred_Handler is syntactically invalid or does
+            The <var>Preferred_Handler</var> is syntactically invalid or does
             not start with <code>org.freedesktop.Telepathy.Client.</code>,
-            the Account does not exist, or one of the Requested_Properties
-            is invalid
+            the <var>Account</var> does not exist, or one of the
+            <var>Requested_Properties</var> is invalid
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
@@ -418,10 +418,10 @@
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
           <tp:docstring>
-            The Preferred_Handler is syntactically invalid or does
+            The <var>Preferred_Handler</var> is syntactically invalid or does
             not start with <code>org.freedesktop.Telepathy.Client.</code>,
-            the Account does not exist, or one of the Requested_Properties
-            is invalid
+            the <var>Account</var> does not exist, or one of the
+            <var>Requested_Properties</var> is invalid
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
@@ -559,16 +559,139 @@
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
           <tp:docstring>
-            The Preferred_Handler is syntactically invalid or does
+            The <var>Preferred_Handler</var> is syntactically invalid or does
             not start with <code>org.freedesktop.Telepathy.Client.</code>,
-            the Account does not exist, or one of the Requested_Properties
-            is invalid
+            the <var>Account</var> does not exist, or one of the
+            <var>Requested_Properties</var> is invalid
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+
+    </method>
+
+    <method name="DelegateChannels"
+            tp:name-for-bindings="Delegate_Channels">
+      <tp:added version="0.23.1" />
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Called by a
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+          to redispatch a bunch of channels it is currently handling.</p>
+
+        <p>If another
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+          can be found,
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+          will be called on it and this function will succeed. In that case,
+          the original <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+          does not longer handle those channels.</p>
+
+        <p>If this method fails, the original
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+          is still handling the channels.</p>
+
+      </tp:docstring>
+
+      <arg direction="in" name="Channels" type="ao">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The list of channels to redispatch. The caller has to be the current
+            <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+            of all of these channels
+          </p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="in" name="User_Action_Time" type="x"
+        tp:type="User_Action_Timestamp">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The time at which user action occurred, or 0 if this channels
+            delegation is for some reason not involving user action.</p>
+
+          <p>This parameter is used in the same way as the corresponding
+            parameter to
+            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="in" name="Preferred_Handler" type="s"
+        tp:type="DBus_Well_Known_Name">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Either the well-known bus name (starting with
+            <code>org.freedesktop.Telepathy.Client.</code>)
+            of the preferred new handler for these
+            channels, or an empty string to indicate that any handler would be
+            acceptable. The behaviour and rationale are the same as for the
+            corresponding parameter to
+            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+
+        </tp:docstring>
+      </arg>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The Preferred_Handler is syntactically invalid or does
+            not start with <code>org.freedesktop.Telepathy.Client.</code> or
+            the Account does not exist.
+          </tp:docstring>
+        </tp:error>
+
+        <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+          <tp:docstring>
+            The caller is not currently handling the channels.
+          </tp:docstring>
+        </tp:error>
+
+        <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+          <tp:docstring>
+            There is no other suitable Handler.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
 
     </method>
 
+    <method name="PresentChannel"
+            tp:name-for-bindings="Present_Channel">
+      <tp:added version="0.23.1" />
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Equivalent of calling
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref>
+        with a <var>Requested_Properties</var> which would result in ensuring
+        <var>Channel</var>.</p>
+
+         <p>If <var>Channel</var> is handled, its handler will be asked to present it the user
+         (e.g. bring it into the foreground).</p>
+      </tp:docstring>
+
+      <arg direction="in" name="Channel" type="o">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The channel to present.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="in" name="User_Action_Time" type="x"
+        tp:type="User_Action_Timestamp">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The time at which user action occurred, or 0 if this channel
+            request is for some reason not involving user action.</p>
+
+          <p>This parameter is used in the same way as the corresponding
+            parameter to
+            <tp:member-ref>EnsureChannelWithHints</tp:member-ref>.</p>
+        </tp:docstring>
+      </arg>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The Account does not exist, the Channel does not exist or it
+            does not belong to the Account.
+          </tp:docstring>
+        </tp:error>
+
+      </tp:possible-errors>
+    </method>
+
     <property name="SupportsRequestHints"
               tp:name-for-bindings="Supports_Request_Hints"
               type="b" access="read">
diff --git a/spec/Channel_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml
index 235046c36..480a2a77c 100644
--- a/spec/Channel_Interface_SMS.xml
+++ b/spec/Channel_Interface_SMS.xml
@@ -205,5 +205,83 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <tp:member-ref>SMSChannel</tp:member-ref> property.
       </tp:docstring>
     </signal>
+
+    <method name="GetSMSLength"
+            tp:name-for-bindings="Get_SMS_Length">
+      <tp:added version="0.23.1"/>
+
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Returns the number of 140 octet chunks required to send a message
+          via SMS, as well as the number of remaining characters available in
+          the final chunk and, if possible, an estimate of the cost.</p>
+
+        <tp:rationale>
+          <p>There are a number of different SMS encoding mechanisms, and the
+            client doesn't know which mechanisms an individual CM might support.
+            This method allows the client, without any knowledge of the
+            encoding mechanism, to provide length details to the user.</p>
+        </tp:rationale>
+
+        <p>Clients SHOULD limit the frequency with which this method is called
+        and SHOULD NOT call it for every keystroke. Clients MAY estimate the
+        remaining size between single keystrokes.</p>
+      </tp:docstring>
+
+      <arg name="Message" type="aa{sv}" tp:type="Message_Part[]" direction="in">
+        <tp:docstring>
+          The message the user wishes to send.
+        </tp:docstring>
+      </arg>
+
+      <arg name="Chunks_Required" type="u" direction="out">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The number of 140 octet chunks required to send this message.</p>
+
+          <p>For example, in the GSM standard 7-bit encoding, a 162 character
+            message would require 2 chunks.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg name="Remaining_Characters" type="i" direction="out">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The number of further characters that can be fit in the final
+            chunk. A negative value indicates that the message will be
+            truncated by <code>abs(Remaining_Characters)</code>. The value
+            <code>MIN_INT32</code> (<code>-2<sup>31</sup></code>)
+            indicates the message will be truncated by an unknown amount.</p>
+
+          <p>For example, in the GSM standard 7-bit encoding, a 162 character
+            message would return 144 remaining characters (because of the
+            space required for the multipart SMS header).</p>
+        </tp:docstring>
+      </arg>
+
+      <arg name="Estimated_Cost" type="i" direction="out">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The estimated cost of sending this message. The currency and
+            scale of this value are the same as the
+            <tp:dbus-ref namespace="ofdT.Connection.Interface">Balance.AccountBalance</tp:dbus-ref>
+            property.</p>
+
+          <p>A value of <code>-1</code> indicates the cost could not be
+            estimated.</p>
+
+        </tp:docstring>
+      </arg>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+          <tp:docstring>
+            Raised when the method is not available on this channel.
+            Clients MAY choose to make their own estimation.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            Raised when the content cannot be encoded into a valid SMS.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
   </interface>
 </node>
diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml
index fe5492345..c4fd68c3b 100644
--- a/spec/Connection_Interface_Location.xml
+++ b/spec/Connection_Interface_Location.xml
@@ -60,7 +60,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
     <!-- Potentially to be reinstated later:
          http://bugs.freedesktop.org/show_bug.cgi?id=19585
-    <tp:enum name="Location_Accuracy_Level" type="i">
+    <tp:enum name="Location_Accuracy_Level" type="u">
       <tp:docstring>
         A location accuracy level. This should be kept in sync with
         GeoclueAccuracyLevel in the Geoclue project.
diff --git a/spec/all.xml b/spec/all.xml
index d1493eb53..e23c6c6f1 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.22.2</tp:version>
+<tp:version>0.23.1</tp:version>
 
 <tp:copyright>Copyright © 2005-2011 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright>