[telepathy-doc/master] Setting up channels with tp-glib

[Davyd Madeley]

---
 docs/book/C/basics.xml                  |   13 +++++++++++
 docs/book/C/channel.xml                 |   34 +++++++++++++++++++++++++++++-
 docs/examples/glib_get_roster/example.c |    4 +++
 3 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/docs/book/C/basics.xml b/docs/book/C/basics.xml
index d43b08c..e5c70ce 100644
--- a/docs/book/C/basics.xml
+++ b/docs/book/C/basics.xml
@@ -1132,6 +1132,19 @@ for (i = 0; i < channels->len; i++)
 }]]></programlisting>
        </example>
 
+       <tip>
+        <title>G_VALUE_TYPE_NAME()</title>
+        <para>
+         The macro <function>G_VALUE_TYPE_NAME</function> can also be useful
+         for unpacking Telepathy types.
+        </para>
+        <para>
+         For example the listed type name of
+         <type>TP_STRUCT_TYPE_CHANNEL_DETAILS_LIST</type> is given as
+         <literal>GPtrArray_GValueArray_DBusGObjectPath+GHashTable_gchararray+GValue___</literal>.
+        </para>
+       </tip>
+
       </sect3>
 
       <sect3 id="sect.basics.language-bindings.telepathy-glib.maps">
diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
index c7c877a..adf0138 100644
--- a/docs/book/C/channel.xml
+++ b/docs/book/C/channel.xml
@@ -299,12 +299,42 @@
     <title>telepathy-glib</title>
     
     <para>
-     Telepathy-glib provides the
+     <application>telepathy-glib</application> maps
+     <methodname>CreateChannel</methodname> and
+     <methodname>EnsureChannel</methodname> to the functions
      <ulink url="&url_telepathy_glib_base;connection-requests.html#tp-cli-connection-interface-requests-call-create-channel"><function>tp_cli_connection_interface_requests_call_create_channel()</function></ulink>
      and <ulink url="&url_telepathy_glib_base;connection-requests.html#tp-cli-connection-interface-requests-call-ensure-channel"><function>tp_cli_connection_interface_requests_call_ensure_channel()</function></ulink>
-     functions for this purpose.
+     respectively. <xref linkend="ex.channel.requesting.glib.ensure"/>
+     shows how this is done.
+    </para>
+
+    <example id="ex.channel.requesting.glib.ensure"
+             file="glib_get_roster/example.c">
+     <title>Ensuring a Channel With telepathy-glib</title>
+    </example>
+
+    <para>
+     The <classname>TpChannel</classname> is used to work with channels in
+     <application>telepathy-glib</application>. It also provides API to help
+     use the <link linkend="sect.channel.groups">Groups interface</link>,
+     that is present on many channels.
     </para>
 
+    <para>
+     A <classname>TpChannel</classname> can either be created using
+     <function>tp_channel_new</function> or
+     <function>tp_channel_new_from_properties</function>. The latter is more
+     useful when you've created a channel using the
+     <interfacename>Requests</interfacename> interface,
+     as you can just pass in the returned property map, as shown in
+     <xref linkend="ex.channel.requesting.glib.tpchannel"/>.
+    </para>
+
+    <example id="ex.channel.requesting.glib.tpchannel"
+             file="glib_get_roster/example.c">
+     <title>Using tp_channel_new_from_properties</title>
+    </example>
+
    </sect2>
 
   </sect1>
diff --git a/docs/examples/glib_get_roster/example.c b/docs/examples/glib_get_roster/example.c
index 8bcdcce..2760328 100644
--- a/docs/examples/glib_get_roster/example.c
+++ b/docs/examples/glib_get_roster/example.c
@@ -57,6 +57,7 @@ new_channels_cb (TpConnection		*conn,
 		GHashTable *map = g_value_get_boxed (
 				g_value_array_get_nth (channel, 1));
 
+		/* begin ex.channel.requesting.glib.tpchannel */
 		const char *type = tp_asv_get_string (map,
 				TP_IFACE_CHANNEL ".ChannelType");
 
@@ -72,6 +73,7 @@ new_channels_cb (TpConnection		*conn,
 			tp_channel_call_when_ready (channel,
 					channel_ready, NULL);
 		}
+		/* end ex.channel.requesting.glib.tpchannel */
 	}
 }
 
@@ -128,6 +130,7 @@ conn_ready (TpConnection	*conn,
 				NULL, NULL, NULL, &error);
 		handle_error (error);
 
+		/* begin ex.channel.requesting.glib.ensure */
 		/* explicitly ask for the publish and subscribe contact lists
 		 * these will be announced by NewChannels, so we don't need
 		 * to handle their callbacks (this does mean we also can't
@@ -150,6 +153,7 @@ conn_ready (TpConnection	*conn,
 				conn, -1, request, NULL, NULL, NULL, NULL);
 
 		g_hash_table_destroy (request);
+		/* end ex.channel.requesting.glib.ensure */
 	}
 }
 
-- 
1.5.6.5