Properties interface enhancements (was: Signal for property changes)

[Simon McVittie]

The short version: if you're augmenting or redesigning the Properties
interface, please consider stealing ideas from Telepathy.

On Sat, 08 Dec 2007 at 13:33:54 +0100, Marcel Holtmann wrote:
> I was playing with the idea of replacing most method calls of the BlueZ
> API with the generic org.freedesktop.DBus.Properties interface.

We have a more extensive Properties interface in Telepathy, and in fact
there's nothing Telepathy-specific about our interface - you could use
org.freedesktop.Telepathy.Properties right now. Additions in our
interface compared with D-Bus':

* change notification
* property permissions (read-only/write-only/read-write/completely unavailable)

See
http://telepathy.freedesktop.org/spec.html#org.freedesktop.Telepathy.Properties
for more.

On the other hand, our properties interface is somewhat
over-complicated in other ways - it identifies properties by an integer
"property ID" and has a ListProperties method to get the name <-> ID
mapping, whereas we should probably have just used the names directly.

If we redesigned it today, it'd probably look like this:

typedef enum { PROPERTY_FLAG_READ = 1, PROPERTY_FLAG_WRITE = 2 } PropertyFlags;

method ListProperties () -> a{s(suv)}
    (or a{s(guv)} if dbus-glib ever gets support for the 'g' signature)
    Return a dict mapping property names to structs containing
    (type signature, flags, current value). Output might look like:

    { 'name': ('s', READ, 'Simon McVittie'),
      'alias': ('s', READ|WRITE, 'smcv'),
      'write-only-property': ('u', WRITE, 0),
      'unimplemented-property': ('u', 0, 0) }
    [0]

method SetProperties (a{sv}) -> nothing
    Set the given properties to the given values. Raise an error if one
    of the given properties is set to a value of an inappropriate type
    (for interoperability, integer types should be converted silently at the
    service end whenever necessary - blame dbus-glib) or if one of the given
    properties is not writeable.

signal PropertiesChanged (a{sv})
    Indicates that the given properties have changed. Services MAY emit
    this signal with properties that have not, in fact, changed.
    Services MUST emit this signal if the property has changed [1].
    The parameter is a map from property names to new values.

signal PropertyFlagsChanged (a{su})
    Indicates that the flags of the given properties have changed. The
    parameter is a map from property names to the new flags [2].

[0]: I believe the D-Bus XML introspection format is far from ideal, and
if it's as easy as this to stop an interface from dependending on
"introspection 1.0", we should.

[1]: I realise this makes it impossible for D-Bus properties to map 1:1
to Qt properties, but I don't think properties without change
notification are likely to be very useful, particularly if you're trying
hard (as we do) to avoid blocking on D-Bus calls. If others overrule me on
this, we could introduce a third value for PropertyFlags,
PROPERTY_FLAG_CHANGE_NOTIFICATION, meaning "changes to this property are
guaranteed to have change notification" (or PROPERTY_FLAG_NEEDS_POLLING,
with the opposite meaning).

[2]: This may seem weird, but in fact we use it in Telepathy - for
instance, when you become a moderator/admin/op in a chatroom, many of
its properties become writeable. We also deny read permission on chat
room properties until we've found out their values from the server.

Another thing we're pondering adding, which I think would be good to
have in a "D-Bus properties interface 2.0", is a naming convention or
naming rules for the properties themselves (I'm not sure whether this
should be a non-binding convention, or some hard requirements).

Regards,
    Simon