dbus/doc TODO,1.59,1.60 dbus-specification.xml,1.19,1.20
Havoc Pennington
hp at freedesktop.org
Sat Jan 29 11:52:21 PST 2005
- Previous message: dbus ChangeLog,1.665,1.666
- Next message: dbus/glib .cvsignore, 1.5, 1.6 Makefile.am, 1.9, 1.10 dbus-gidl.c,
1.8, 1.9 dbus-gidl.h, 1.5, 1.6 dbus-glib-tool.c, 1.6,
1.7 dbus-gobject.c, 1.12, 1.13 dbus-gparser.c, 1.7, 1.8
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Update of /cvs/dbus/dbus/doc
In directory gabe:/tmp/cvs-serv20067/doc
Modified Files:
TODO dbus-specification.xml
Log Message:
2005-01-29 Havoc Pennington <hp at redhat.com>
* glib/Makefile.am: rename dbus-glib-tool to dbus-binding-tool;
though it uses glib, it could be extended for any binding in
principle
* glib/dbus-gobject.c (gobject_message_function): change to the
new way properties work
* dbus/dbus-protocol.h: add the new interfaces
* doc/dbus-specification.xml: document the introspection format,
Introspectable interface, and add an org.freedesktop.Properties
interface.
* glib/dbus-gparser.c: add support for a <property> element
* glib/dbus-gidl.c: add PropertyInfo
* glib/dbus-gobject.c (handle_introspect): put the outermost
<node> outside the signal and property descriptions.
(introspect_properties): export properties as <property> rather
than as method calls
Index: TODO
===================================================================
RCS file: /cvs/dbus/dbus/doc/TODO,v
retrieving revision 1.59
retrieving revision 1.60
diff -u -d -r1.59 -r1.60
--- TODO 29 Jan 2005 04:21:32 -0000 1.59
+++ TODO 29 Jan 2005 19:52:19 -0000 1.60
@@ -43,6 +43,8 @@
support escaping in the addresses, be sure multiple addresses
in one env variable work, etc.
+ - Ping isn't handled
+
Important for 1.0 GLib Bindings
===
Index: dbus-specification.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -d -r1.19 -r1.20
--- dbus-specification.xml 29 Jan 2005 04:21:32 -0000 1.19
+++ dbus-specification.xml 29 Jan 2005 19:52:19 -0000 1.20
@@ -1119,12 +1119,22 @@
exceptions.
</para>
<para>
+ In converting from native APIs to D-BUS, it is perhaps nice to
+ map D-BUS naming conventions ("FooBar") to native conventions
+ such as "fooBar" or "foo_bar" automatically. This is OK
+ as long as you can say that the native API is one that
+ was specifically written for D-BUS. It makes the most sense
+ when writing object implementations that will be exported
+ over the bus. Object proxies used to invoke remote D-BUS
+ objects probably need the ability to call any D-BUS method,
+ and thus a magic name mapping like this could be a problem.
+ </para>
+ <para>
This specification doesn't require anything of native API bindings;
the preceding is only a suggested convention for consistency
among bindings.
</para>
</sect4>
-
</sect3>
<sect3 id="message-protocol-types-signal">
@@ -2053,25 +2063,183 @@
</para>
</sect1>
- <sect1 id="standard-messages">
- <title>Standard One-to-One Messages</title>
+ <sect1 id="naming-conventions">
+ <title>Naming Conventions</title>
+
+ <para>
+ D-BUS namespaces are all lowercase and correspond to reversed domain
+ names, as with Java. e.g. "org.freedesktop"
+ </para>
+ <para>
+ Interface, signal, method, and property names are "WindowsStyleCaps", note
+ that the first letter is capitalized, unlike Java.
+ </para>
+ <para>
+ Object paths are normally all lowercase with underscores used rather than
+ hyphens.
+ </para>
+ </sect1>
+
+ <sect1 id="standard-interfaces">
+ <title>Standard Interfaces</title>
<para>
See <xref linkend="message-protocol-types-notation"/> for details on
- the notation used in this section.
+ the notation used in this section. There are some standard interfaces
+ that may be useful across various D-BUS applications.
</para>
- <sect2 id="standard-messages-ping">
- <title><literal>org.freedesktop.Peer.Ping</literal></title>
- <para>
+ <sect2 id="standard-interfaces-peer">
+ <title><literal>org.freedesktop.Peer</literal></title>
+ <para>
+ The <literal>org.freedesktop.Peer</literal> interface
+ has one method:
<programlisting>
org.freedesktop.Peer.Ping ()
</programlisting>
</para>
<para>
- On receipt of the <literal>METHOD_CALL</literal>
- message <literal>org.freedesktop.Peer.Ping</literal>, an application
- should do nothing other than reply with a <literal>METHOD_RETURN</literal> as usual.
+ On receipt of the <literal>METHOD_CALL</literal> message
+ <literal>org.freedesktop.Peer.Ping</literal>, an application should do
+ nothing other than reply with a <literal>METHOD_RETURN</literal> as
+ usual. It does not matter which object path a ping is sent to. The
+ reference implementation should simply handle this method on behalf of
+ all objects, though it doesn't yet. (The point is, you're really pinging
+ the peer process, not a specific object.)
+ </para>
+ </sect2>
+
+ <sect2 id="standard-interfaces-introspectable">
+ <title><literal>org.freedesktop.Introspectable</literal></title>
+ <para>
+ This interface has one method:
+ <programlisting>
+ org.freedesktop.Introspectable.Introspect (out STRING xml_data)
+ </programlisting>
+ </para>
+ <para>
+ Objects instances may implement
+ <literal>Introspect</literal> which returns an XML description of
+ the object, including its interfaces (with signals and methods), objects
+ below it in the object path tree, and its properties.
+ </para>
+ <para>
+ <xref linkend="introspection-format"/> describes the format of this XML string.
+ </para>
+ </sect2>
+ <sect2 id="standard-interfaces-properties">
+ <title><literal>org.freedesktop.Properties</literal></title>
+ <para>
+ Many native APIs will have a concept of object <firstterm>properties</firstterm>
+ or <firstterm>attributes</firstterm>. These can be exposed via the
+ <literal>org.freedesktop.Properties</literal> interface.
+ </para>
+ <para>
+ <programlisting>
+ org.freedesktop.Properties.Get (in STRING interface_name,
+ in STRING property_name,
+ out VARIANT value);
+ org.freedesktop.Properties.Set (in STRING interface_name,
+ in STRING property_name,
+ in VARIANT value);
+ </programlisting>
+ </para>
+ <para>
+ The available properties and whether they are writable can be determined
+ by calling <literal>org.freedesktop.Introspectable.Introspect</literal>,
+ see <xref linkend="standard-interfaces-introspectable"/>.
</para>
</sect2>
+ </sect1>
+
+ <sect1 id="introspection-format">
+ <title>Introspection Data Format</title>
+ <para>
+ As described in <xref linkend="standard-interfaces-introspectable"/>,
+ objects may be introspected at runtime, returning an XML string
+ that describes the object. The same XML format may be used in
+ other contexts as well, for example as an "IDL" for generating
+ static language bindings.
+ </para>
+ <para>
+ Here is an example of introspection data:
+ <programlisting>
+ <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+ "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+ <node name="/org/freedesktop/sample_object">
+ <interface name="org.freedesktop.SampleInterface">
+ <method name="Frobate">
+ <arg name="foo" type="int32" direction="in"/>
+ <arg name="bar" type="string" direction="out"/>
+ </method>
+ <signal name="Changed">
+ <arg name="new_value" type="boolean"/>
+ </signal>
+ <property name="Bar" type="byte" access="readwrite"/>
+ </interface>
+ <node name="child_of_sample_object"/>
+ <node name="another_child_of_sample_object"/>
+ </node>
+ </programlisting>
+ </para>
+ <para>
+ A more formal DTD and spec needs writing, but here are some quick notes.
+ <itemizedlist>
+ <listitem>
+ <para>
+ Only the root <node> element can omit the node name, as it's
+ known to be the object that was introspected. If the root
+ <node> does have a name attribute, it should be an absolute
+ object path. If child <node> have object paths, they should be
+ relative.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If a child <node> has any sub-elements, then they
+ must represent a complete introspection of the child.
+ If a child <node> is empty, then it may or may
+ not have sub-elements; the child must be introspected
+ in order to find out. The intent is that if an object
+ knows that its children are "fast" to introspect
+ it can go ahead and return their information, but
+ otherwise it can omit it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The direction element on <arg> may be omitted,
+ in which case it defaults to "in" for method calls
+ and "out" for signals. Signals only allow "out"
+ so while direction may be specified, it's pointless.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The possible directions are "in" and "out",
+ unlike CORBA there is no "inout"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The possible property access flags are
+ "readwrite", "read", and "write"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The current type="uint32" stuff is totally broken,
+ instead we have to do full signatures.
+ However, then this format will suck for human readability.
+ So, some thinking to do here.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Multiple interfaces can of course be listed for
+ one <node>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
</sect1>
- Previous message: dbus ChangeLog,1.665,1.666
- Next message: dbus/glib .cvsignore, 1.5, 1.6 Makefile.am, 1.9, 1.10 dbus-gidl.c,
1.8, 1.9 dbus-gidl.h, 1.5, 1.6 dbus-glib-tool.c, 1.6,
1.7 dbus-gobject.c, 1.12, 1.13 dbus-gparser.c, 1.7, 1.8
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the dbus-commit
mailing list