Add the spec Connection.Interface.ContactCapabilities.DRAFT

2 files changed, 174 insertions, 1 deletions

diff --git a/xml/Connection_Interface_Contact_Capabilities.xml b/xml/Connection_Interface_Contact_Capabilities.xml
new file mode 100644
index 00000000..4d1d6320
--- /dev/null
+++ b/xml/Connection_Interface_Contact_Capabilities.xml
@@ -0,0 +1,172 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright> Copyright (C) 2005, 2006, 2008 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright (C) 2005, 2006, 2008 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright (C) 2006 INdT </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.ContactCapabilities.DRAFT">
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface to get contact capabilities in order to know what channel
+        classes may be created with a contact before the request is made to the
+        connection object. Each capability represents a commitment by the
+        connection manager that it will ordinarily be able to create a channel
+        with a contact when given a request with the properties defined by the
+        channel class.</p>
+
+      <p>Capabilities pertain to particular contact handles, and represent
+        activities such as having a text chat, a voice call with the user or a
+        stream tube of a defined type.</p>
+
+      <p>This interface also enables user interfaces to notify the connection
+        manager what capabilities to advertise for the user to other contacts.
+        This is done by using the SetSelfCapabilities method, and deals with
+        channel properties values pertaining to them which are implemented by
+        available client processes.</p>
+
+    </tp:docstring>
+
+    <method name="SetSelfCapabilities"
+            tp:name-for-bindings="Set_Self_Capabilities">
+      <arg direction="in" name="caps" type="aa{sv}"
+           tp:type="String_Variant_Map[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          An array of channel classes to replace to the list of what the
+          connection can handle
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Used by user interfaces to indicate which channel classes they are
+        able to handle on this connection. It replaces the previous advertised
+        channel classes by the set given as parameter.</p>
+
+        <p>If a channel class is unknown by the connection manager, it is just
+        ignored. No error are returned in this case, and other known channel
+        class are added.</p>
+
+        <p>Upon a successful invocation of this method, the
+        ContactCapabilitiesChanged signal will be emitted for the user's own
+        handle (as returned by GetSelfHandle) by the connection manager to
+        indicate the changes that have been made.</p>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+      </tp:possible-errors>
+    </method>
+
+    <method name="GetContactCapabilities"
+            tp:name-for-bindings="Get_Contact_Capabilities">
+      <arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>An array of contact handles for this connection.</p>
+
+          <p>The handle zero MUST NOT be included in the request.</p>
+        </tp:docstring>
+      </arg>
+      <!-- There was a bug in dbus-glib that prevent to use the right type:
+           Instead of a{ua(a{sv}as)}, we used a(ua{sv}as) as a workaround.
+           See http://bugs.freedesktop.org/show_bug.cgi?id=17329
+           Now there is a fix, so we don't use the workaround anymore.
+        -->
+      <arg direction="out" type="a{ua(a{sv}as)}"
+           tp:type="Contact_Handle_Enhanced_Contact_Capability_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          An array of structures containing:
+          <ul>
+            <li>a dictionary mapping the channel properties to their values.</li>
+            <li>an array of additional allowed properties</li>
+          </ul>
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Returns an array of enhanced capabilities for the given contact handles.
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+          <tp:docstring>
+            The handle does not represent a contact. Zero is always invalid.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
+    <signal name="ContactCapabilitiesChanged"
+            tp:name-for-bindings="Contact_Capabilities_Changed">
+      <arg name="handle" type="u" tp:type="Contact_Handle">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A contact handle.</p>
+        </tp:docstring>
+      </arg>
+      <arg name="caps" type="a(a{sv}as)"
+           tp:type="Enhanced_Contact_Capability[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          All the capabilities of the contact
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Announce that there has been a change of capabilities on the
+          given handle.</p>
+      </tp:docstring>
+    </signal>
+
+    <tp:struct name="Enhanced_Contact_Capability"
+               array-name="Enhanced_Contact_Capability_List">
+      <tp:docstring>
+        A struct representing a capability posessed by a contact,
+        as returned by GetContactCapabilities on the ContactCapabilities
+        interface. The channel creation will succeed if the request contains
+        all the Fixed_Properties will the values specified in this struct. The
+        request can contain additional properties from Allowed_Properties. If
+        the request contains a property which does not belong to
+        Fixed_Properties nor to Allowed_Properties, the request will fail.
+      </tp:docstring>
+      <tp:member type="a{sv}" tp:type="Channel_Class"
+                 name="Fixed_Properties">
+        <tp:docstring>
+          A dictionary mapping the channel properties to their values.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="as" name="Allowed_Properties">
+        <tp:docstring>
+          An array of additional allowed properties.
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+  <tp:mapping name="Contact_Handle_Enhanced_Contact_Capability_Map"
+              array-name="Contact_Handle_Enhanced_Contact_Capability_Map_List">
+    <tp:docstring>A mapping from contact handle to their capabilities.
+    </tp:docstring>
+    <tp:member type="u" name="Key" tp:type="Contact_Handle">
+      <tp:docstring>
+        A contact handle.
+      </tp:docstring>
+    </tp:member>
+    <tp:member type="a(a{sv}as)" name="Value"
+               tp:type="Enhanced_Contact_Capability[]">
+      <tp:docstring>
+        The contact capabilities.
+      </tp:docstring>
+    </tp:member>
+  </tp:mapping>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/xml/Makefile.am b/xml/Makefile.am
index abf87505..b3d77650 100644
--- a/xml/Makefile.am
+++ b/xml/Makefile.am
@@ -16,7 +16,8 @@ SPECS = MissionControl.xml \
 	Client.xml \
 	Client_Approver.xml \
 	Client_Handler.xml \
-	Client_Observer.xml
+	Client_Observer.xml \
+        Connection_Interface_Contact_Capabilities.xml
 
 
 SPECS_GEN = ${SPECS:.xml=-gen.xml}