[Telepathy] Properties vs properties

[Simon McVittie]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

While doing Mission Control spec musing, I've been pondering the future
of the Telepathy Properties interface vs the D-Bus core Properties
interface.

These two interfaces have fundamentally different models of what it
means to have a property, and I'm not convinced they can be reconciled.
I'm starting to think we should deprecate (our) Properties in favour of some
clearer API.

Telepathy Properties
- --------------------

* Arbitrary objects have a non-namespaced a{sv} of properties

* Interfaces define properties, but instances of those interfaces aren't
  actually guaranteed to *have* them

* Uses, in practice:
  - Text channels: anonymous, invite-only, password, ... are read and
    written by UIs

  - Media Signalling interface: nat-traversal, stun-server etc.
    are read (only) by Stream Engine

* Overly complex API where you have to call two methods to
  "bootstrap" initial state, and you have to remember a name<->ID map
  to make any sense of the signals

* Change notification is guaranteed

* No special interaction with bindings is expected

* Properties can be set asynchronously

* Property access can change dynamically - properties are allowed to
  change between read-only, write-only, read/write and unusable at any
  time

D-Bus core Properties
- ---------------------

* Arbitrary objects have what's conceptually an a{sv} per interface

* Interfaces define a set of properties (just like methods) and every
  instance of that interface is expected to have them all, all the time

  - unless it implements an older version of the spec of course (i.e.
    just like methods)
  - properties appear in introspection, again like methods

* No guarantee of change notification, although interfaces are free to provide
  their own

* Expected to be implemented specially by bindings by mapping to e.g.
  GObject properties

  - restricting write access might be problematic
  - raising exceptions might be problematic
  - returning asynchronously is likely to be impossible
  - all those simplifications might in fact be considered a feature
  - read-only properties with cached values should be fine
  - TODO: does dbus-glib actually treat them specially?

Proposals
- ---------

1. Media Signalling should grow the following API:

method GetNATTraversal () -> s: nattraversal, a{sv}: parameters
    Return:
    * the type of NAT traversal to use (values 'none', 'stun'
      and 'gtalk-p2p', as currently used for the "nat-traversal" property)
    * a dict of parameters (well-known keys are defined by the type
      of NAT traversal, with 'stun-server', 'stun-port' and
      'gtalk-p2p-relay-token' currently defined)

    (alternatively, this could be a property, NATTraversal, or two properties,
    NATTraversal and NATTraversalParameters)

signal NATTraversalChanged (s: nattraversal, a{sv}: parameters)
    The values that would be returned by GetNATTraversal have changed.
    All parameters are given, not just the ones that changed.

2. Chatrooms should eventually get a simpler API broadly equivalent to the
   current properties, perhaps Channel.Interface.Chatroom.

3. We deprecate Properties and let it die.

4. Use D-Bus core Properties for things that never change and are
   "instant" to retrieve - Connection.Interfaces, Channel.Handle,
   Channel.HandleType, Channel.ChannelType, Channel.Interfaces, etc.
   Then we can replace the current tedious setup process for TpChannel
   with a single call to GetAll() (falling back to the current way
   until telepathy-glib 0.9 or so).

   Other possibilities from the current spec:
   Channel.Interface.Text.MessageTypes
   Connection.Interface.Avatars.AvatarRequirements

5. Consider using D-Bus core Properties for things that can change,
   with change notification provided by an interface-specific signal
   (things that must be polled don't have the signal).

   From a quick scan through the spec, it probably rarely makes sense to
   offer read/write properties - we can have property-specific "set"
   mechanisms. These, and the change notification, will often work better
   in terms of differences (e.g. add, remove) rather than as a "set"
   method.

   Possibilities from the current spec (all read-only):
   Channel.Interface.Group.Members
   Channel.Interface.Group.LocalPendingMembers
   Channel.Interface.Group.RemotePendingMembers
   Channel.Interface.Group.GroupFlags
   Channel.Interface.Password.PasswordFlags
   Channel.Interface.MediaSignalling.SessionHandlers
   Media.SessionHandler.StreamHandlers
   Channel.Type.Tubes.AvailableTubeTypes
   Channel.Type.Tubes.AvailableStreamTubeTypes
   Channel.Type.Tubes.Tubes
-----BEGIN PGP SIGNATURE-----

iD8DBQFHo1NrWSc8zVUw7HYRAqeoAKCF9BWzTkQz4S5+q24XZ+nI2A5xXgCgkKyc
4Wag41b3hRAvBCvpBPgVhUY=
=wP6N
-----END PGP SIGNATURE-----