If a protocol has the concept of presence, showing when users are online or available, then its Connection will provide the SimplePresence interface. This interface provides functions to set and get the user's current presence as well as the presence of other accounts (usually the accounts on the user's roster).

Presence vs. SimplePresence

The Telepathy API specification also specifies another presence interface Presence. This interface was deemed too complex and has summarily been deprecated. Telepathy clients should not use Presence and instead use SimplePresence.

5.3.1. The SimplePresence Tuple

The SimplePresence tuple is a D-Bus structure consisting of three members that is used throughout Telepathy.

The three members are:

  1. A presence type from the enum Connection_Presence_Type.

    This type must match the type specified for the status string as returned by the Statuses property (see below).

  2. A status string (e.g. "available" or "xa").

    This status string must valid for this Connection, as returned by the Statuses property (see below).

  3. An optional free-form status message (e.g. "Gone Fishing").

    This message may only be provided if the Can Have Message bit is true for the specificed status string (see below).

5.3.2. The Statuses Property

The Statuses property is provided by a Connection's SimplePresence interface, and maps the available status strings that can be used on that connection (the second member of the SimplePresence tuple) to properties for each status.

The string keys returned can be considered a superset of the enum Connection_Presence_Type, and allow extra presence information supported by a protocol to be reported back to Telepathy clients. For instance, a protocol that supports redirecting messages to your mobile phone might expose the status string "mobile", which is part of the type Connection_Presence_Type_Away, a Telepathy client can choose to expose this detail if it wishes. The SimplePresence entry lists some well-known status strings that might be reported by a Connection Manager.

The value of this map is a D-Bus struct containing three members: the Connection_Presence_Type for this status string; a boolean indicating whether a client can request this status, or if it's only returnable by the Connection Manager (i.e. used for error conditions); and a boolean flag indicating whether or not the status supports an additional free-form status message.

Table 5-2 is an example of a status map that might be returned (e.g. from Telepathy Gabble).

Table 5-2Example Statuses Map
Key Value
Status Type May Set on Self Can Have Message
available Connection_Presence_Type_Available True True
chat Connection_Presence_Type_Available True True
dnd Connection_Presence_Type_Busy True True
away Connection_Presence_Type_Away True True
xa Connection_Presence_Type_Extended_Away True True
hidden Connection_Presence_Type_Hidden True True
offline Connection_Presence_Type_Offline False True
unknown Connection_Presence_Type_Unknown False True
error Connection_Presence_Type_Error False True

5.3.3. Setting the User's Presence Via the Account Manager

The AccountManager and Account interfaces are not implemented in Mission Control 5 exactly as they are specified in the Telepathy API specification.

Mission Control 4 implements a completely different interface which is not documented here.

If this Connection was obtained from the Account Manager, then the user's presence can be set on the appropriate Account object using the RequestedPresence property of the Account interface. This property takes a SimplePresence as its value.

Setting presence via the Account Manager is documented fully in Section 3.2 ― Managing Presence. Via the Connection

The user sets their own presence via the SetPresence method. Parameters are a status identifier (e.g. available, away, hidden) and an optional status message (e.g. "At the Movies"). Valid status identifiers for this connection can be retrieved using the Statuses property (see above). This is shown in Example 5-4.

Example 5-4Requesting the Statuses and Setting Our Presence
# request the statuses
print 'Requesting statuses...'
                        reply_handler = self.get_statuses_cb,
                        error_handler = self.error_cb)

# set our presence
print 'Setting presence...'
                        'At the Movies',
                        reply_handler = self.generic_reply,
                        error_handler = self.error_cb)

Complete Source Code

5.3.4. Retrieving Contacts' Presence

This is documented in Section 7.2 ― Presence.