<?xml version="1.0" ?>
<node name="/Connection_Interface_Resources"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 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.Resources.DRAFT"
    tp:causes-havoc="experimental">
    <tp:added version="0.21.1">(draft 1)</tp:added>
    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>An interface on connections to show contact attributes for
        specific resources of a contact, if the protocol supports
        multiple resources. Resources are most common in XMPP, hence the
        name of this interface, but they are also present in MSN, where
        they are called points of presence.</p>

      <p>When a client requests some attribute of a contact using its
        handle on the connection, the CM uses an algorithm to choose the
        most appropriate resource for the job. If there is only one
        resource, then the choice is obvious. If, however, there is more
        than one resource connected at any one time, the CM either
        aggregates all appropriate information to return (in the case of
        capabilities), or chooses one specific resource (in the case of
        presence).</p>

      <p>Resources in XMPP have names, and it can be extremely useful
        for the user to be able to know which resources of a contact are
        online, providing the names are human-readable. Before now,
        resources have not been exposed in Telepathy, but this interface
        attempts to change this.</p>

      <p>When using this interface, it is a little like using the
        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface"
        >Contacts</tp:dbus-ref> interface, but only resource-specific
        attributes are ever returned. The resource-specific contact
        attributes are decided on by the CM, but XMPP's are listed
        below:</p>

      <ul>
        <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence/presence</tp:dbus-ref></li>
        <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities/capabilities</tp:dbus-ref></li>
        <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ClientTypes/client-types</tp:dbus-ref></li>
      </ul>

    </tp:docstring>

    <method name="GetResources" tp:name-for-bindings="Get_Resources">
      <tp:docstring>
        Return the resource information of the given contacts. If any
        of the contact attributes for specific resources of the given
        contacts' are not known return immediately without waiting for
        a reply.
      </tp:docstring>

      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          The contacts whose resource attributes should be returned.
        </tp:docstring>
      </arg>

      <arg direction="out" name="Resources" type="a{ua{sa{sv}}}"
        tp:type="Resources_Attributes_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The contacts' resources and the contact attributes specific
            to each resource. If contact attributes are not immediately
            known, the behaviour is defined by the interface; the
            attribute should either be omitted from the result or
            replaced with a default value.</p>

          <p>For every contact handle passed into this method, it is
            guaranteed that there will be a key in the returned map
            that corresponds to said handle. If there is no information
            regarding the contact the resource information map will be
            empty.</p>
        </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>

    <tp:enum name="Resources_Human_Readability" type="u">
      <tp:enumvalue suffix="Never" value="0">
        <tp:docstring>
          The resource string is never human-readable.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Maybe" value="1">
        <tp:docstring>
          The resource string might be human-readable.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <property name="ResourcesHumanReadable" type="u" access="read"
      tp:type="Resources_Human_Readability"
      tp:name-for-bindings="Resources_Human_Readable">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Whether the resources returned from <tp:member-ref>GetResources</tp:member-ref>
          are human readable or not.</p>

        <p>If the connection manager knows that all resource names are
          automatically generated, then the resource strings mean
          nothing to the user. Showing these strings in the UI would
          be confusing, so by setting this to
          Resources_Human_Readability_Never, the UI is advised not to
          show resources.</p>

        <p>If on the other hand, all resources are set to nice names
          (such as "office" or "home") then it might be wise to expose
          these strings in the UI, so this property would be set to
          Resources_Human_Readability_Maybe. This is the case in XMPP --
          most resources are set in a way that the user can deduce some
          information from them. The absence of an Always enum value is
          because in the case of XMPP, the resource string could be
          partially human-readable (as on Google Talk, where a resource
          of "home" is changed by the server to a unique string like
          "home_1234fdec") or not at all human-readable.</p>

      </tp:docstring>
    </property>

    <signal name="ResourcesUpdated" tp:name-for-bindings="Resources_Updated">
      <tp:docstring>
        Emitted when a contact has a resource added or removed, or any
        contact attribute for any resource changes.
      </tp:docstring>

      <arg name="Contact" type="u" tp:type="Contact_Handle">
        <tp:docstring>
          The contact.
        </tp:docstring>
      </arg>
      <arg name="Resources" tp:type="Resource_Information_Map"
        type="a{sa{sv}}">
        <tp:docstring>
          The contact's resource information. All resource information
          is given, not just the details which have changed.
        </tp:docstring>
      </arg>
    </signal>

    <tp:mapping name="Resource_Information_Map">
      <tp:docstring>
        A map of a contact's resources to their resource-specific
        information.
      </tp:docstring>

      <tp:member name="Key" type="s">
        <tp:docstring>
          <p>The name of the resource.</p>
        </tp:docstring>
      </tp:member>

      <tp:member name="Contact_Attributes" type="a{sv}"
        tp:type="Single_Contact_Attributes_Map">
        <tp:docstring>
          A map of contact attributes whose data is specific to this
          resource.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <tp:mapping name="Resources_Attributes_Map">
      <tp:docstring>Mapping returned by
        <tp:member-ref>GetResources</tp:member-ref>, representing a
        collection of Contacts, their resources, and their
        resource-specific contact attributes.</tp:docstring>

      <tp:member type="u" tp:type="Contact_Handle" name="Contact">
        <tp:docstring>
          A contact.
        </tp:docstring>
      </tp:member>

      <tp:member type="a{sa{sv}}" tp:type="Resource_Information_Map"
        name="Resources">
        <tp:docstring>
          A map of the contact's resources to their resource-specific
          information.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <tp:contact-attribute name="resources" type="a{sa{sv}}"
      tp:type="Resource_Information_Map">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The same mapping that would be returned by
          <tp:member-ref>GetResources</tp:member-ref> for this contact.</p>
      </tp:docstring>
    </tp:contact-attribute>

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