summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDanielle Madeley <danielle.madeley@collabora.co.uk>2010-08-20 07:31:40 (GMT)
committerDanielle Madeley <danielle.madeley@collabora.co.uk>2010-08-20 07:31:40 (GMT)
commit5354ce2749f7cdf75c0e48b7404371a691510b50 (patch)
tree8ab4dba5d0099ac0c4bc190b1e28bbe6c40579c5
parent217856c2621a79a9d819f0d8efa5803efad1f7d2 (diff)
downloadtelepathy-doc-5354ce2749f7cdf75c0e48b7404371a691510b50.tar.gz
telepathy-doc-5354ce2749f7cdf75c0e48b7404371a691510b50.tar.xz
Notes on the context delay method
-rw-r--r--docs/book/C/channel-dispatcher.xml21
-rw-r--r--docs/examples/glib_mc5_observer/example2.c19
2 files changed, 37 insertions, 3 deletions
diff --git a/docs/book/C/channel-dispatcher.xml b/docs/book/C/channel-dispatcher.xml
index 11ce834..373b873 100644
--- a/docs/book/C/channel-dispatcher.xml
+++ b/docs/book/C/channel-dispatcher.xml
@@ -929,13 +929,28 @@
<classname>TpHandleChannelsContext</classname>; named after the D-Bus
method that triggers the callback. Each context object provides three
methods: accept, fail and delay; one of which must be called before
- the end of the callback. The Delay method is used if you have further
+ the end of the callback.
+ </para>
+ <para>
+ The Accept and Fail methods are used to return from the
+ <methodname>ObserveChannels</methodname> D-Bus method, either
+ successfully or with an error condition.
+ </para>
+ <para>
+ The Delay method is used if you have further
preparation to carry out before ultimately calling either Accept or
- Fail. You must reference the context object to hold it outside the
+ Fail. This is often used for things that need to be done before the
+ Handler is given the channel, like inspecting the pending message
+ queue. You must reference the context object to hold it outside the
callback.
+ <xref linkend="ex.channel-dispatcher.clients.impl.tpsimpleobserver"/>
+ shows an example of using the delay method.
</para>
- <!-- FIXME: example of Delay -->
+ <example id="ex.channel-dispatcher.clients.impl.tpsimpleobserver"
+ file="glib_mc5_observer/example2.c">
+ <title>Delaying Response to the Context Object</title>
+ </example>
</sect3>
diff --git a/docs/examples/glib_mc5_observer/example2.c b/docs/examples/glib_mc5_observer/example2.c
index 15ce7ce..634ade4 100644
--- a/docs/examples/glib_mc5_observer/example2.c
+++ b/docs/examples/glib_mc5_observer/example2.c
@@ -82,6 +82,19 @@ channel_group_prepared (GObject *channel,
static void
+channel_invalided (TpProxy *channel,
+ guint domain,
+ guint code,
+ const char *message,
+ gpointer user_data)
+{
+ /* release our reference to this channel proxy */
+ g_object_unref (channel);
+}
+
+
+/* begin ex.channel-dispatcher.clients.impl.tpsimpleobserver */
+static void
observe_channels (TpSimpleObserver *observer,
TpAccount *account,
TpConnection *connection,
@@ -116,6 +129,11 @@ observe_channels (TpSimpleObserver *observer,
context);
increment_pending (context);
}
+
+ /* hold a reference to the channel, that we release on invalidation */
+ g_object_ref (channel);
+ g_signal_connect (channel, "invalidated",
+ G_CALLBACK (channel_invalided), NULL);
}
/* hold a reference to @context */
@@ -123,6 +141,7 @@ observe_channels (TpSimpleObserver *observer,
/* delay responding to @context until our callbacks have finished */
tp_observe_channels_context_delay (context);
}
+/* end ex.channel-dispatcher.clients.impl.tpsimpleobserver */
int