[Telepathy] Proposal for tp-glib client code

[Simon McVittie]

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

On Thu, 24 Jan 2008 at 06:27:50 +0100, Xavier Claessens wrote:
> I'm updating Empathy to use the new API and I saw that TpConnection has an
> introspect queue. I had an idea:
> 
> What about moving the "ready" property to TpProxy and put the queue there,
> with a method like
> tp_proxy_add_introspect_func(TpProxy*,TpProxyIntrospectFunc*); Like that
> TpChannel and TpConnection which inherint from TpProxy will have that queue
> to add requests for everything that could be cached before being "ready".
> And it makes my live easier in empathy since I'm planning to have
> EmpathyTpGroup inheriting from TpChannel and add stuffs like GetMembers and
> GetSelfHandle in that introspect queue. Of course EmpathyTpGroup could be
> moved to tp-glib (But not as it is right now).

The plan is to have helper code for at least groups in TpChannel, since
the Group interface ends up being used for just about everything in Telepathy
(whether this is good or not is debatable...)

TpProxy is meant to be something that (with suitable namespacing
changes) could be dropped into dbus-glib more or less as-is, so it
shouldn't include anything particularly Telepathy-specific. I don't
know how generally applicable introspection and "state download" functionality
is, but I'm somewhat wary of extensible introspection, since if we get
the API slightly wrong, we'll be stuck with an API guarantee that the
object will download all state and subscribe to all signals. This is
undesirable if you don't actually care, since your process will wake up
when it didn't really need to.

I think it's reasonable for TpConnection and TpChannel to subscribe to certain
carefully selected signals automatically, though - Renaming (when we finalize
it) and Group both have sufficiently complex interactions with the "main"
interfaces that telepathy-glib should track them.

There are several broad classes of "property" that we could care about:

* Immutable properties, which might not be available immediately, but
  won't change after we've been able to retrieve them.

  Available immediately:
  * D-Bus core Introspect() (not that we use this in Telepathy...)
  * Channel GetInterfaces(), GetHandle(), Channel GetChannelType()
  * Connection GetProtocol()

  Not available immediately:
  * Connection GetInterfaces()
  * Connection Aliasing.GetAliasFlags()
  * Connection Avatars.GetAvatarRequirements()
  * Connection Presence.GetStatuses()

* Mutable properties, for which it's wrong to download the current state
  automatically if you don't first subscribe to an appropriate signal

  Available immediately:
  * Connection GetStatus()/StatusChanged
  * Channel Group.GetSelfHandle()/Connection Renamed
  * Channel GetGroupFlags()
  * Channel GetAvailableStreamTubeTypes(), GetAvailableTubeTypes()
  * Channel Properties

  Not available until Connection is connected:
  * Connection GetSelfHandle()/Renamed
  * Connection capabilities
  * Connection Properties? (though it's unclear whether this is allowed)

* Poll-only properties (no change notification)
  (we avoid these in Telepathy, to the extent that Gabble automatically
  polls MUC properties to avoid clients having to poll)

  D-Bus core Properties

Immutable properties could usefully be included in the definition of
"ready".

Mutable properties shouldn't be fetched until you have connected to
appropriate signals, but we don't want telepathy-glib to
connect to all signals in all cases (unnecessary wakeups are bad);
in this case "ready" should only include things where you've already also
connected to the signals automatically, which in a library should be
minimal.

Poll-only properties should be fetched on-demand (and are generally a bad
move anyway).

    Simon
-----BEGIN PGP SIGNATURE-----

iD8DBQFHmHcNWSc8zVUw7HYRAlIPAJ9gTsxNinsJpES4UiZWVvaL/Be2GwCggi2b
2TP+xGWvJOMs80mj0wlSJdo=
=XQCY
-----END PGP SIGNATURE-----