telepathy-glib: Update Connection.Interface.Contacts spec

[Xavier Claessens]

Module: telepathy-glib
Branch: master
Commit: 38151925c854b2051ddf6118d882457c806c897f
URL:    http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=38151925c854b2051ddf6118d882457c806c897f

Author: Xavier Claessens <xavier.claessens at collabora.co.uk>
Date:   Tue May  8 11:12:28 2012 +0200

Update Connection.Interface.Contacts spec

---

 docs/reference/telepathy-glib-sections.txt |    5 ++
 spec/Connection_Interface_Contacts.xml     |   58 ++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 0 deletions(-)

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 1564368..b5d0909 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -1219,6 +1219,9 @@ TpSvcConnectionInterfaceContactsClass
 tp_svc_connection_interface_contacts_get_contact_attributes_impl
 tp_svc_connection_interface_contacts_implement_get_contact_attributes
 tp_svc_connection_interface_contacts_return_from_get_contact_attributes
+tp_svc_connection_interface_contacts_get_contact_by_id_impl
+tp_svc_connection_interface_contacts_implement_get_contact_by_id
+tp_svc_connection_interface_contacts_return_from_get_contact_by_id
 <SUBSECTION Standard>
 TP_IS_SVC_CONNECTION_INTERFACE_CONTACTS
 TP_SVC_CONNECTION_INTERFACE_CONTACTS
@@ -4530,6 +4533,8 @@ tp_cli_connection_interface_cellular_signal_callback_imsi_changed
 tp_cli_connection_interface_contacts_call_get_contact_attributes
 tp_cli_connection_interface_contacts_callback_for_get_contact_attributes
 tp_cli_connection_interface_contacts_run_get_contact_attributes
+tp_cli_connection_interface_contacts_call_get_contact_by_id
+tp_cli_connection_interface_contacts_callback_for_get_contact_by_id
 </SECTION>
 
 <SECTION>
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: -->