n00b: signals with an extensible message

[Tim Hockin]

On Tue, Feb 16, 2010 at 7:35 AM, Simon McVittie
<simon.mcvittie at collabora.co.uk> wrote:
> 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.

Thanks for the pointer.  I found the tp_asv helper routines, but I am
having trouble finding the marshalling code. Any deeper pointers you
can share?

Tim