[next] telepathy-spec: Add GetContactByID

[Simon McVittie]

Module: telepathy-spec
Branch: next
Commit: 5a06a27ca320f115e0cbeab40b867433282d1e62
URL:    http://cgit.freedesktop.org/telepathy/telepathy-spec/commit/?id=5a06a27ca320f115e0cbeab40b867433282d1e62

Author: Xavier Claessens <xavier.claessens at collabora.co.uk>
Date:   Tue May  8 10:56:03 2012 +0200

Add GetContactByID

---

 spec/Connection_Interface_Contacts.xml |   58 ++++++++++++++++++++++++++++++++
 1 files changed, 58 insertions(+), 0 deletions(-)

diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
index 1020190..748933a 100644
--- a/spec/Connection_Interface_Contacts.xml
+++ b/spec/Connection_Interface_Contacts.xml
@@ -186,6 +186,64 @@
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
       </tp:possible-errors>
     </method>
+
+    <method name="GetContactByID"
+      tp:name-for-bindings="Get_Contact_By_ID">
+      <tp:added version="0.UNRELEASED"/>
+      <tp:docstring>
+        Return any number of contact attributes for the given identifier.
+        <tp:rationale>
+          This is for a single identifier to make it simpler to use for the most
+          common use case. For multiple contacts case,
+          <tp:member-ref>GetContactAttributes</tp:member-ref> should be used.
+        </tp:rationale>
+      </tp:docstring>
+
+      <arg direction="in" name="Identifier" type="s">
+        <tp:docstring>
+          An identifier representing a contact.
+        </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>See <tp:member-ref>GetContactAttributes</tp:member-ref> for
+            details.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" name="Handle" type="u" tp:type="Contact_Handle">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The contact's handle, as returned by <tp:dbus-ref
+          namespace="ofdT.Connection">RequestHandles</tp:dbus-ref></p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" type="a{sv}" name="Attributes"
+        tp:type="Single_Contact_Attributes_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>All supported attributes of the contact on
+            the given interfaces that can be returned without network
+            round-trips. 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>The 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:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+      </tp:possible-errors>
+    </method>
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->