Handles Telepathy Properties
Telepathy Logo

API conventions

There is a general convention for method names in Telepathy.

Many method names begin with Get (e.g. GetAliases, GetParameters, GetInterfaces, etc.). Get methods will only ever return immutable or cached data. They never block on a network request to a remote service; so data should be available immediately (see Section 2.6 ― API conventions below).

Method names beginning with Request (e.g. RequestAliases, RequestAvatars, RequestContactInfo, etc.) may make network requests (but not always, this depends on the Connection Manager). Depending on the network service, its latency and the size of the reply, it may be some time before data is available (or the network might fail and eventually an error will be returned).

Always Use Asynchronous Method Calls

Even when using a Get call, for which the information will already be available, you must always make asynchronous requests via D-Bus for the reasons outlined in Section 2.2 ― Using D-Bus.

Get Calls Can Trigger Network Traffic

Telepathy interprets Get calls as a way for a client to show interest in information.

In the case where there is no information cached in a Connection Manager, Get calls may choose to trigger a network request. The current (empty) cache will be returned as the reply, but upon completion of the request a signal will be emitted to indicate new data is available.

For example, if there is no cached data, GetAliases will return no information, but a request for alias information will be made to the remote service. Once that information has been retrieved the AliasesChanged signal will be emitted.

Handles Telepathy Properties