[telepathy-doc/master] Initial work on TpContact

[Davyd Madeley]

---
 docs/book/C/contactinfo.xml             |   30 ++++++++++++++++++++++--
 docs/examples/glib_get_roster/example.c |   37 ++++++++++++++++++------------
 2 files changed, 49 insertions(+), 18 deletions(-)

diff --git a/docs/book/C/contactinfo.xml b/docs/book/C/contactinfo.xml
index 666f40b..5693e8e 100644
--- a/docs/book/C/contactinfo.xml
+++ b/docs/book/C/contactinfo.xml
@@ -25,7 +25,7 @@
   the <link linkend="sect.contactinfo.contacts">Contacts</link> interface to
   bulk request the intial state.
  </para>
-  
+
  <sect1 id="sect.contactinfo.contacts">
   <title>Contacts</title>
   <para>
@@ -130,8 +130,8 @@
   <sect2 id="sect.contactinfo.contacts.receiving-updates">
    <title>Receiving Updates</title>
    <para>
-    While <interfacename>Contacts</interfacename>/
-    <methodname>GetContactAttributes</methodname> allows us to
+    While <interfacename>Contacts</interfacename>/<methodname>GetContactAttributes</methodname>
+    allows us to
     bulk-request lots of information about a contact. It does not provide a
     mechanism to receive signals to notify the client of changes to a contact
     (e.g., their alias, avatar, location, status, etc.).
@@ -140,6 +140,30 @@
    </para>
   </sect2>
 
+  <sect2 id="sect.contactinfo.contacts.glib">
+   <title>telepathy-glib &mdash; TpContact</title>
+
+   <para>
+    <application>telepathy-glib</application> provides an class specifically
+    for managing information relating to a contact,
+    <classname>TpContact</classname>.
+   </para>
+
+   <para>
+    A collection of <classname>TpContact</classname> instances can be
+    created by calling
+    <function>tp_connection_get_contacts_by_handle</function> (or
+    <function>tp_connection_get_contacts_by_id</function>).
+    <application>telepathy-glib</application> takes care of tracking
+    <classname>TpContact</classname> objects, so requesting the same contact
+    multiple times is safe (and results in the same object being returned).
+    To hold on to a <classname>TpContact</classname> you must reference it
+    (i.e. using <function>g_object_ref</function> or using it in a way that
+    implicitly references &mdash; e.g. adding it to a
+    <classname>GtkListStore</classname>).
+   </para>
+  </sect2>
+
  </sect1>
 
  <sect1 id="sect.contactinfo.presence">
diff --git a/docs/examples/glib_get_roster/example.c b/docs/examples/glib_get_roster/example.c
index 2597513..1e8b780 100644
--- a/docs/examples/glib_get_roster/example.c
+++ b/docs/examples/glib_get_roster/example.c
@@ -28,6 +28,23 @@ handle_error (const GError *error)
 }
 
 static void
+contact_notify_cb (TpContact	*contact,
+		   GParamSpec	*pspec,
+		   gpointer	 user_data)
+{
+	if (pspec)
+	{
+		g_print (" %% parameter updated %s\n", pspec->name);
+	}
+
+	g_print ("  - %s (%s)\t\t%s - %s\n",
+			tp_contact_get_alias (contact),
+			tp_contact_get_identifier (contact),
+			tp_contact_get_presence_status (contact),
+			tp_contact_get_presence_message (contact));
+}
+
+static void
 contacts_ready (TpConnection		*conn,
 		guint			 n_contacts,
 		TpContact * const	*contacts,
@@ -50,11 +67,11 @@ contacts_ready (TpConnection		*conn,
 	{
 		TpContact *contact = contacts[i];
 
-		g_print ("  - %s (%s)\t\t%s - %s\n",
-				tp_contact_get_alias (contact),
-				tp_contact_get_identifier (contact),
-				tp_contact_get_presence_status (contact),
-				tp_contact_get_presence_message (contact));
+		g_object_ref (contact);
+		g_signal_connect (contact, "notify",
+				G_CALLBACK (contact_notify_cb), NULL);
+
+		contact_notify_cb (contact, NULL, NULL);
 	}
 }
 
@@ -235,16 +252,6 @@ conn_ready (TpConnection	*conn,
 		g_hash_table_destroy (request);
 		/* end ex.channel.requesting.glib.ensure */
 	}
-
-	/* check if the SimplePresence interface is available */
-	if (tp_proxy_has_interface_by_id (conn,
-		TP_IFACE_QUARK_CONNECTION_INTERFACE_SIMPLE_PRESENCE))
-	{
-		tp_cli_connection_interface_simple_presence_connect_to_presences_changed (
-				conn, presences_changed_cb,
-				NULL, NULL, NULL, &error);
-		handle_error (error);
-	}
 }
 
 static void
-- 
1.5.6.5