Merge branch 'client-types'

Conflicts:
	src/connection.c
	src/debug.c
	src/debug.h
	src/presence-cache.c

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

3 files changed, 206 insertions, 1 deletions

diff --git a/extensions/Connection_Interface_Client_Types.xml b/extensions/Connection_Interface_Client_Types.xml
new file mode 100644
index 000000000..0822122aa
--- /dev/null
+++ b/extensions/Connection_Interface_Client_Types.xml
@@ -0,0 +1,203 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Client_Types"
+  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.ClientTypes.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>
+        <li>game (a gaming device)</li>
+      </ul>
+
+      <p>If the empty list is given as the client types, this means that
+        details about the contact's client types are 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 an array (with
+      one element: "phone") as the client types 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 have 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_Types">
+        <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 array 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
+          types 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="RequestClientTypes" tp:name-for-bindings="Request_Client_Types">
+      <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_Types" 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-types" 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 types are 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 9748d587c..622498179 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -24,7 +24,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_Types.xml
 
 noinst_LTLIBRARIES = libgabble-extensions.la
 
diff --git a/extensions/all.xml b/extensions/all.xml
index ed04be95d..ab86682a6 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -46,6 +46,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA</p>
 <xi:include href="Connection_Interface_Gabble_Decloak.xml"/>
 <xi:include href="Connection_Interface_Mail_Notification.xml"/>
 <xi:include href="Connection_Future.xml"/>
+<xi:include href="Connection_Interface_Client_Types.xml"/>
 
 <xi:include href="Gabble_Plugin_Gateways.xml"/>
 <xi:include href="Gabble_Plugin_Test.xml"/>