clarity of concept

clarity of concept

Actually I think it's not too difficult to map D-Bus concepts to C (and classic UNIX) concepts in an understandable way. I mean, most programs today use C in a more or less object-oriented fashion (even though the language itself doesn't really have any syntactic sugar for that), and as D-Bus is object-oriented you can map things relatively easily.

• What OO/D-Bus calls a "method" translates to a C "function".
• What OO/D-Bus calls an "interface" translates to a C "struct" plus the functions you'd use to modify the struct.
• What D-Bus calls an "object path" in a way translates in C to a pointer to a specific instance of a struct.
• What D-Bus calls a method "signature" is really like a C signature, or function prototype if you so will.
• What OO/D-Bus calls a "service" one could translate more or less to a UNIX socket.
• And finally, the concept of a "bus" one could translate to a directory in the file system that multiple UNIX sockets are placed in.

Now, if you want to call a function on some other process via D-Bus, then you would do a method call, passing an object path, its interface, and the right arguments according to the method's signature, and send that to a specific service, on a specific bus.

And that's really all there is to it. If you understood C then D-Bus isn't particularly difficult. That said, libdbus-1 doesn't really help in making D-Bus digestable. Because it wanted to be a library that people should use for writing higher-level language bindings for, it is a bit too verbose I guess. In systemd we decided to provide a new D-Bus library that's supposed to be easier to use. With that in place calling a D-Bus method becomes really easy:

{
        sd_bus *bus;
        sd_bus_new_system(&bus);
        sd_bus_call_method(bus, 
                "org.freedesktop.timedate1",
                "/org/freedesktop/timedate1",
                "org.freedesktop.timedate1"
                "SetTimezone"
                NULL,
                NULL, 
                "sb",
                "Europe/Berlin",
                1);
       sd_bus_unref(bus);
}

This connects to the system bus (which is where all system services are found on), then call a method on the "org.freedesktop.timedate1" service, referencing an object by its path "/org/freedesktop/timedate1", selecting its interface "org.freedesktop.timedate1", invoking the "SetTimezone" method call. The two NULL pointers are for getting back a more verbose error on failure and for getting some other response data back. In thise case for the sake of just being an example we pass that as NULL because we aren't interested. Then, the signature of the call is "sb", meaning a string followed by a boolean. And finally, that's the wo arguments we pass.

Ignoring the fact that this example doesn't do any error checking this is really as easy as it gets. In effectively four lines of pure C code you can fire off an RPC call.

Now, D-Bus does substantially more than just what the example above shows. It has a scheme for getting notifications back from bus objects ("signals"), it knows introspection, and authentication and all that stuff. But in the essence its really as easy as the example above shows.

Hope this is useful,

Lennart

> import dbus
> 
> dbus.SessionBus() \
>     .get_object('org.freedesktop.timedate1', '/org/freedesktop/timedate1') \
>     .SetTimezone('Europe/Berlin', dbus_interface='org.freedesktop.timedate1')