From fd3e49f249fb4ab5ac7da4fe9fc14cc67958d84a Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sat, 29 Jan 2005 19:52:19 +0000 Subject: 2005-01-29 Havoc Pennington * 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 element * glib/dbus-gidl.c: add PropertyInfo * glib/dbus-gobject.c (handle_introspect): put the outermost outside the signal and property descriptions. (introspect_properties): export properties as rather than as method calls --- doc/TODO | 2 + doc/dbus-specification.xml | 188 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 180 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/TODO b/doc/TODO index d4ca427a..49b00779 100644 --- a/doc/TODO +++ b/doc/TODO @@ -43,6 +43,8 @@ Important for 1.0 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 === diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 6e34be27..973f390b 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1118,13 +1118,23 @@ Error replies are normally mapped to exceptions in languages that have exceptions. + + 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. + This specification doesn't require anything of native API bindings; the preceding is only a suggested convention for consistency among bindings. - @@ -2053,26 +2063,184 @@ - - Standard One-to-One Messages + + Naming Conventions + + + D-BUS namespaces are all lowercase and correspond to reversed domain + names, as with Java. e.g. "org.freedesktop" + + + Interface, signal, method, and property names are "WindowsStyleCaps", note + that the first letter is capitalized, unlike Java. + + + Object paths are normally all lowercase with underscores used rather than + hyphens. + + + + + Standard Interfaces See 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. - - <literal>org.freedesktop.Peer.Ping</literal> - + + <literal>org.freedesktop.Peer</literal> + + The org.freedesktop.Peer interface + has one method: org.freedesktop.Peer.Ping () - On receipt of the METHOD_CALL - message org.freedesktop.Peer.Ping, an application - should do nothing other than reply with a METHOD_RETURN as usual. + On receipt of the METHOD_CALL message + org.freedesktop.Peer.Ping, an application should do + nothing other than reply with a METHOD_RETURN 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.) + + <literal>org.freedesktop.Introspectable</literal> + + This interface has one method: + + org.freedesktop.Introspectable.Introspect (out STRING xml_data) + + + + Objects instances may implement + Introspect 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. + + + describes the format of this XML string. + + + + <literal>org.freedesktop.Properties</literal> + + Many native APIs will have a concept of object properties + or attributes. These can be exposed via the + org.freedesktop.Properties interface. + + + + 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); + + + + The available properties and whether they are writable can be determined + by calling org.freedesktop.Introspectable.Introspect, + see . + + + + + + Introspection Data Format + + As described in , + 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. + + + Here is an example of introspection data: + + <!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> + + + + A more formal DTD and spec needs writing, but here are some quick notes. + + + + 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. + + + + + 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. + + + + + 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. + + + + + The possible directions are "in" and "out", + unlike CORBA there is no "inout" + + + + + The possible property access flags are + "readwrite", "read", and "write" + + + + + 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. + + + + + Multiple interfaces can of course be listed for + one <node>. + + + + + -- cgit