Properties interface enhancements (was: Signal for property changes)

[Thiago Macieira]

Simon McVittie wrote:
> Additions in our
>interface compared with D-Bus':

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

How is that different from the D-Bus read-only, write-only and read-write 
properties?

I'm ignoring completely unavailable properties because they are, by 
definition, unavailable and useless. Do you have a use-case for a 
property that always exists, but can't be read or written to?

>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]

ListProperties => Introspect

>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.

Good idea. A method to set many properties at once, avoiding round-trips.

>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.

This is what we're discussing.

>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].

I don't agree with this. Interfaces don't change while they're existing, 
so properties shouldn't change from readable to write-only, etc.

>[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.

Whereas I would agree that using D-Bus's own data structures to describe 
the interfaces would have been better in the beginning, now everyone 
parses the XML already.

Besides, applications don't query unknown interfaces in unknown objects at 
run-time and decide by themselves what to do. They only talk to known 
interfaces, which means that the remote end's capabilities are known at 
develop- and compile-time. Pre-parsing an XML file at that point has 
negligible cost.

>[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).

This is Marcel's proposal: we add a flag to the property indicating if 
it's "watchable". I would personally like to avoid sending signals 
unnecessarily, so I'd request the signal be emitted only if there's at 
least one listener.

>[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.

This is interesting, but it can also be solved by using other structures 
rather than properties. Or, like you invented yourself, 
Telepathy-specific properties.

>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).

The naming convention is FirstLetterCapitalCamelCase, just like for 
methods and signals, even though KDE is not following that.

-- 
  Thiago Macieira  -  thiago (AT) macieira.info - thiago (AT) kde.org
    PGP/GPG: 0x6EF45358; fingerprint:
    E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://lists.freedesktop.org/archives/dbus/attachments/20071208/66fe524d/attachment.pgp