[Telepathy-commits] [telepathy-spec/master] First draft of Connection.Interface.ContactCapabilities.DRAFT

[Alban Crequy]

---
 spec/Connection_Interface_Contact_Capabilities.xml |  105 ++++++++++++++++++++
 spec/all.xml                                       |    1 +
 2 files changed, 106 insertions(+), 0 deletions(-)
 create mode 100644 spec/Connection_Interface_Contact_Capabilities.xml

diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml
new file mode 100644
index 0000000..35acb09
--- /dev/null
+++ b/spec/Connection_Interface_Contact_Capabilities.xml
@@ -0,0 +1,105 @@
+<?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 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright (C) 2005, 2006 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 for connections where it is possible to know what channel
+        types may be requested 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 when given
+        a request with the given type and handle.</p>
+
+      <p>Capabilities pertain to particular contact handles, and represent
+        activities such as having a text chat or a voice call with the user.
+        The activities are represented by the D-Bus interface name of the
+        channel type for that activity.</p>
+
+      <p>The generic capability flags are defined by
+        <tp:type>Connection_Capability_Flags</tp:type>.</p>
+
+      <p>In addition, channel types may have type specific capability flags of
+        their own, which are described in the documentation for each channel
+        type.</p>
+
+      <p>This interface also provides for user interfaces notifying the
+        connection manager of what capabilities to advertise for the user. This
+        is done by using the AdvertiseCapabilities method, and deals with the
+        interface names of channel types and the type specific flags pertaining
+        to them which are implemented by available client processes.</p>
+    </tp:docstring>
+
+    <tp:changed version="0.17.8">Previously, this interface
+      also expressed capabilities of the connection itself, indicating what
+      sorts of channels could be requested (for instance, the ability to
+      open chatroom lists or chatrooms). However, this was never very
+      well-defined or consistent, and as far as we know it was never
+      implemented correctly. This usage is now deprecated.</tp:changed>
+
+    <!-- FIXME: are the type-specific flags sufficient, in a world that has
+    the Requests interface? It'd be nice if we could advertise capabilities
+    that are not defined in terms of a channel type but rather in terms of
+    a property or something, e.g. Channel.Interface.TLS.Secure for
+    individually TLS'd channels. -->
+
+    <method name="GetContactCapabilities">
+      <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>
+      <arg direction="out" type="a(a{sv}as)"
+           tp:type="Enhanced_Contact_Capability[]">
+        <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 enhenced capabilities for the given contact handles.
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <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:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+      </tp:possible-errors>
+    </method>
+
+    <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.</tp:docstring>
+      <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Fixed_Properties"/>
+      <tp:member type="as" name="Allowed_Properties"/>
+    </tp:struct>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/all.xml b/spec/all.xml
index 158efc5..6028e98 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -30,6 +30,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 <xi:include href="Connection_Interface_Aliasing.xml"/>
 <xi:include href="Connection_Interface_Avatars.xml"/>
 <xi:include href="Connection_Interface_Capabilities.xml"/>
+<xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
 <xi:include href="Connection_Interface_Contacts.xml"/>
 <!-- Never implemented, is a terrible API
 <xi:include href="Connection_Interface_Contact_Info.xml"/> -->
-- 
1.5.6.5