extensions: add Conn.I.ClientType draft

Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

3 files changed, 202 insertions, 1 deletions

diff --git a/extensions/Connection_Interface_Client_Type.xml b/extensions/Connection_Interface_Client_Type.xml
new file mode 100644
index 00000000..6be261c5
--- /dev/null
+++ b/extensions/Connection_Interface_Client_Type.xml
@@ -0,0 +1,199 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Client_Type"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright>Copyright (C) 2010 Collabora Ltd.</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.ClientType.DRAFT"
+    tp:causes-havoc="experimental">
+    <tp:added version="0.19.UNRELEASED">(as draft)</tp:added>
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface on connections to support protocols which allows users to
+        subscribe to the client types of their contacts.</p>
+
+      <p>One can connect to instant messaging networks on a huge variety of
+        devices, from PCs, to phones to consoles. It can be useful for users
+        to know what kind of device a contact is using so that he or she
+        can decide not to send that big file or start a video chat. This
+        interface exposes exactly this information for clients to display.</p>
+
+      <p>The client types are represented in strings, using the values
+        <a href="http://xmpp.org/registrar/disco-categories.html#client">
+        documented by the XMPP registrar</a> with some additional types
+        added for other protocols. A contact can set one or more client types
+        so this interface returns a list of strings to denote client types
+        for a contact. The well-known client types to be used are:</p>
+
+      <ul>
+        <li>bot</li>
+        <li>console (minimal non-GUI client used on dumb terminals or
+          text-only screens, <strong>not</strong> a games console)</li>
+        <li>handheld</li>
+        <li>pc</li>
+        <li>phone</li>
+        <li>web</li>
+        <li>sms (the client is not actually an instant messaging client
+          but all messages sent to this contact will be delivered as SMSs)</li>
+      </ul>
+
+      <p>If the empty list is given as the client types, this means that
+        details about the contact's client type is unknown. If there are
+        multiple resources of a contact online at one point in time, the
+        client types of the most available resource will be returned. In
+        other words, the client types are the types of the client whose
+        SimplePresence we see. For example, if a contact has two
+        resources:</p>
+
+      <ul>
+        <li>one his phone, with presence "available", and</li>
+        <li>one his pc, with presence "busy",</li>
+      </ul>
+
+      <p>then the methods in this interface will return the "phone" client type
+        as that is the more available resource. If some time later his phone's
+        presence moves to "away", then the
+        <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will notify
+        that his client type has changed from "phone" to "pc", because "busy"
+        is a more available presence than "away".</p>
+
+    </tp:docstring>
+
+    <tp:mapping name="Contact_Client_Types">
+      <tp:docstring>
+        A mapping from contact handle to client types.
+      </tp:docstring>
+      <tp:member type="u" tp:type="Contact_Handle" name="Contact">
+        <tp:docstring>
+          A contact.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="as" name="Client_Type">
+        <tp:docstring>
+          The contact's client types as documented earlier in this interface.
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <method name="GetClientTypes" tp:name-for-bindings="Get_Client_Types">
+      <tp:docstring>
+        Return the client types of the given contacts, if they are
+        already known. If any of the given contacts' client types are not known,
+        request their current client types, but return immediately without waiting
+        for a reply; if a reply with a non-empty client type is later received
+        for those contacts, the <tp:member-ref>ClientTypesUpdated</tp:member-ref>
+        signal will be emitted for them.
+
+        <tp:rationale>
+          This method is appropriate for "lazy" client type finding, for instance
+          displaying the client types (if available) of everyone in your contact
+          list.
+        </tp:rationale>
+      </tp:docstring>
+
+      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring>
+          The contacts whose client types should be returned or signalled.
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" name="Client_Types" type="a{uas}"
+        tp:type="Contact_Client_Types">
+        <tp:docstring>
+          The contacts' client types, if already known. Contacts whose client
+          typess are not already known are omitted from the mapping; contacts known
+          to have no client type information appear in the mapping with an empty
+          list.
+        </tp:docstring>
+      </arg>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+      </tp:possible-errors>
+    </method>
+
+    <method name="RequestClientType" tp:name-for-bindings="Request_Client_Type">
+      <tp:docstring>
+        Return the current client types of the given contact. If necessary, make
+        a request to the server for up-to-date information, and wait for a
+        reply.
+
+        <tp:rationale>
+          This method is appropriate for use in a "Contact Information..."
+          dialog; it can be used to show progress information (while waiting
+          for the method to return), and can distinguish between various error
+          conditions.
+        </tp:rationale>
+      </tp:docstring>
+
+      <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          The contact whose client types should be returned.
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" name="Client_Type" type="as">
+        <tp:docstring>
+          The contact's client types. It MAY be empty, indicating that no client
+          type information was found.
+        </tp:docstring>
+      </arg>
+
+      <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.InvalidHandle"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
+          <tp:docstring>
+            The requested contact does not allow the local user to see their
+            client type information.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
+    <signal name="ClientTypesUpdated" tp:name-for-bindings="Client_Types_Updated">
+      <tp:docstring>
+        Emitted when a contact's client types change or become known.
+      </tp:docstring>
+
+      <arg name="Contact" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          The contact.
+        </tp:docstring>
+      </arg>
+      <arg name="Client_Types" type="as">
+        <tp:docstring>
+          The contact's client types, or an empty list to indicate that nothing
+          is known about the contact's client types.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+    <tp:contact-attribute name="client-type" type="as">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The same mapping that would be returned by
+          <tp:member-ref>GetClientTypes</tp:member-ref> for this contact.
+          Omitted from the result if the contact's client type is not
+          known.</p>
+      </tp:docstring>
+    </tp:contact-attribute>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Makefile.am b/extensions/Makefile.am
index ba369af9..a54fa9bd 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -26,7 +26,8 @@ EXTRA_DIST = \
     OLPC_Channel_Type_BuddyView.xml \
     OLPC_Channel_Type_ActivityView.xml \
     Channel_Interface_Sasl_Authentication.xml \
-    Channel_Type_Server_Authentication.xml
+    Channel_Type_Server_Authentication.xml \
+    Connection_Interface_Client_Type.xml
 
 noinst_LTLIBRARIES = libgabble-extensions.la
 
diff --git a/extensions/all.xml b/extensions/all.xml
index 22827090..9dd9c6ce 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -48,6 +48,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA</p>
 <xi:include href="Channel_Interface_Conference.xml"/>
 <xi:include href="Connection_Interface_Mail_Notification.xml"/>
 <xi:include href="Connection_Future.xml"/>
+<xi:include href="Connection_Interface_Client_Type.xml"/>
 
 <xi:include href="Gabble_Plugin_Gateways.xml"/>
 <xi:include href="Gabble_Plugin_Test.xml"/>