Documenting Telepathy: Examples

I’m gradually working on documenting Telepathy, the IM/real-time-communications toolkit, though I am currently still exploring the API rather than writing text, and I am only using occasional hours here and there for even that. The delay is more due to me than Telepathy. With the help of the Telepathy developers, I have  completed some simple telepathy-glib examples, giving me a feel for the API. I can now start to write up some of the text.

Telepathy actually works and is full featured, and has many people working on it. That makes it very useful to many people.

But to be honest, the API feels frustrating so far and I think you’ll see what I mean when you look at those examples. I’ll continue trying to document it so people at least know what to do, even if what they have to do doesn’t seem very nice.

Apart from the many little annoyances, I think the API suffers greatly from extreme use of asynchronicity, instead of fighting to protect application developers from that. I think that’s partly due to the choice of D-Bus for the implementation, instead of just using a C library, forcing every method call to be asynchronous. There’s also a tendency for high-level actions to consist of  multiple small (asynchronous) low-level steps, though that’s partly due to the awkwardness of simulating an object-orientated class hierarchy in a D-Bus API where even (the equivalent of) a cast is asynchronous, and a consequence of needing to discover interfaces at runtime, due to inconsistent interface coverage by the various plugins (connection managers). There’s also a tendency to expose the (naturally asynchronous) client-server network behavior of the protocols directly in the API instead of combining and hiding multiple network back and forth behind simpler API, though the new TpContact class does a lot of work in the background.

However,  I have not yet explored the whole API and don’t yet have a full sense of the common ways that the API is used, so my judgement could conceivably be wrong. I also suspect that it could be much worse.

12 thoughts on “Documenting Telepathy: Examples

  1. The problem isn’t that it uses DBUS : since telepathy deals with networks, it must be as asynchronous as possible, so it’s normal that the api reflects that. Ekiga does have the same technical constraints, and uses similar technical solutions.

    In fact, it always amazes me that they started telepathy from scratch instead of breaking ekiga in pieces like we’ve been doing…

  2. Doing things right is hard; who knew? In other news, making people free() memory is a pain in the arse. APIs should definitely protect developers from memory management, since that’s difficult too.

  3. “Snark, but D-Bus makes it worse.”

    I think, a good justification is required for that statement. How about you document somewhere where developers will know about it instead of ranting in blogs?

  4. Murray,
    I feel for you trying to document an API, but don’t you believe that most of the low-level stuff will eventually be abstracted out and become less problematic? I can see a place for a VALA extension to do that.

  5. It seems to me, and I speak without much knoweledge, that if you want to make a telepathy app, you better use libempathy instead. I think libtelepathy is too much low level.

  6. I don’t think D-Bus is the problem, we use it on BlueZ and AFAIK people are happy to not have to deal directly with sockets or any other API, people should really start to consider using signals for asynchronous operation anyway. Telepathy API is just too big, and eccentric to be honest e.g. PresenceUpdate signal, and actually not really useful for applications which needs something way more simple. Libraries such as libempathy or libtelepathy help but in the end they defeat the very purpose of D-Bus bindings.

    BTW, Discovering the interfaces seems to be a dbus-glib problem where the introspection data is generated from the spec text files.

  7. I agree with Ignacius. Developing with libtelepathy is a bit hard, especially for newcomers like me. Using libempathy is a good alternative to libtelepathy. Moreover there exists libempathy and libempathy-gtk which separate UI and underlying functionality that allows other developers to use libempathy in their applications with their UI.

  8. Snark: Telepathy started out as a D-Bus API specification rather than tied to a specific implementation. We implemented the XMPP backend ourselves initially (using the Loudmouth library rather than a higher-level implementation mostly due to licensing reasons at the time) as a prototype/reference implementation, but the bulk of work for other protocols (SIP and IRC by Nokia, MSN from the commuity, libpurple as a GSoC project) came from other sources in the end, who all made their own implementation choices for their own reasons. There’s nothing preventing anyone implementing or consuming parts of the Telepathy APIs using parts of Ekiga, but there’s not been a lot of call for H.232 support and mostly due to Nokia’s choice, the SIP stack came from elsewhere. But there’s nothing about these implementations that prevent other people from implementing the same API. If I was feeling mischievous, I’d say “It amazes me people still write their own APIs from scratch for these tasks…” :)

    Murray: D-Bus doesn’t make it worse, really. The fact it uses IPC is a design goal of Telepathy, to allow the sharing of connections between client processes. Use of IPC necessarily introduces more complexity than an in-process library, in the same way as threading does, because it means that the state of things you are interacting with can change in an asynchronous manner, but that’s not D-Bus’s fault.

    Daeng, Ignacius, Deniz: Yes, currently the API provided by libempathy is a lot easier to use because it does a lot of the legwork of downloading/initialising state for you behind the scenes. Like TpContact, its our intention that telepathy-glib does this for you for the common use-cases and so abstracts out more of the D-Bus legwork, and that libempathy can slim down/disappear a fair bit.

    Vudentz: Yes, PresenceUpdate sucks and was a mistake. We’ve already deprecated it in favour of a new SimplePresence interface, and continue to make changes like this to reduce API complexity and save round-trips. At some point we might make a Telepathy 1.0 and remove the deprecated API, but we’ve got work to do to finish updating/fixing things before then. As to being big, well, it turns out people put a lot of stuff through their IM protocols these days….

  9. Murray! What Daeng (I believe) was talking about when he refered to Vala and high-level api was Vala’s new co-thread support. Using this your code/logic looks very much like it would in case it was completely synchronous. It’s not completely implemented yet but looking at how fast Jurg implements complicated stuff, I am sure it will be there soon (<2-3 months).

Comments are closed.