spec 0.27.3

7 files changed, 378 insertions, 4 deletions

diff --git a/spec/Channel_Dispatcher_Interface_Messages1.xml b/spec/Channel_Dispatcher_Interface_Messages1.xml
new file mode 100644
index 000000000..e768b5549
--- /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="org.freedesktop.Telepathy.ChannelDispatcher.Interface.Messages1">
+    <tp:requires interface="org.freedesktop.Telepathy.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="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[]">
+        <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>
+</node>
+
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index f50b96344..493ac54f4 100644
--- a/spec/Channel_Type_File_Transfer.xml
+++ b/spec/Channel_Type_File_Transfer.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..864f1fa8e
--- /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="org.freedesktop.Telepathy.Connection.Interface.IRCCommand1"
+    tp:causes-havoc='not well-tested'>
+    <tp:requires interface="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.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_Renaming.xml b/spec/Connection_Interface_Renaming.xml
index d08b748d9..200611850 100644
--- a/spec/Connection_Interface_Renaming.xml
+++ b/spec/Connection_Interface_Renaming.xml
@@ -18,8 +18,8 @@ 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="org.freedesktop.Telepathy.Connection.Interface.Renaming"
-    tp:causes-havoc='not well-tested'>
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.Renaming">
+    <tp:added version="0.27.3">(as stable API)</tp:added>
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
     <signal name="Renamed" tp:name-for-bindings="Renamed">
       <arg name="Original" type="u" tp:type="Contact_Handle">
diff --git a/spec/Connection_Interface_Sidecars1.xml b/spec/Connection_Interface_Sidecars1.xml
new file mode 100644
index 000000000..c303fcbe8
--- /dev/null
+++ b/spec/Connection_Interface_Sidecars1.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Sidecars1"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+  >
+  <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
+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="org.freedesktop.Telepathy.Connection.Interface.Sidecars1">
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+    <tp:added version="0.27.3"/>
+
+    <method name="EnsureSidecar" tp:name-for-bindings="Ensure_Sidecar">
+      <tp:added version="0.27.3">(as stable API)</tp:added>
+
+      <arg direction="in" name="Main_Interface" type="s"
+           tp:type="DBus_Interface">
+        <tp:docstring>
+          The "primary" interface implemented by an object attached
+          to a connection. For example, a Gabble plugin implementing
+          fine-grained control of XEP-0016 privacy lists might expose an object
+          implementing <tt>com.example.PrivacyLists</tt>.
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" name="Path" type="o">
+        <tp:docstring>The object path of the sidecar, exported by the same bus
+          name as the Connection to which it is attached.</tp:docstring>
+      </arg>
+      <arg direction="out" name="Properties" type="a{sv}"
+           tp:type="Qualified_Property_Value_Map">
+        <tp:docstring>Immutable properties of the sidecar.</tp:docstring>
+      </arg>
+
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request an object with a particular interface providing additional
+          connection-specific functionality, together with its immutable
+          properties. These will often be implemented by plug-ins to the
+          connection managers; for example, support for an XMPP XEP for which
+          no generic Telepathy interface exists might be implemented by a
+          Gabble plugin exposing a sidecar with a particular interface.</p>
+
+        <p>This method may be called at any point during the lifetime of a
+          connection, even before its <tp:type>Connection_Status</tp:type>
+          changes to Connected. It MAY take a long time to
+          return—perhaps it needs to wait for a connection to be established
+          and for all the services supported by the server to be discovered
+          before determining whether necessary server-side support is
+          available—so callers SHOULD override the default method timeout (25
+          seconds) with a much higher value (perhaps even MAX_INT32, meaning
+          “no timeout” in recent versions of libdbus).</p>
+
+        <tp:rationale>
+          <p>There is an implicit assumption that any connection
+            manager plugin will only want to export one “primary” object per
+            feature it implements, since there is a one-to-one mapping between
+            interface and object. This is reasonable since Sidecars are
+            (intended to be) analogous to extra interfaces on the connection,
+            providing once-per-connection shared functionality; it also makes
+            client code straightforward (look up the interface you care about
+            in a dictionary, build a proxy object from the value). More
+            “plural” plugins are likely to want to implement new types of
+            <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>
+            instead.</p>
+        </tp:rationale>
+      </tp:docstring>
+
+      <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+        <tp:docstring>
+          The requested sidecar is not implemented by this connection manager,
+          or a necessary server-side component does not exist. (FIXME: split
+          these two errors out? Then again, once we list the guaranteed and
+          possible sidecars on a Protocol object, clients can tell the
+          difference themselves, because they shouldn't be calling this in the
+          first case.)
+        </tp:docstring>
+      </tp:error>
+
+      <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+        <tp:docstring>
+          A server-side component needed by the requested sidecar reported it
+          is currently too busy, or did not respond for some
+          implementation-defined time. The caller may wish to try again later.
+        </tp:docstring>
+      </tp:error>
+
+      <tp:error name="org.freedesktop.Telepathy.Error.Cancelled">
+        <tp:docstring>
+          The connection was disconnected while the sidecar was being set up.
+        </tp:docstring>
+      </tp:error>
+    </method>
+
+  </interface>
+</node>
diff --git a/spec/Makefile.am b/spec/Makefile.am
index ea7899a07..711c07bb8 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -24,6 +24,7 @@ EXTRA_DIST = \
     Channel.xml \
     Channel_Dispatch_Operation.xml \
     Channel_Dispatcher.xml \
+    Channel_Dispatcher_Interface_Messages1.xml \
     Channel_Dispatcher_Interface_Operation_List.xml \
     Channel_Future.xml \
     Channel_Handler.xml \
@@ -92,6 +93,7 @@ EXTRA_DIST = \
     Connection_Interface_Contact_List.xml \
     Connection_Interface_Contacts.xml \
     Connection_Interface_Forwarding.xml \
+    Connection_Interface_IRC_Command1.xml \
     Connection_Interface_Keepalive.xml \
     Connection_Interface_Location.xml \
     Connection_Interface_Mail_Notification.xml \
@@ -102,6 +104,7 @@ EXTRA_DIST = \
     Connection_Interface_Requests.xml \
     Connection_Interface_Resources.xml \
     Connection_Interface_Service_Point.xml \
+    Connection_Interface_Sidecars1.xml \
     Connection_Interface_Simple_Presence.xml \
     Connection_Manager.xml \
     Connection_Manager_Interface_Account_Storage.xml \
diff --git a/spec/all.xml b/spec/all.xml
index e1c8647eb..e94eb0677 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.27.2</tp:version>
+<tp:version>0.27.3</tp:version>
 
 <tp:copyright>Copyright © 2005-2012 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright>
@@ -48,7 +48,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    </p>
   </tp:docstring>
   <xi:include href="Connection.xml"/>
-  <xi:include href="Connection_Future.xml"/>
   <xi:include href="Connection_Interface_Contacts.xml"/>
   <xi:include href="Connection_Interface_Requests.xml"/>
 
@@ -108,6 +107,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <xi:include href="Connection_Interface_Mail_Notification.xml"/>
    <xi:include href="Connection_Interface_Power_Saving.xml"/>
    <xi:include href="Connection_Interface_Service_Point.xml"/>
+   <xi:include href="Connection_Interface_Sidecars1.xml"/>
+   <xi:include href="Connection_Interface_IRC_Command1.xml"/>
   </tp:section>
  </tp:section>
 
@@ -300,6 +301,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"/>