Interface Client

Interface Index (Compact) | Summary | Description | Properties

Properties

Interfaces as (DBus_Interface_List) Read only
Added in 0.17.26. (as a stable interface)

Description

Telepathy clients use connection managers, the channel dispatcher and optionally the account manager to provide useful functionality.

User interface processes are the obvious example of Telepathy clients, but they can provide other functionality, such as address-book synchronization.

Every running or activatable process with a well-known name of the form im.telepathy1.Client.clientname should be probed by the channel dispatcher to discover its capabilities. Each client is either an observer, an approver, a channel handler, or some combination of these.

Rationale:

Activatable services (those with a D-Bus .service file) must be supported so that we can run clients in response to channel creation.

Non-activatable services (those that do not register a D-Bus .service file for their well-known name, but do request it at runtime) must be supported so that we can have programs that process channels, but only if they are already running - for instance, a full-screen media centre application might do this.

The client name, clientname, MUST be a non-empty string of ASCII digits, letters, dots and/or underscores, starting with a letter or underscore, and without sets of two consecutive dots or a dot followed by a digit. For non-activatable services, it MAY contain a part that is generated per instance at runtime.

Rationale:

If each of a client Foo's instances should be able to manipulate channels separately, the instance with unique name :1.25 might request a well-known name like im.telepathy1.Client.Foo._1._25.

(Note that well-known bus-name components may not start with a digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)

Each Client MUST export an object whose object path may be determined by replacing '.' with '/' in the well-known name and prepending '/'. This object represents its API as a Telepathy client; the channel dispatcher will call its methods and read its properties when appropriate.

As an optimization, activatable clients SHOULD install a file $XDG_DATA_DIRS/telepathy/clients/clientname.client containing a cached version of its immutable properties, so that for most clients, the channel dispatcher can just read a file to discover capabilities, instead of having to service-activate the client immediately in order to fetch its read-only properties. However, the D-Bus API is canonical, and the channel dispatcher MUST support clients without such a file.

Non-activatable clients MAY install a .client file, but there's not much point in them doing so.

The .client files MUST contain UTF-8 text with the same syntax as Desktop Entry files (although the allowed groups, keys and values differ). Every .client file MUST contain a group whose name is the name of this interface.

The groups, keys and values in the .client file are defined by individual interfaces. Each interface that can usefully cache information in the .client file SHOULD correspond to a group with the same name.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

Interfaces — as (DBus_Interface_List)

Read only

A list of the extra interfaces provided by this client. This SHOULD include at least one of Client.Observer, Client.Approver or Client.Handler.

In the .client file, this is represented by key "Interfaces" in the group named after this interface. The value of the key is a list of interface names each followed by a semicolon (so it always ends with a semicolon unless it is empty), i.e. a key of type "strings" as described in the Desktop Entry specification.