Start developement.

1 files changed, 191 insertions, 0 deletions

diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
new file mode 100644
index 0000000..1020190
--- /dev/null
+++ b/spec/Connection_Interface_Contacts.xml
@@ -0,0 +1,191 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contacts" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright> Copyright (C) 2005-2008 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.Contacts">
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+    <tp:added version="0.17.9"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>This interface allows many attributes of many contacts to be
+        obtained in a single D-Bus round trip.</p>
+
+      <p>Each contact attribute has an string identifier
+        (<tp:type>Contact_Attribute</tp:type>), which is namespaced
+        by the D-Bus interface which defines it.</p>
+    </tp:docstring>
+
+    <tp:simple-type name="Contact_Attribute" type="s">
+      <tp:docstring>
+        A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character
+        and an identifier for an attribute defined by that interface. The
+        attribute identifier SHOULD be in lower case.
+
+        <tp:rationale>
+          These aren't D-Bus core Properties, and we want them to look visibly
+          different.
+        </tp:rationale>
+      </tp:docstring>
+    </tp:simple-type>
+
+    <tp:mapping name="Single_Contact_Attributes_Map">
+      <tp:docstring>
+        Some of the attributes of a single contact.
+      </tp:docstring>
+
+      <tp:member type="s" tp:type="Contact_Attribute" name="Attribute">
+        <tp:docstring>
+          The name of the attribute
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member type="v" name="Value">
+        <tp:docstring>
+          The value of the attribute
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <tp:mapping name="Contact_Attributes_Map">
+      <tp:docstring>Mapping returned by
+        <tp:member-ref>GetContactAttributes</tp:member-ref>, representing a
+        collection of Contacts and their requested 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{sv}" tp:type="Single_Contact_Attributes_Map"
+        name="Attributes">
+        <tp:docstring>
+          Attributes of that contact
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <property name="ContactAttributeInterfaces" access="read" type="as"
+      tp:type="DBus_Interface[]"
+      tp:name-for-bindings="Contact_Attribute_Interfaces">
+      <tp:docstring>
+        A list of D-Bus interfaces for which
+        <tp:member-ref>GetContactAttributes</tp:member-ref> is expected to work.
+        This cannot change during the lifetime of the Connection.
+      </tp:docstring>
+    </property>
+
+    <method name="GetContactAttributes"
+      tp:name-for-bindings="Get_Contact_Attributes">
+      <tp:docstring>
+        Return any number of contact attributes for the given handles.
+      </tp:docstring>
+
+      <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring>
+          An array of handles representing contacts.
+        </tp:docstring>
+      </arg>
+
+      <arg direction="in" name="Interfaces" type="as"
+        tp:type="DBus_Interface[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A list of strings indicating which D-Bus interfaces the calling
+            process is interested in. All supported attributes from these
+            interfaces, whose values can be obtained without additional network
+            activity, will be in the reply.</p>
+
+          <p>Connection managers SHOULD ignore interfaces requested which they
+            do not support (i.e. those not mentioned in the
+            <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>
+            property.)</p>
+
+          <tp:rationale>
+            <p>This simplifies client-side code. Clients which care may
+              distinguish between unsupported interfaces (e.g. this Connection
+              does not support Avatars), and interfaces on which no information
+              is known for these contacts (e.g. we don't know the avatar tokens
+              of any of the contacts, so we omitted them all) by inspecting
+              <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>.</p>
+          </tp:rationale>
+
+          <p>Attributes from the interface
+            <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref>
+            are always returned, and need not be requested explicitly.</p>
+
+          <p>As well as returning cached information immediately, the
+            connection MAY start asynchronous requests to obtain better
+            values for the contact attributes. If better values are later
+            obtained by this process, they will be indicated with the usual
+            signals (such as <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">AliasesChanged</tp:dbus-ref>).</p>
+
+          <tp:rationale>
+            For instance, an XMPP connection manager could download vCards
+            in response to a request for <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface">Aliasing</tp:dbus-ref>
+            attributes.
+          </tp:rationale>
+        </tp:docstring>
+        <tp:changed version="0.19.2">
+          requesting information for interfaces not mentioned in
+          <tp:member-ref>ContactAttributeInterfaces</tp:member-ref> is no
+          longer an error. Be aware that older connection managers may still
+          consider this an error.
+        </tp:changed>
+      </arg>
+
+      <arg direction="in" name="Hold" type="b">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>If true, all handles that appear as keys in the result have been
+            held on behalf of the calling process, as if by a call to
+            <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>.
+            (If <tp:dbus-ref namespace="ofdT.Connection"
+              >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the
+            case in all new connection managers, this has no effect.)</p>
+
+          <tp:rationale>
+            <p>For further round-trip avoidance.</p>
+          </tp:rationale>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" type="a{ua{sv}}" name="Attributes"
+        tp:type="Contact_Attributes_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A dictionary mapping the contact handles to contact attributes.
+            If any of the requested handles are in fact invalid, they are
+            simply omitted from this mapping. 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>Each contact's attributes will always include at least the
+            identifier that would be obtained by inspecting the handle
+            (<code>org.freedesktop.Telepathy.Connection/contact-id</code>).</p>
+        </tp:docstring>
+      </arg>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+      </tp:possible-errors>
+    </method>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->