[Telepathy-commits] [telepathy-doc/master] 2009-01-27 Murray Cumming <murrayc at murrayc.com>
Murray Cumming
murrayc at murrayc.com
Wed Jan 28 10:36:32 PST 2009
* docs/examples/: Added basics_dbus_glib_signals/ and
basics_dbus_python_signals/
* docs/book/C/telepathy.xml: Basics: Using D-Bus: Added sections with
examples of using D-Bus signals with dbus-glib and Python, though the
dbus-glib one doe not seem to work yet.
Entities: Corrected the base URL for the dbus-glib API reference.
---
ChangeLog | 9 +++
configure.ac | 2 +
docs/book/C/telepathy.xml | 19 ++++++-
docs/examples/Makefile.am | 2 +-
.../basics_dbus_python_signals/Makefile.am | 4 ++
.../examples/basics_dbus_python_signals/example.py | 56 ++++++++++++++++++++
6 files changed, 88 insertions(+), 4 deletions(-)
create mode 100644 docs/examples/basics_dbus_python_signals/Makefile.am
create mode 100644 docs/examples/basics_dbus_python_signals/example.py
diff --git a/ChangeLog b/ChangeLog
index 726a018..4f11a37 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
2009-01-27 Murray Cumming <murrayc at murrayc.com>
+ * docs/examples/: Added basics_dbus_glib_signals/ and
+ basics_dbus_python_signals/
+ * docs/book/C/telepathy.xml: Basics: Using D-Bus: Added sections with
+ examples of using D-Bus signals with dbus-glib and Python, though the
+ dbus-glib one doe not seem to work yet.
+ Entities: Corrected the base URL for the dbus-glib API reference.
+
+2009-01-27 Murray Cumming <murrayc at murrayc.com>
+
* docs/examples/:
* docs/book/C/telepathy.xml: Basics: Using D-Bus: Added sections with
examples of using D-Bus properties with dbus-glib and Python.
diff --git a/configure.ac b/configure.ac
index 6abf2ce..6441c97 100644
--- a/configure.ac
+++ b/configure.ac
@@ -27,8 +27,10 @@ AC_OUTPUT([
docs/examples/Makefile
docs/examples/basics_dbus_glib_methods/Makefile
docs/examples/basics_dbus_glib_properties/Makefile
+ docs/examples/basics_dbus_glib_signals/Makefile
docs/examples/basics_dbus_python_methods/Makefile
docs/examples/basics_dbus_python_properties/Makefile
+ docs/examples/basics_dbus_python_signals/Makefile
docs/examples/connect/Makefile
docs/examples/list_all_protocols/Makefile
docs/examples/list_contacts/Makefile
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 981960e..05edfc6 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -22,6 +22,8 @@
<!ENTITY url_spec_base "&url_spec;#org.freedesktop.Telepathy.">
<!ENTITY url_telepathy_glib_base "http://telepathy.freedesktop.org/doc/telepathy-glib/telepathy-glib-">
<!ENTITY url_dbus_spec_base "http://dbus.freedesktop.org/doc/dbus-specification.html#">
+ <!ENTITY url_dbus_glib_base "http://dbus.freedesktop.org/doc/dbus-glib/">
+ <!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
]>
<book id="index">
@@ -168,8 +170,8 @@ of the Telapathy specification.
<sect3 id="sect-basics-dbus-glib-methods">
<title>Calling Methods</title>
- <para>This example uses dbus-glib's <ulink url="http://dbus.freedesktop.org/doc/api/html/group__DBusGLib.html#gbd4dab5f4d66ab052c15862028502caf">dbus_g_proxy_begin_call()</ulink> function to call the <literal>Notify()</literal> method on the <literal>org.freedesktop.Notification</literal> interface of the desktop notification service at the <literal>/org/freedesktop/Notification</literal> path. Note that we must specify the types of each parameter.</para>
- <para>We could have used the synchronous <ulink url="http://dbus.freedesktop.org/doc/api/html/group__DBusGLib.html#ge38c0fb788e874fcf88489c961480f38">dbus_g_proxy_call()</ulink> function instead but, as already mentioned, asynchronous calls are generally preferred with D-Bus.</para>
+ <para>This example uses dbus-glib's <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-begin-call"><function>dbus_g_proxy_begin_call()</function></ulink> function to call the <literal>Notify()</literal> method on the <literal>org.freedesktop.Notification</literal> interface of the desktop notification service at the <literal>/org/freedesktop/Notification</literal> path. Note that we must specify the types of each parameter. The specified callback function then calls <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-end-call"><function>dbus_g_proxy_end_call()</function></ulink> to retreive the result.</para>
+ <para>We could have used the synchronous <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-call"><function>dbus_g_proxy_call()</function></ulink> function instead but, as already mentioned, asynchronous calls are generally preferred with D-Bus.</para>
<para><ulink url="&url_examples_base;basics_dbus_glib_methods">Source Code</ulink></para>
</sect3>
@@ -180,6 +182,11 @@ of the Telapathy specification.
<para><ulink url="&url_examples_base;basics_dbus_glib_properties">Source Code</ulink></para>
</sect3>
+ <sect3 id="sect-basics-dbus-glib-signals">
+ <title>Handling Signals</title>
+ <para>D-Bus signal handlers may be specified with dbus-glib with the <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-connect-signal"><function>dbus_g_proxy_connect_signal()</function></ulink> function. As when calling D-Bus methods, you must specify the expected types, but for signals you must do this in a previous call to <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-add-signal"><function>dbus_g_proxy_add_signal()</function></ulink>. The specified callback function will then be called when the signal is emitted. This example connects to the "DeviceAdded" signal of the "org.freedesktop.Hal.Manager" interface so it can print a message to the terminal when, for instance, you plug in a USB stick.</para>
+ <para><ulink url="&url_examples_base;basics_dbus_glib_signals">Source Code</ulink></para>
+ </sect3>
</sect2>
@@ -194,12 +201,18 @@ of the Telapathy specification.
</sect3>
<sect3 id="sect-basics-dbus-python-properties">
- <title>Using Propertie</title>
+ <title>Using Properties</title>
<para>D-Bus properties are available via an additional <ulink url="&url_dbus_spec_base;standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface on some objects, which provides <function>Get()</function>, <function>Set()</function> and <function>GetAll</function> methods. You can call these methods to get or set property values for the object's other interfaces.</para>
<para>As of this writing, Python has no simple API for dealing with D-Bus properties so you must call these functions directly. Therefore this example is therefore very similar to the <link linkend="sect-basics-dbus-python-methods">Calling Methods</link> example.</para>
<para><ulink url="&url_examples_base;basics_dbus_python_properties">Source Code</ulink></para>
</sect3>
+ <sect3 id="sect-basics-dbus-python-signals">
+ <title>Handling Signals</title>
+ <para>D-Bus signal handlers may be specified in Python with the proxy object's <ulink url="&url_dbus_python_base;dbus.proxies.Interface-class.html#connect_to_signal"><function>connect_to_signal()</function></ulink> method. The specified callback function will then be called when the signal is emitted. This example connects to the "DeviceAdded" signal of the "org.freedesktop.Hal.Manager" interface so it can print a message to the terminal when, for instance, you plug in a USB stick.</para>
+ <para><ulink url="&url_examples_base;basics_dbus_python_signals">Source Code</ulink></para>
+ </sect3>
+
</sect2>
</sect1>
diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am
index 3a9e443..47d12d0 100644
--- a/docs/examples/Makefile.am
+++ b/docs/examples/Makefile.am
@@ -1,6 +1,6 @@
include $(top_srcdir)/docs/Makefile_web.am_fragment
-example_dirs = basics_dbus_glib_methods basics_dbus_glib_properties basics_dbus_python_methods basics_dbus_python_properties connect list_all_protocols list_contacts set_presence send_message
+example_dirs = basics_dbus_glib_methods basics_dbus_glib_properties basics_dbus_python_methods basics_dbus_python_properties basics_dbus_python_signals connect list_all_protocols list_contacts set_presence send_message
SUBDIRS = $(example_dirs)
diff --git a/docs/examples/basics_dbus_python_signals/Makefile.am b/docs/examples/basics_dbus_python_signals/Makefile.am
new file mode 100644
index 0000000..6e633c3
--- /dev/null
+++ b/docs/examples/basics_dbus_python_signals/Makefile.am
@@ -0,0 +1,4 @@
+include $(top_srcdir)/docs/examples/Makefile.am_fragment
+
+#Dist the example:
+EXTRA_DIST = example.py
diff --git a/docs/examples/basics_dbus_python_signals/example.py b/docs/examples/basics_dbus_python_signals/example.py
new file mode 100644
index 0000000..7e618a8
--- /dev/null
+++ b/docs/examples/basics_dbus_python_signals/example.py
@@ -0,0 +1,56 @@
+# Copyright 2009 Collabora Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2
+# as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+import dbus
+import dbus.mainloop.glib
+import gobject
+import sys
+import traceback
+
+def on_signal_device_added(path):
+ print "DeviceAdded signal handled: %s \n" % path
+ loop.quit()
+
+if __name__ == '__main__':
+
+ # Tell the dbus python module to use the Glib mainloop,
+ # which we will start and stop later:
+ dbus.mainloop.glib.DBusGMainLoop(set_as_default = True)
+
+ # Connect to the bus:
+ bus = dbus.SystemBus()
+
+ # Get a proxy for the remote object:
+ try:
+ proxy = bus.get_object('org.freedesktop.Hal',
+ '/org/freedesktop/Hal/Manager',
+ 'org.freedesktop.Hal.Manager')
+ except dbus.DBusException:
+ traceback.print_exc()
+ sys.exit(1)
+
+
+ # Connect to a signal on the interface: */
+ proxy.connect_to_signal(
+ "DeviceAdded",
+ on_signal_device_added)
+
+ # Start the mainloop so we can wait until the D-Bus method
+ # returns. We stop the mainloop in our handlers.
+ loop = gobject.MainLoop()
+ loop.run()
+
+
+
--
1.5.6.5
More information about the telepathy-commits
mailing list