sync with spec 0.99.4

7 files changed, 270 insertions, 7 deletions

diff --git a/spec/Channel_Dispatcher_Interface_Messages1.xml b/spec/Channel_Dispatcher_Interface_Messages1.xml
new file mode 100644
index 000000000..4c0bd0cd3
--- /dev/null
+++ b/spec/Channel_Dispatcher_Interface_Messages1.xml
@@ -0,0 +1,175 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatcher_Interface_Messages1"
+      xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+  <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
+      modify it under the terms of the GNU Lesser General Public
+      License as published by the Free Software Foundation; either
+      version 2.1 of the License, or (at your option) any later version.</p>
+
+    <p>This library is distributed in the hope that it will be useful,
+      but WITHOUT ANY WARRANTY; without even the implied warranty of
+      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+      Lesser General Public License for more details.</p>
+
+    <p>You should have received a copy of the GNU Lesser General Public
+      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="im.telepathy1.ChannelDispatcher.Interface.Messages1">
+    <tp:requires interface="im.telepathy1.ChannelDispatcher"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>
+        This interface allows DBus clients to use the ChannelDispatcher to
+        send one-off text messages to a contact, identified by account and
+        target ID, without requiring the caller to handle channels or be
+        the primary message UI.
+      </p>
+
+      <tp:rationale>
+        <p>
+          This enables entities other than the main UI to send messages
+          to contacts.
+        </p>
+      </tp:rationale>
+    </tp:docstring>
+
+    <method name="SendMessage" tp:name-for-bindings="Send_Message">
+      <arg direction="in"  name="Account"  type="o">
+        <tp:docstring>
+          The <tp:dbus-ref namespace="imt1">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[]">
+        <tp:docstring>
+          The parts of the message, the same as for <tp:dbus-ref
+            namespace="imt1.Channel.Type">Text.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="imt1.Channel.Type">Text.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="imt1.Channel.Type">Text.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="imt1.Channel.Type">Text.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="imt1">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="imt1.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="imt1">Channel.ChannelType</tp:dbus-ref>:
+        …<tp:dbus-ref namespace="imt1">Channel.Type.Text</tp:dbus-ref>,
+    …<tp:dbus-ref namespace="imt1">Channel.TargetHandleType</tp:dbus-ref>:
+        <tp:value-ref type="Handle_Type">Contact</tp:value-ref>,
+    …<tp:dbus-ref namespace="imt1">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="imt1.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref>
+          or <tp:dbus-ref
+            namespace="imt1.Channel.Type">Text.SendMessage</tp:dbus-ref>
+          methods, or signalled by the <tp:dbus-ref
+            namespace="imt1.ChannelRequest">Failed</tp:dbus-ref>
+          signal.</p>
+      </tp:docstring>
+
+      <tp:possible-errors>
+        <tp:error name="im.telepathy1.Error.Disconnected"/>
+        <tp:error name="im.telepathy1.Error.NetworkError"/>
+        <tp:error name="im.telepathy1.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="im.telepathy1.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="im.telepathy1.Error.InvalidHandle">
+          <tp:docstring>
+            The requested message is malformed and cannot be sent.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="im.telepathy1.Error.Offline">
+          <tp:docstring>
+            The requested channel cannot be created because the target is
+            offline.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="im.telepathy1.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="im.telepathy1.Error.PermissionDenied"/>
+      </tp:possible-errors>
+    </method>
+
+  </interface>
+</node>
+
diff --git a/spec/Channel_Type_File_Transfer1.xml b/spec/Channel_Type_File_Transfer1.xml
index dbfe5424f..50d59ff9d 100644
--- a/spec/Channel_Type_File_Transfer1.xml
+++ b/spec/Channel_Type_File_Transfer1.xml
@@ -579,6 +579,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </arg>
     </signal>
 
+    <property name="FileCollection" tp:name-for-bindings="File_Collection"
+      type="s" access="read">
+      <tp:added version="0.27.3"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The collection of files to which this channel belongs,
+          or the empty string if this channel does not belong to
+          a collection of files.</p>
+
+        <p>A channel's FileCollection property can never change.</p>
+
+        <p>At least on GTalk and apparently also on iChat the user can
+          send a set of files to a contact and that contact can then
+          pick and choose which files to actually receive.</p>
+
+        <p> The CM should emit all new FT channels belonging to one collection
+          at the same time. UIs supporting this feature can then
+          bundle all these channels together in some way, and show a
+          nice UI. UIs not supporting it will treat them as separate
+          transfers, which is not great but a reasonable fallback.</p>
+
+        <p>No mechanism is currently defined to indicate whether the UI
+          should expect any more files in the same collection. UIs
+          SHOULD assume that more file transfers may be added to a
+          collection. It is possible that a "no more channels in this
+          collection" indication will be added in a future version of
+          this specification.</p>
+      </tp:docstring>
+    </property>
+
   </interface>
 
 </node>
diff --git a/spec/Connection_Interface_IRC_Command1.xml b/spec/Connection_Interface_IRC_Command1.xml
new file mode 100644
index 000000000..c4fa597bf
--- /dev/null
+++ b/spec/Connection_Interface_IRC_Command1.xml
@@ -0,0 +1,55 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_IRC_Command1" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright> Copyright (C) 2013 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
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+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="im.telepathy1.Connection.Interface.IRCCommand1"
+    tp:causes-havoc='not well-tested'>
+    <tp:requires interface="im.telepathy1.Connection"/>
+    <tp:added version="0.27.3"/>
+
+    <method name="Send" tp:name-for-bindings="Send">
+      <arg direction="in" name="Command" type="s">
+        <tp:docstring>
+          The command followed by its arguments.
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Send an arbitrary IRC command to the server.</p>
+        <p>For example, an IRC client receiving <code>/bip blreset</code> from
+           the user might call this method with <code>BIP blreset</code> as
+           argument which will send <code>BIP blreset</code> to the server.</p>
+        <p>The command is supplied in UTF-8 (because strings on D-Bus are
+           always UTF-8). It is transcoded into the connection's configured
+           character set, if different, before sending to the server.</p>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="im.telepathy1.Error.Disconnected"/>
+        <tp:error name="im.telepathy1.Error.NetworkError"/>
+        <tp:error name="im.telepathy1.Error.InvalidArgument">
+          <tp:docstring>
+            The connection manager MAY raise this error for commands that
+            have a more appropriate D-Bus API.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+    <tp:docstring>
+      An interface to send arbitrary IRC commands to the server.
+    </tp:docstring>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Renaming1.xml b/spec/Connection_Interface_Renaming1.xml
index 15b7a9ac5..7c480dae8 100644
--- a/spec/Connection_Interface_Renaming1.xml
+++ b/spec/Connection_Interface_Renaming1.xml
@@ -18,9 +18,9 @@ Lesser General Public License for more details.</p>
 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="im.telepathy1.Connection.Interface.Renaming1"
-    tp:causes-havoc='not well-tested'>
+  <interface name="im.telepathy1.Connection.Interface.Renaming1">
     <tp:requires interface="im.telepathy1.Connection"/>
+    <tp:added version="0.27.3">(as stable API)</tp:added>
     <signal name="Renamed" tp:name-for-bindings="Renamed">
       <arg name="Original" type="u" tp:type="Contact_Handle">
         <tp:docstring>
diff --git a/spec/Connection_Interface_Sidecars1.xml b/spec/Connection_Interface_Sidecars1.xml
index 3ab8b27df..9ef67f3ef 100644
--- a/spec/Connection_Interface_Sidecars1.xml
+++ b/spec/Connection_Interface_Sidecars1.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Connection_Interface_Sidecars1"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-
-  <tp:copyright>Copyright © 2012 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2009-2013 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2009 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
       modify it under the terms of the GNU Lesser General Public
@@ -22,7 +22,7 @@
 
   <interface name="im.telepathy1.Connection.Interface.Sidecars1">
     <tp:requires interface="im.telepathy1.Connection"/>
-    <tp:added version="0.99.1">from Connection.FUTURE</tp:added>
+    <tp:added version="0.27.3"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>A <a href="http://en.wikipedia.org/wiki/Sidecar">sidecar</a>
@@ -32,7 +32,7 @@
     </tp:docstring>
 
     <method name="EnsureSidecar" tp:name-for-bindings="Ensure_Sidecar">
-      <tp:added version="0.19.0">(as a draft)</tp:added>
+      <tp:added version="0.27.3">(as stable API)</tp:added>
 
       <arg direction="in" name="Main_Interface" type="s"
            tp:type="DBus_Interface">
diff --git a/spec/Makefile.am b/spec/Makefile.am
index 85d03af99..e73bb33b7 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -25,6 +25,7 @@ EXTRA_DIST = \
     Channel.xml \
     Channel_Dispatch_Operation.xml \
     Channel_Dispatcher.xml \
+    Channel_Dispatcher_Interface_Messages1.xml \
     Channel_Dispatcher_Interface_Operation_List1.xml \
     Channel_Interface_Addressing1.xml \
     Channel_Interface_Anonymity1.xml \
@@ -82,6 +83,7 @@ EXTRA_DIST = \
     Connection_Interface_Contact_List1.xml \
     Connection_Interface_Contacts.xml \
     Connection_Interface_Forwarding1.xml \
+    Connection_Interface_IRC_Command1.xml \
     Connection_Interface_Keepalive1.xml \
     Connection_Interface_Location1.xml \
     Connection_Interface_Mail_Notification1.xml \
diff --git a/spec/all.xml b/spec/all.xml
index 437496bfa..b18d77b3b 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.99.2</tp:version>
+<tp:version>0.99.4</tp:version>
 
 <tp:copyright>Copyright © 2005-2013 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright>
@@ -106,6 +106,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <xi:include href="Connection_Interface_Power_Saving1.xml"/>
    <xi:include href="Connection_Interface_Service_Point1.xml"/>
    <xi:include href="Connection_Interface_Sidecars1.xml"/>
+   <xi:include href="Connection_Interface_IRC_Command1.xml"/>
   </tp:section>
  </tp:section>
 
@@ -278,6 +279,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_List1.xml"/>
  <xi:include href="Channel_Dispatch_Operation.xml"/>
  <xi:include href="Channel_Request.xml"/>