Where is the documentation

[Jacques Pelletier]

On September 19, 2008 04:39:18 am Mihail Kotelnikov wrote:
> Hello.
>
> I tried to write dbus-powered application about three years ago. I've not
> found any documentation except short function/data types reference.
> Some days ago i've returned to this problem. And what i see? After three
> years of development project's documentation stays on the same level. In
> particular, there is no documentation conforming to the status of the
> project (linux message bus standard i mean). Function reference IS NOT a
> documentation. There is no complete examples (sorry, but sleep(1) IS NOT
> example of a working main loop), best practice explanation and so on. You
> suggest to use higher level bindings, but it's documentation is worse than
> documentation of the raw API. Yes, i can to bury myself in the dbus code,
> function reference and pieces of third-party half-working examples and
> write a [half-]working code. But it isn't the best way to write stable and
> efficient application for a production use.
>
> Sorry for my english.

I would like to contribute my bit of documentation.

I made a program using DBUS a little while ago. It's supposed to use DBUS to 
send strings of bytes specified in hexadecimal. Exceptionaly for my program, 
the DBUS interface sends ASCII strings instead of hexadecimal bytes as the 
other interfaces.
(See: http://sourceforge.net/projects/protocoltool/)

Here are my notes about DBUS below, extracted from the README file of my 
project. I hope it may be useful.


DBUS
----
http://en.wikipedia.org/wiki/Dbus

The would be successor of DCOP in the KDE environment.
See http://www.freedesktop.org/wiki/Software/dbus

For DBUS particularly, the format of strings are the same as dbus-send,
but surrounded with double quotes. protocoltool strip down these double
quotes and feed the string to a parser. The output on the terminal window
"is not what you get", but the output before parsing.

See man page for dbus-send.

The DBUS interface is fully implemented for now. Since the dbus-send 
mimicking code works, I plan to use the binary mode, i.e. sending strings 
directly without translating them as dbus-send does. This will allow to use 
the 
binary protocol as originally intended.

A dbus translating layer can be done later with a more generalized interface.

1) The man page for dbus-send has a small bug in the example invocation:

dbus-send --dest='org.freedesktop.ExampleName            \
                   /org/freedesktop/sample/object/name              \
                   org.freedesktop.ExampleInterface.ExampleMethod   \
                   int32:47 string:'hello world' double:65.32

There is a quote missing after "org.freedesktop.ExampleName".
The string argument can take white spaces.

Using this example 'as is' won't do anything unless you have a server
providing this service. A better way to get DBUS working is to use 
an example from dbus-glib bindings source file.

2) If you compiled dbus-glib from sources, there are 2 examples:
example-service and example-client.

The file example-service needs to be modified before using it:
Here's what it should look like
....
  bus_proxy = dbus_g_proxy_new_for_name (bus, "org.freedesktop.DBus",
					 "/org/freedesktop/DBus",
					 "org.freedesktop.DBus");

  if (!dbus_g_proxy_call (bus_proxy, "RequestName", &error,
			  G_TYPE_STRING, "org.designfu.SampleService",
			  G_TYPE_UINT, 0,
			  G_TYPE_INVALID,
			  G_TYPE_UINT, &request_name_result,
			  G_TYPE_INVALID))
    lose_gerror ("Failed to acquire org.designfu.SampleService", error);

  obj = g_object_new (SOME_TYPE_OBJECT, NULL);

  dbus_g_connection_register_g_object (bus, "/SomeObject", G_OBJECT (obj));
....

3) Protocoltool has already the settings preconfigured for simulating these
programs (and have a working demonstration). It has the same format and limi-
tations as dbus-send because I used parts of dbus-send.c for this program.
I also used the file dbus-print-message.c. Both of these come from dbus-1.0.2
source code (available anywhere, with the copy of the GPL).

You need to start example-service in a user console, dbus-monitor in another 
console and example-client on a 3rd console. Finally, you can compare with 
protocoltool.

The service and the client need to be run by the same user. Here, protocoltool 
acts as a client to example-service.

See files in examples/dbus for examples of DBUS results.


JP