Complete CD.I.Messages1

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=37380
Reviewed-by: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>

2 files changed, 129 insertions, 10 deletions

diff --git a/spec/Channel_Dispatcher_Interface_Messages1.xml b/spec/Channel_Dispatcher_Interface_Messages1.xml
index 61a398b7..e768b554 100644
--- a/spec/Channel_Dispatcher_Interface_Messages1.xml
+++ b/spec/Channel_Dispatcher_Interface_Messages1.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
-<node name="/Channel_Dispatcher_Interface_Messages_Draft"
+<node name="/Channel_Dispatcher_Interface_Messages1"
       xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
 
-  <tp:copyright>Copyright (C) 2011 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright (C) 2011-2013 Collabora Ltd.</tp:copyright>
   <tp:copyright>Copyright (C) 2011 Nokia Corporation</tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
     <p>This library is free software; you can redistribute it and/or
@@ -22,9 +22,7 @@
   </tp:license>
 
   <interface
-    name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.Messages.DRAFT"
-    tp:causes-havoc="not yet final">
-
+    name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.Messages1">
     <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -44,12 +42,132 @@
     </tp:docstring>
 
     <method name="SendMessage" tp:name-for-bindings="Send_Message">
-      <arg direction="in"  name="Account"  type="o"/>
-      <arg direction="in"  name="TargetID" type="s"/>
+      <arg direction="in"  name="Account"  type="o">
+        <tp:docstring>
+          The <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref>
+          through which to communicate.
+        </tp:docstring>
+      </arg>
+      <arg direction="in"  name="Target_ID" type="s">
+        <tp:docstring>
+          The contact to send the message to.
+        </tp:docstring>
+      </arg>
       <arg direction="in"  name="Message"  type="aa{sv}"
-           tp:type="Message_Part[]"/>
-      <arg direction="in"  name="Flags"    type="u"/>
-      <arg direction="out" name="Token"    type="s"/>
+           tp:type="Message_Part[]">
+        <tp:docstring>
+          The parts of the message, the same as for <tp:dbus-ref
+            namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
+        </tp:docstring>
+      </arg>
+      <arg direction="in"  name="Flags"    type="u">
+        <tp:docstring>
+          Flags influencing how to send the message, the same as for <tp:dbus-ref
+            namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
+        </tp:docstring>
+      </arg>
+      <arg direction="out" name="Token"    type="s">
+        <tp:docstring>
+          An opaque token equivalent to the one returned by <tp:dbus-ref
+            namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Submit a message to the server for sending, like the
+          <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>
+          method.</p>
+
+        <p>If the <var>Account</var> is connected and a Text channel to the
+          <var>Target_ID</var> already exists, this method is equivalent to
+          sending the same message via that channel.</p>
+
+        <p>Otherwise, this method creates a channel (connecting the
+          Account if appropriate), sends the desired message, and
+          closes the channel as if via <tp:dbus-ref
+            namespace="ofdT">Channel.Close</tp:dbus-ref>, without
+          acknowledging any messages received on that channel
+          during that time.</p>
+
+        <p>If any messages are received on that channel before it is
+          closed, a correct connection manager implementation will reopen
+          the channel when it is closed, resulting in those "rescued" messages
+          being processed by the system's normal <tp:dbus-ref
+            namespace="ofdT.Client">Handler</tp:dbus-ref> for text
+          channels. In particular, this deals with the situation where
+          a successful or failed delivery report is received
+          before the channel is closed.</p>
+
+        <tp:rationale>
+          <p>Expecting a trivial client (perhaps a send-only IRC bot,
+            or a simple SMS-sending API) to go through all those steps to
+            send a message seems somewhat unreasonable. Having this as a
+            method in the ChannelDispatcher lets it take some short-cuts if
+            required, and centralizes the implementation to reduce the risk of
+            mistakes that cause message loss.</p>
+        </tp:rationale>
+
+        <p>The ChannelDispatcher SHOULD support this method for any
+          connection manager that would accept channel requests of this
+          form:</p>
+
+        <pre>  {
+    …<tp:dbus-ref namespace="ofdT">Channel.ChannelType</tp:dbus-ref>:
+        …<tp:dbus-ref namespace="ofdT">Channel.Type.Text</tp:dbus-ref>,
+    …<tp:dbus-ref namespace="ofdT">Channel.TargetHandleType</tp:dbus-ref>:
+        <tp:value-ref type="Handle_Type">Contact</tp:value-ref>,
+    …<tp:dbus-ref namespace="ofdT">Channel.TargetID</tp:dbus-ref>:
+    <var>Target_ID</var>
+  }</pre>
+
+        <p>However, if the connection manager provides additional APIs
+          (such as a way to open "send-only" channels), the
+          ChannelDispatcher MAY use those: it is not required to use
+          those exact request parameters.</p>
+
+        <p>This method may raise any error that would be raised by the
+          <tp:dbus-ref
+            namespace="ofdT.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref>
+          or <tp:dbus-ref
+            namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>
+          methods, or signalled by the <tp:dbus-ref
+            namespace="ofdT.ChannelRequest">Failed</tp:dbus-ref>
+          signal.</p>
+      </tp:docstring>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+          <tp:docstring>
+            The connection manager does not implement Text channels
+            that communicate with a named contact.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+          <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+            The <var>Target_ID</var> was not syntactically valid for the
+            <var>Account</var>'s protocol.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+          <tp:docstring>
+            The requested message is malformed and cannot be sent.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.Offline">
+          <tp:docstring>
+            The requested channel cannot be created because the target is
+            offline.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The requested channel cannot be created, but in
+            principle, a similar request might succeed in future.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+      </tp:possible-errors>
     </method>
 
   </interface>
diff --git a/spec/all.xml b/spec/all.xml
index f41a7000..616b8806 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -300,6 +300,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   </p>
  </tp:docstring>
  <xi:include href="Channel_Dispatcher.xml"/>
+ <xi:include href="Channel_Dispatcher_Interface_Messages1.xml"/>
  <xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/>
  <xi:include href="Channel_Dispatch_Operation.xml"/>
  <xi:include href="Channel_Request.xml"/>