Update text on requesting channels

3 files changed, 173 insertions, 67 deletions

diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
index a04431c..240c730 100644
--- a/docs/book/C/channel.xml
+++ b/docs/book/C/channel.xml
@@ -352,76 +352,180 @@
    <sect2 id="sect.channel.requesting.glib">
     <title>telepathy-glib</title>
 
-    <para>
-     <xref linkend="table.channel.requesting.glib"/> shows the respective
-     functions for calling <methodname>CreateChannel</methodname> and
-     <methodname>EnsureChannel</methodname> using
-     <application>telepathy-glib</application>.
-    </para>
+    <sect3 id="sect.channel.requesting.glib.cd">
+     <title>From the Channel Dispatcher</title>
 
-    <table id="table.channel.requesting.glib">
-     <title>telepathy-glib Functions for Requesting Channels</title>
-     <tgroup cols="2">
-      <thead>
-       <row>
-        <entry>From the...</entry>
-	<entry>Method</entry>
-	<entry>telepathy-glib Function</entry>
-       </row>
-      </thead>
-      <tbody>
-       <row>
-        <entry morerows="1" valign="middle">Channel Dispatcher</entry>
-	<entry><methodname>CreateChannel</methodname></entry>
-	<entry><function>tp_cli_channel_dispatcher_call_create_channel</function></entry>
-       </row>
-       <row>
-        <entry><methodname>EnsureChannel</methodname></entry>
-	<entry><function>tp_cli_channel_dispatcher_call_ensure_channel</function></entry>
-       </row>
-       <row>
-        <entry morerows="1" valign="middle">Connection</entry>
-	<entry><methodname>CreateChannel</methodname></entry>
-	<entry><function>tp_cli_connection_interface_requests_call_create_channel</function></entry>
-       </row>
-       <row>
-        <entry><methodname>EnsureChannel</methodname></entry>
-	<entry><function>tp_cli_connection_interface_requests_call_ensure_channel</function></entry>
-       </row>
-      </tbody>
-     </tgroup>
-    </table>
+     <para>
+      Requesting channels from the Channel Dispatcher is the generally
+      preferred way to create or ensure channels. telepathy-glib provides
+      a class <classname>TpAccountChannelRequest</classname> that you can
+      use to make channel requests that either you or another client can
+      handle.
+     </para>
 
-    <para>
-     <xref linkend="ex.channel.requesting.glib.ensure"/>
-     shows ensuring a channel directly from a Connection.
-    </para>
+     <para>
+      There are four main methods available via the
+      <classname>TpAccountChannelRequest</classname> class:
+     </para>
+     <itemizedlist>
+      <listitem><para>ensure;</para></listitem>
+      <listitem><para>create;</para></listitem>
+      <listitem><para>ensure and handle; and</para></listitem>
+      <listitem><para>create and handle.</para></listitem>
+     </itemizedlist>
 
-    <example id="ex.channel.requesting.glib.ensure"
-             file="glib_get_roster/example.c">
-     <title>Ensuring a Channel from a Connection with telepathy-glib</title>
-    </example>
+     <para>
+      The first two methods request a channel that can be dispatched to any
+      channel handler (see
+      <xref linkend="sect.channel-dispatcher.clients"/>). You may optionally
+      provide a name for the preferred Handler for this channel request. If
+      you want to request a channel, but you don't care who handles it, use
+      these methods.
+      <xref linkend="ex.channel.requesting.glib.cd.ensure"/> is an example
+      of ensuring a channel this way, the channel is most likely going to be
+      handled by Empathy or some other chat client.
+     </para>
 
-    <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>
+      The second two methods request a channel that you wish to handle
+      yourself. These methods work by creating a temporary Handler and
+      giving its name as the preferred Handler for the channel request. If
+      you want to request a channel to use yourself (and you want to get a
+      <classname>TpChannel</classname> in your callback), use these methods.
+     </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
-     generally preferred 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.cd.ensure"
+              file="glib_dbus_tube/offer-tube.c">
+      <title>Ensuring a Channel via the Channel Dispatcher</title>
+     </example>
 
-    <example id="ex.channel.requesting.glib.tpchannel"
-             file="glib_get_roster/example.c">
-     <title>Using tp_channel_new_from_properties</title>
-    </example>
+     <para>
+      These methods follow the GIO async pattern, so you must call the
+      appropriate "finish" method in the callback. Checking the return value
+      and error let's you know the channel was successfully handled.
+      <classname>TpChannel</classname>s have the <literal>core</literal>
+      feature prepared.
+     </para>
+
+     <table id="table.channel.requesting.glib.cd">
+      <title>Channel Request Methods</title>
+      <tgroup cols="3">
+       <thead>
+        <row>
+	 <entry>Operation</entry>
+	 <entry>Launch Method/Finish Method</entry>
+	 <entry>Return Value</entry>
+	</row>
+       </thead>
+       <tbody>
+        <row>
+	 <entry>Create</entry>
+	 <entry>
+	  <function>tp_account_channel_request_create_channel_async</function>
+	  <function>tp_account_channel_request_create_channel_finish</function>
+	 </entry>
+	 <entry>True if channel successfully handled</entry>
+	</row>
+	<row>
+	 <entry>Ensure</entry>
+	 <entry>
+	  <function>tp_account_channel_request_ensure_channel_async</function>
+	  <function>tp_account_channel_request_ensure_channel_finish</function>
+	 </entry>
+	 <entry>True if channel successfully handled</entry>
+	</row>
+	<row>
+	 <entry>Create and Handle</entry>
+	 <entry>
+	  <function>tp_account_channel_request_create_and_handle_channel_async</function>
+	  <function>tp_account_channel_request_create_and_handle_channel_finish</function>
+	 </entry>
+	 <entry><classname>TpChannel</classname> if successful</entry>
+	</row>
+	<row>
+	 <entry>Ensure and Handle</entry>
+	 <entry>
+	  <function>tp_account_channel_request_ensure_and_handle_channel_async</function>
+	  <function>tp_account_channel_request_ensure_and_handle_channel_finish</function>
+	 </entry>
+	 <entry><classname>TpChannel</classname> if successful</entry>
+	</row>
+       </tbody>
+      </tgroup>
+     </table>
+
+     <para>
+      If you are the channel handler, and the channel you've requested can
+      be ensured by other clients (e.g. a text-channel), you should keep the
+      <classname>TpAccountChannelRequest</classname> and listen to the
+      <methodname>re-handled</methodname> signal. This signal will be
+      emitted whenever someone else ensures the channel, and can be used to
+      bring attention to the channel.
+     </para>
+
+     <tip>
+      <title>User Action Times</title>
+      <para>
+       When handling a channel, the user action time can be used for things
+       like focus stealing prevention.
+      </para>
+      <para>
+       User action times in Telepathy are subtley different to event times
+       in X11. To help convert between them, telepathy-glib provides to
+       convenience functions:
+       <function>tp_user_action_time_from_x11</function> and
+       <function>tp_user_action_time_should_present</function>.
+      </para>
+     </tip>
+
+    </sect3>
+
+    <sect3 id="sect.channel.requesting.glib.conn">
+     <title>From a Connection</title>
+
+     <warning><para>
+      It is possible to request a channel directly from a Connection.
+      telepathy-glib provides no high-level API to do this, because it's
+      only intended to be used by the Channel Dispatcher, and not by
+      Telepathy clients. Channels requested directly will be unknown to the
+      Channel Dispatcher.
+     </para></warning>
+
+     <para>
+      <xref linkend="ex.channel.requesting.glib.ensure"/>
+      shows ensuring a channel directly from a Connection.
+     </para>
+
+     <example id="ex.channel.requesting.glib.ensure"
+              file="glib_get_roster/example.c">
+      <title>Ensuring a Channel from a Connection with telepathy-glib</title>
+     </example>
+    </sect3>
+
+    <sect3 id="ect.channel.requesting.glib.tpchannel">
+     <title>TpChannel</title>
+
+     <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
+      generally preferred 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>
+    </sect3>
 
    </sect2>
 
diff --git a/docs/examples/glib_dbus_tube/accept-tube.c b/docs/examples/glib_dbus_tube/accept-tube.c
index d846bf5..c583636 100644
--- a/docs/examples/glib_dbus_tube/accept-tube.c
+++ b/docs/examples/glib_dbus_tube/accept-tube.c
@@ -176,7 +176,7 @@ _account_ready (GObject *account,
       NULL);
 
   request = tp_account_channel_request_new (TP_ACCOUNT (account),
-      props, G_MAXINT64 /* current time */);
+      props, TP_USER_ACTION_TIME_CURRENT_TIME);
 
   tp_account_channel_request_ensure_channel_async (request,
       NULL, NULL, _muc_channel_ready, NULL);
diff --git a/docs/examples/glib_dbus_tube/offer-tube.c b/docs/examples/glib_dbus_tube/offer-tube.c
index f3c554b..2c8c652 100644
--- a/docs/examples/glib_dbus_tube/offer-tube.c
+++ b/docs/examples/glib_dbus_tube/offer-tube.c
@@ -148,7 +148,7 @@ _muc_channel_ready (GObject *request,
   request2 = tp_account_channel_request_new (
       tp_account_channel_request_get_account (
         TP_ACCOUNT_CHANNEL_REQUEST (request)),
-      props, G_MAXINT64 /* current time */);
+      props, TP_USER_ACTION_TIME_CURRENT_TIME);
 
   tp_account_channel_request_create_and_handle_channel_async (request2,
       NULL, _tube_channel_ready, NULL);
@@ -171,6 +171,7 @@ _account_ready (GObject *account,
   if (!tp_proxy_prepare_finish (account, res, &error))
     handle_error (error);
 
+  /* begin ex.channel.requesting.glib.cd.ensure */
   props = tp_asv_new (
       TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_TEXT,
       TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, TP_TYPE_HANDLE, TP_HANDLE_TYPE_ROOM,
@@ -178,7 +179,7 @@ _account_ready (GObject *account,
       NULL);
 
   request = tp_account_channel_request_new (TP_ACCOUNT (account),
-      props, G_MAXINT64 /* current time */);
+      props, TP_USER_ACTION_TIME_CURRENT_TIME);
 
   /* ensure this channel, but let the default handler handle it */
   tp_account_channel_request_ensure_channel_async (request,
@@ -186,6 +187,7 @@ _account_ready (GObject *account,
 
   g_hash_table_destroy (props);
   g_object_unref (request);
+  /* end ex.channel.requesting.glib.cd.ensure */
 }