<?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">
    <tp:added version="0.21.1">(as stable API)</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>
<!-- Excluding these two because there's been no conclusion regarding my mail
     to standards@xmpp.org about adding these two to their list:

        <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 returned client types are those for the resource whose
        presence will be retreived using the
        <tp:dbus-ref namespace="ofdT.Connection.Interface">SimplePresence</tp:dbus-ref>
        interface.</p>

      <p>For example, if a contact has two resources:</p>

      <ul>
        <li>their phone, with presence "available"; and</li>
        <li>their 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 because that is the more
      available resource. If at some later time the contact's phone's presence
      changes to "away", the
      <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will
      notify that the contact's client types attribute 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_Types" tp:type="Contact_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 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:type="Contact_Client_Type[]">
        <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:type="Contact_Client_Type[]">
        <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:type="Contact_Client_Type[]">
      <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>

    <tp:simple-type name="Contact_Client_Type" type="s"
      array-name="Contact_Client_Type_List">
      <tp:docstring>A string representing a single client type of a
        contact.</tp:docstring>
    </tp:simple-type>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
