n00b: signals with an extensible message

[Simon McVittie]

On Tue, 16 Feb 2010 at 07:38:44 -0600, Schmottlach, Glenn wrote:
> Another alternative is to encode your payload using XML or (preferably)
> JSON on top of D-Bus.

I'd discourage this unless there's already a common format for the payload, and
perhaps even then (for instance, it'd make sense to transfer rich text as HTML
rather than inventing a D-Bus serialization, but Telepathy has a D-Bus
serialization for vCards).

If you use JSON or XML, your recipient needs two libraries and two type
systems; in practice that means they'll be dealing with three subtly different
type systems (JSON, D-Bus, and whatever their language/runtime uses).

In particular, D-Bus has all the building blocks that JSON does, with the
notable exception of the special constant 'null' in JSON (which can be worked
around, if necessary). JSON objects/dictionaries are D-Bus 'a{sv}', JSON lists
are D-Bus 'av' (or some more specific type), JSON strings (Unicode) are D-Bus
's' (UTF-8), and so on.

To represent a simple C struct that will break ABI in the future, something
like:

    struct Meme {
        int32_t badger;
	char *mushroom;
	size_t n_snakes;
	uint64_t *snakes;    /* an array of length n_snakes */
	bool magical_trevor;
    } my_meme = {
        42,
	"fungus",
	2,
	{ 23, 37 },
	TRUE,
    };

I'd use an a{sv} something like this (using dbus-python notation to make the
types explicit - this can be written more concisely of course):

    dbus.Dictionary({
        dbus.String('badger'):         dbus.Int32(42),
	dbus.String('mushroom'):       dbus.String('fungus'),
	dbus.String('snakes'):         dbus.Array([23, 37], signature='x'),
	dbus.String('magical-trevor'): dbus.Boolean(True),
    }, signature='sv')

In other words, represent your struct as a dictionary, using the D-Bus type
system. The receiver can detect missing or extra members and do whatever it
wants with them (best practice is usually to ignore extra members and define a
sane default for missing members, but if that's not always acceptable, you
could define a local convention like "if there are unrecognised fields starting
with '!' the message must be rejected").

Telepathy <http://telepathy.freedesktop.org/spec/> contains many examples of
a{sv} being used as an extensible payload format.

Regards,
    S