dbus/doc Makefile.am, 1.17, 1.18 dbus-tutorial.xml, 1.16,
1.17 introspect.dtd, 1.2, 1.3 introspect.xsl, NONE, 1.1
John Palmieri
johnp at freedesktop.org
Wed Aug 17 21:04:59 PDT 2005
Update of /cvs/dbus/dbus/doc
In directory gabe:/tmp/cvs-serv4207/doc
Modified Files:
Makefile.am dbus-tutorial.xml introspect.dtd
Added Files:
introspect.xsl
Log Message:
* ChangeLog: clean up my last entry a bit
* doc/introspect.xsl: New stylesheet for converting introspection data
into browser renderable xhtml. Contributed by Lennart Poettering.
* doc/introspect.dtd: Fixups in the introspect format from Lennart
Poettering.
* doc/dbus-tutorial.xml:
- Add Colin Walter to the Authors section for authoring the GLib
section
- Add descriptions of the new signature and type functionality
in the Python complex type mapping section
- Add a sidenote on the new args matching functionality in
the Python bindings
- Fixed up some of the examples to use the gobject.MainLoop
instead of gtk.main
* python/_dbus.py:
(Bus::_create_args_dict): New. Converts a hash of arg matches
to a more useable format
(Bus::add_signal_receiver): add a **keywords parameter for catching
arg match parameters
(Bus::remove_signal_receiver): add a **keywords parameter for catching
arg match parameters
* python/matchrules.py:
(MatchTree::exec_matches): Check for arg matches
(SignalMatchRule::add_args_match): New method
(SignalMatchRule::execute): Added args_list parameter as an optimization
so we don't have to marshal the args more than once
(SignalMatchRule::match_args_from_list): New method that checks to see
if the rule's arg matches match an argument list. Only arguments
set in the rule are checked.
(SignalMatchRule::match_args_from_rule): New method that checks to see
if the rule's arg matches match another rule's. All args have to match
in order for this method to return true. If either rule has more args
then it is not a match.
(SignalMatchRule::is_match): Add args match
(SignalMatchRule::repr): Add args to the final output if they exist
Index: Makefile.am
===================================================================
RCS file: /cvs/dbus/dbus/doc/Makefile.am,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -d -r1.17 -r1.18
--- Makefile.am 5 Feb 2005 03:24:54 -0000 1.17
+++ Makefile.am 18 Aug 2005 04:04:57 -0000 1.18
@@ -6,7 +6,8 @@
dbus-test-plan.xml \
dbus-tutorial.xml \
dcop-howto.txt \
- file-boilerplate.c
+ file-boilerplate.c \
+ introspect.xsl
HTML_FILES= \
dbus-faq.html \
Index: dbus-tutorial.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-tutorial.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- dbus-tutorial.xml 15 Jul 2005 15:21:43 -0000 1.16
+++ dbus-tutorial.xml 18 Aug 2005 04:04:57 -0000 1.17
@@ -34,7 +34,16 @@
</address>
</affiliation>
</author>
-
+ <author>
+ <firstname>Colin</firstname>
+ <surname>Walters</surname>
+ <affiliation>
+ <orgname>Red Hat, Inc.</orgname>
+ <address>
+ <email>walters at redhat.com</email>
+ </address>
+ </affiliation>
+ </author>
</authorgroup>
</articleinfo>
@@ -1195,7 +1204,7 @@
<thead>
<row>
<entry>D-BUS basic type</entry>
- <entry>Python object</entry>
+ <entry>Python wrapper</entry>
<entry>Notes</entry>
</row>
</thead>
@@ -1269,6 +1278,7 @@
<row>
<entry>D-BUS type</entry>
<entry>Python type</entry>
+ <entry>Python wrapper</entry>
<entry>Notes</entry>
</row>
</thead>
@@ -1276,28 +1286,63 @@
<row>
<entry><literal>ARRAY</literal></entry>
<entry><literal>Python lists</literal></entry>
+ <entry><literal>dbus.Array</literal></entry>
<entry>Python lists, denoted by square brackets [], are converted into arrays and visa versa.
The one restriction is that when sending a Python list each element of the list must be of the same
- type. This is because D-BUS arrays can contain only one element type. Use Python tuples for mixed types.</entry>
+ type. This is because D-BUS arrays can contain only one element type. Use Python tuples for mixed types.
+
+ When using the wrapper you may also specify a type or signature of the elements contained in the Array.
+ This is manditory when passing an empty Array to a method on the bus because Python can not guess at the
+ contents of an empty array. For example if a method is expecting an Array of int32's and you need to pass
+ it an empty Array you would do it as such:
+
+ <programlisting>emptyint32array = dbus.Array([], type=dbus.Int32)</programlisting>
+
+ or
+
+ <programlisting>emptyint32array = dbus.Array([], signature="i")</programlisting>
+
+ Note that dbus.Array derives from list so it acts just like a python list.
+ </entry>
</row>
<row>
<entry><literal>STRUCT</literal></entry>
<entry><literal>Python tuple</literal></entry>
+ <entry><literal>dbus.Struct</literal></entry>
<entry>Python tuples, denoted by parentheses (,), are converted into structs and visa versa.
Tuples can have mixed types.</entry>
</row>
<row>
<entry><literal>DICTIONARY</literal></entry>
<entry><literal>Python dictionary</literal></entry>
+ <entry><literal>dbus.Dictionary</literal></entry>
<entry>D-BUS doesn't have an explicit dictionary type. Instead it uses LISTS of DICT_ENTRIES to
represent a dictionary. A DICT_ENTRY is simply a two element struct containing a key/value pair.
- Python dictionaries are automatically converted to a LIST of DICT_ENTRIES and visa versa.</entry>
+ Python dictionaries are automatically converted to a LIST of DICT_ENTRIES and visa versa.
+
+ Since dictonaries are described as lists of dict_entries we also need the signature in order
+ to pass empty dictionaries. The wrapper provides a way of specifying this through the key_type/value_type
+ type parameters or the signature parameters. To send an empty Dictionary where the key is a string
+ and the value is a string you would do it as such:
+
+ <programlisting>emptystringstringdict = dbus.Dictionary({}, key_type=dbus.String, value_type=dbus.Value)</programlisting>
+
+ or
+
+ <programlisting>emptystringstringdict = dbus.Dictionary({}, signature="ss")</programlisting>
+
+ Note that dbus.Dictionary derives from dict so it acts just like a python dictionary.
+ </entry>
</row>
<row>
<entry><literal>VARIANT</literal></entry>
<entry><literal>any type</literal></entry>
+ <entry><literal>dbus.Variant</literal></entry>
<entry>A variant is a container for any type. Python exports its methods to accept only variants
- since we are an untyped language and can demarshal into any Python type.</entry>
+ since we are an untyped language and can demarshal into any Python type.
+
+ To send a variant you must first wrap it in a<literal>dbus.Variant</literal>. If no type or signiture is
+ given to the variant the marshaler will get the type from the contents.</entry>
</row>
</tbody>
@@ -1340,7 +1385,7 @@
calls allows you to return control to the GUI while you wait for the reply. This is exceedingly easy to do in
Python. Here is an example using the GLib/GTK+ mainloop.
<programlisting>
-import gtk
+import gobject
import dbus
if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
import dbus.glib
@@ -1357,7 +1402,8 @@
dbus_iface.ListNames(reply_handler=print_list_names_reply, error_handler=print_error)
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
</programlisting>
</para>
<para>
@@ -1383,7 +1429,7 @@
which takes a signal name and handler as arguments. Let us look at an example of connecting to the HAL service to receive
signals when devices are added and removed and when devices register a capability. This example assumes you have HAL already running.
<programlisting>
-import gtk
+import gobject
import dbus
if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
import dbus.glib
@@ -1407,7 +1453,8 @@
hal_manager.connect_to_signal('DeviceRemoved', device_removed_callback)
hal_manager.connect_to_signal('NewCapability', device_capability_callback)
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
</programlisting>
</para>
<para>
@@ -1440,6 +1487,28 @@
a reference to the object so once a signal was received operations could be executed on the object.
</para>
<sidebar>
+ <title>Signal matching on arguments</title>
+ <para>
+ Starting with D-Bus 0.36 and the (0, 43, 0) version of the python
+ bindings you can now add a match on arguments being sent in a signal.
+ This is useful for instance for only getting NameOwnerChanged
+ signals for your service. Lets say we create a name on the bus called
+ 'org.foo.MyName' we could also add a match to just get
+ NameOwnerChanges for that name as such:
+<programlisting>
+bus.add_signal_receiver(myname_changed,
+ 'NameOwnerChanged',
+ 'org.freedesktop.DBus',
+ 'org.freedesktop.DBus',
+ '/org/freedesktop/DBus',
+ arg0='org.foo.MyName')
+</programlisting>
+
+ It is as simple as that. To match the second arg you would use arg1=,
+ the third arg2=, etc.
+ </para>
+ </sidebar>
+ <sidebar>
<title>Cost of Creating a Proxy Object</title>
<para>
Note that creating proxy objects can have an associated processing cost. When introspection is implemented
@@ -1473,6 +1542,7 @@
a Python object that inherits from dbus.service.Object. The following is the start of an example
HelloWorld object that we want to export over the session bus.
<programlisting>
+import gobject
import dbus
import dbus.service
if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
@@ -1486,7 +1556,8 @@
bus_name = dbus.service.BusName('org.freedesktop.HelloWorld', bus=session_bus)
object = HelloWorldObject(bus_name)
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
</programlisting>
</para>
<para>
@@ -1500,6 +1571,7 @@
<para>
Let's make this object do something and export a method over the bus.
<programlisting>
+import gobject
import dbus
import dbus.service
if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
@@ -1517,7 +1589,8 @@
bus_name = dbus.service.BusName('org.freedesktop.HelloWorld', bus=session_bus)
object = HelloWorldObject(bus_name)
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
</programlisting>
</para>
<sidebar>
@@ -1572,6 +1645,7 @@
<para>
Setting up signals to emit is just as easy as exporting methods. It uses the same syntax as methods.
<programlisting>
+import gobject
import dbus
import dbus.service
if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
@@ -1595,7 +1669,8 @@
object.hello_signal('I sent a hello signal')
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
</programlisting>
</para>
<para>
Index: introspect.dtd
===================================================================
RCS file: /cvs/dbus/dbus/doc/introspect.dtd,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- introspect.dtd 17 Feb 2005 21:11:18 -0000 1.2
+++ introspect.dtd 18 Aug 2005 04:04:57 -0000 1.3
@@ -4,15 +4,18 @@
<!-- see D-BUS specification for documentation -->
-<!ELEMENT node (interface*,node*)>
-<!ATTLIST node name CDATA #REQUIRED>
+<!ELEMENT node (node|interface)*>
+<!ATTLIST node name CDATA #IMPLIED>
-<!ELEMENT interface (annotation*,method*,signal*,property*)>
+<!ELEMENT interface (method|signal|property|annotation)*>
<!ATTLIST interface name CDATA #REQUIRED>
-<!ELEMENT method (annotation*,arg*)>
+<!ELEMENT method (arg|annotation)*>
<!ATTLIST method name CDATA #REQUIRED>
+<!ELEMENT signal (arg|annotation)*>
+<!ATTLIST signal name CDATA #REQUIRED>
+
<!ELEMENT arg EMPTY>
<!ATTLIST arg name CDATA #IMPLIED>
<!ATTLIST arg type CDATA #REQUIRED>
@@ -21,12 +24,10 @@
The DTD format can't express that subtlety. -->
<!ATTLIST arg direction (in|out) "in">
-<!ELEMENT signal (arg,annotation)>
-<!ATTLIST signal name CDATA #REQUIRED>
-
-<!ELEMENT property (annotation)> <!-- AKA "attribute" -->
+<!-- AKA "attribute" -->
+<!ELEMENT property (annotation)*>
<!ATTLIST property name CDATA #REQUIRED>
-<!ATTLIST property type CDATA #REQUIRED>
+<!ATTLIST property type CDATA #REQUIRED>
<!ATTLIST property access (read|write|readwrite) #REQUIRED>
<!ELEMENT annotation EMPTY> <!-- Generic metadata -->
--- NEW FILE: introspect.xsl ---
<?xml version="1.0" encoding="ISO-8859-15"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
<!--
Copyright (C) 2005 Lennart Poettering.
Licensed under the Academic Free License version 2.1
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
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
-->
<!-- $Id: introspect.xsl,v 1.1 2005/08/18 04:04:57 johnp Exp $ -->
<xsl:output method="xml" version="1.0" encoding="iso-8859-15" doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" indent="yes"/>
<xsl:template match="/">
<html>
<head>
<title>DBUS Introspection data</title>
<style type="text/css">
body { color: black; background-color: white }
h1 { font-family: sans-serif }
ul { list-style-type: none; margin-bottom: 10px }
li { font-family: sans-serif }
.keyword { font-style: italic }
.type { font-weight: bold }
.symbol { font-family: monospace }
.interface { padding: 10px; margin: 10px }
</style>
</head>
<body>
<xsl:for-each select="node/interface">
<div class="interface">
<h1>
<span class="keyword">interface</span><xsl:text> </xsl:text>
<span class="symbol"><xsl:value-of select="@name"/></span>
</h1>
<ul>
<xsl:apply-templates select="annotation"/>
<xsl:for-each select="method|signal|property">
<li>
<span class="keyword"><xsl:value-of select="name()"/></span>
<xsl:text> </xsl:text>
<span class="symbol"><xsl:value-of select="@name"/></span>
<ul>
<xsl:apply-templates select="annotation"/>
<xsl:for-each select="arg">
<li>
<span class="keyword">
<xsl:choose>
<xsl:when test="@direction != """>
<xsl:value-of select="@direction"/>
</xsl:when>
<xsl:when test="name(..) = "signal"">
out
</xsl:when>
<xsl:otherwise>
in
</xsl:otherwise>
</xsl:choose>
</span>
<xsl:text> </xsl:text>
<span class="type"><xsl:value-of select="@type"/></span><xsl:text> </xsl:text>
<span class="symbol"><xsl:value-of select="@name"/></span><xsl:text> </xsl:text>
</li>
</xsl:for-each>
</ul>
</li>
</xsl:for-each>
</ul>
</div>
</xsl:for-each>
</body>
</html>
</xsl:template>
<xsl:template match="annotation">
<li>
<span class="keyword">annotation</span>
<code><xsl:value-of select="@name"/></code><xsl:text> = </xsl:text>
<code><xsl:value-of select="@value"/></code>
</li>
</xsl:template>
</xsl:stylesheet>
More information about the dbus-commit
mailing list