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).
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.
The SimplePresence tuple is a D-Bus structure consisting of three members that is used throughout Telepathy.
The three members are:
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).
A status string (e.g. "available" or "xa").
This status string must valid for this Connection, as returned by the Statuses property (see below).
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).
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).
| 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 |
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.
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.
# request the statuses print 'Requesting statuses...' conn[DBUS_PROPERTIES].Get(CONNECTION_INTERFACE_SIMPLE_PRESENCE, 'Statuses', reply_handler = self.get_statuses_cb, error_handler = self.error_cb) # set our presence print 'Setting presence...' conn[CONNECTION_INTERFACE_SIMPLE_PRESENCE].SetPresence( 'away', 'At the Movies', reply_handler = self.generic_reply, error_handler = self.error_cb)