[Telepathy] Proposed Telepathy client GLib API

[Simon McVittie]

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

Rob and I have been thinking about how best to improve the client API
of Telepathy. We want to include some sort of client-side code in
telepathy-glib, so we can declare libtelepathy to be obsolete. In the
process we want to fix libtelepathy's API problems.

We'd appreciate comments on this, particularly from client code authors
(Empathy, Tapioca, Banter, Nokia Mission Control and UI, Decibel).

Goals:
* All "boring" code auto-generated from the specification, like we do
  for services, to avoid mistakes while improving type-safety
* Easier to use than libtelepathy
* Clean, consistent API that does not expose implementation details, so
  it can be reimplemented in a more efficient way without ABI breakage
* Easy synchronous and async calls, with async encouraged

Non-goals:
* Replacing dbus-glib

Here's what our plan for the API looks like:

* TpClientProxy is a subclass of DBusGProxy with logic for fetching and
  caching a list of interfaces

* TpChannel, TpConnection, TpConnectionManager are the main subclasses of
  TpClientProxy

* TpMediaStreamHandler, TpMediaSessionHandler, TpChannelHandler are also
  TpClientProxy subclasses? or direct DBusGProxy subclasses?

* Auto-generated method stubs similar to those in libtelepathy's *-gen.h in a
  tp_cli namespace, with naming similar to the tp_svc namespace, leading to
  names like tp_cli_connection_interface_avatars_get_avatar_requirements -
  instead of taking an interface DBusGProxy as the first argument, they
  will probably take the main proxy (TpConnection etc.) as the first argument

* Hand-written convenience methods outside the tp_cli namespace added
  on an as-needed basis, e.g. tp_cli_connection_request_channel() will
  "return" an object path, but tp_connection_request_channel() will return
  a TpChannel. Some of these methods will cache data where it's known to
  be safe, listening to signals where necessary to keep the cache fresh.
  For instance, group membership can be tracked like that, and handle
  inspection can probably be cached.

* Some sort of really cunning signal-connection process that I haven't quite
  planned out yet :-)

I intend to prototype this in the development branch of libtelepathy,
which will evolve into something with a progressively closer resemblance
to telepathy-glib (plus an increasing amount of deprecated glue code to
keep it API-compatible with the old libtelepathy). When it's API-stable
and seems sane, we'll move it into telepathy-glib and declare libtelepathy
to be obsolete.

Meanwhile, Rob will continue to convert Stream Engine into library code, in
the tp_media namespace. This will initially depend on libtelepathy, but
when telepathy-glib has enough client code to support Stream Engine,
it'll use telepathy-glib instead. This library will eventually be moved to
the telepathy-glib Darcs repository (possibly in a telepathy-media-glib
subdirectory); when it's API-stable, it'll produce
libtelepathy-media-glib.so.0. We expect distributions to package
the two libraries separately, e.g. Debian would ship binary packages
libtelepathy-glib0 and libtelepathy-media-glib0, both built from a source
package called telepathy-glib.

The division between telepathy-glib and telepathy-media-glib is that
telepathy-media-glib contains everything that requires Farsight. If
Farsight is not available at build time, only telepathy-glib will be
built. Obviously, distributions should build against Farsight.

	Simon
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: OpenPGP key: http://www.pseudorandom.co.uk/2003/contact/ or pgp.net

iD8DBQFHFNifWSc8zVUw7HYRAqDPAKCcnAXDHgiPf1fbMi7nOkqgFZa41wCgoA51
rcQQjszxQZg41lkDqzcF4pc=
=hQX3
-----END PGP SIGNATURE-----