Conn.I.Presence — Telepathy D-Bus Interface Specification

# Interface Connection.Interface.Presence

Interface Index (Compact) | Summary | Description | Methods | Signals | Types

### Methods

AddStatus | (s: Status, a{sv}: Parameters) | → | nothing |
ClearStatus | () | → | nothing |
GetPresence | (au: Contacts) | → | a{u(ua{sa{sv}})}: Presence |
GetStatuses | () | → | a{s(ubba{ss})}: Available_Statuses |
RemoveStatus | (s: Status) | → | nothing |
RequestPresence | (au: Contacts) | → | nothing |
SetLastActivityTime | (u: Time) | → | nothing |
SetStatus | (a{sa{sv}}: Statuses) | → | nothing |

### Signals

PresenceUpdate | (a{u(ua{sa{sv}})}: Presence) |

### Types

Multiple_Status_Map | Mapping | a{sa{sv}} |
Contact_Presences | Mapping | a{u(ua{sa{sv}})} |
Status_Spec_Map | Mapping | a{s(ubba{ss})} |
Last_Activity_And_Statuses | Struct | (ua{sa{sv}}) |
Status_Spec | Struct | (ubba{ss}) |

Changed in 0.17.23. Connection managers implementing Presence MUST implement SimplePresence too.
Deprecated since 0.17.21. Client implementations SHOULD use SimplePresence instead.
Objects implementing this interface must also implement:

- org.freedesktop.Telepathy.Connection
- org.freedesktop.Telepathy.Connection.Interface.SimplePresence

### Description

This interface is for services which have a concept of presence which can be published for yourself and monitored on your contacts. Telepathy's definition of presence is based on that used by the Galago project.

Presence on an individual (yourself or one of your contacts) is modelled as a last activity time along with a set of zero or more statuses, each of which may have arbitrary key/value parameters. Valid statuses are defined per connection, and a list of them can be obtained with the GetStatuses method.

(The SimplePresence interface which replaces this one restricts presences to one status per contact, with an optional message, which is in practice all that was implemented on this interface.)

Each status has an arbitrary string identifier which should have an agreed meaning between the connection manager and any client which is expected to make use of it. The well-known values defined by the SimplePresence interface SHOULD be used where possible

As well as these well-known status identifiers, every status also has a numerical type value chosen from Connection_Presence_Type which can be used by the client to classify even unknown statuses into different fundamental types.

These numerical types exist so that even if a client does not understand the string identifier being used, and hence cannot present the presence to the user to set on themselves, it may display an approximation of the presence if it is set on a contact.

The dictionary of variant types allows the connection manager to exchange further protocol-specific information with the client. It is recommended that the string (s) argument 'message' be interpreted as an optional message which can be associated with a presence status.

If the connection has a 'subscribe' contact list, PresenceUpdate signals should be emitted to indicate changes of contacts on this list, and should also be emitted for changes in your own presence. Depending on the protocol, the signal may also be emitted for others such as people with whom you are communicating, and any user interface should be updated accordingly.

On some protocols, RequestPresence may only succeed on contacts on your 'subscribe' list, and other contacts will cause a PermissionDenied error. On protocols where there is no 'subscribe' list, and RequestPresence succeeds, a client may poll the server intermittently to update any display of presence information.

# Methods

(Permalink)

## AddStatus (s: Status, a{sv}: Parameters) → nothing

### Parameters

- Status — s
The string identifier of the desired status
- Parameters — a{sv} (String_Variant_Map)
A dictionary of optional parameter names mapped to their variant-boxed values

Request that a single presence status is published for the user, along with any desired parameters. Changes will be indicated by PresenceUpdate signals being emitted.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Invalid Argument
Raised when one of the provided arguments is invalid.
- Not Available
Raised when the requested functionality is temporarily unavailable.
- Permission Denied
The user is not permitted to perform the requested operation.

(Permalink)

## ClearStatus () → nothing

Request that all of a user's presence statuses be removed. Be aware that this request may simply result in the statuses being replaced by a default available status. Changes will be indicated by PresenceUpdate signals being emitted.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Permission Denied
The user is not permitted to perform the requested operation.

(Permalink)

## GetPresence (au: Contacts) → a{u(ua{sa{sv}})}: Presence

### Parameters

- Contacts — au (Contact_Handle_List)
An array of the contacts whose presence should be obtained

### Returns

- Presence — a{u(ua{sa{sv}})} (Contact_Presences)
Presence information in the same format as for the PresenceUpdate signal

Get presence previously emitted by PresenceUpdate for the given contacts. Data is returned in the same structure as the PresenceUpdate signal. Using this method in favour of RequestPresence has the advantage that it will not wake up each client connected to the PresenceUpdate signal.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Invalid Handle
The handle specified is unknown on this channel or connection.
- Not Available
Raised when the requested functionality is temporarily unavailable.

(Permalink)

## GetStatuses () → a{s(ubba{ss})}: Available_Statuses

### Returns

- Available_Statuses — a{s(ubba{ss})} (Status_Spec_Map)
A dictionary of string identifiers mapped to a struct for each status, containing:

- a type value from one of the values above
- a boolean to indicate if this status may be set on yourself
- a boolean to indicate if this is an exclusive status which you may not set alongside any other
- a dictionary of valid optional string argument names mapped to their types

Get a dictionary of the valid presence statuses for this connection. This is only available when online because only some statuses will be available on some servers.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.

(Permalink)

## RemoveStatus (s: Status) → nothing

### Parameters

- Status — s
The string identifier of the status not to publish anymore for the user

Request that the given presence status is no longer published for the user. Changes will be indicated by PresenceUpdate signals being emitted. As with ClearStatus, removing a status may actually result in it being replaced by a default available status.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Permission Denied
The user is not permitted to perform the requested operation.
- Invalid Argument
The status requested is not currently set

(Permalink)

## RequestPresence (au: Contacts) → nothing

### Parameters

- Contacts — au (Contact_Handle_List)
An array of the contacts whose presence should be obtained

Request the presence for contacts on this connection. A PresenceUpdate signal will be emitted when they are received. This is not the same as subscribing to the presence of a contact, which must be done using the 'subscription' ContactList, and on some protocols presence information may not be available unless a subscription exists.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Invalid Handle
The handle specified is unknown on this channel or connection.
- Permission Denied
The user is not permitted to perform the requested operation.
- Not Available
The presence of the requested contacts is not reported to this connection

(Permalink)

## SetLastActivityTime (u: Time) → nothing

### Parameters

- Time — u (Unix_Timestamp)
A UNIX timestamp of the user's last activity time (in UTC)

Request that the recorded last activity time for the user be updated on the server.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Not Implemented
This protocol has no concept of idle time

(Permalink)

## SetStatus (a{sa{sv}}: Statuses) → nothing

### Parameters

- Statuses — a{sa{sv}} (Multiple_Status_Map)
A dictionary mapping status identifiers to dictionaries, which map optional parameter names to their variant-boxed values

Request that the user's presence be changed to the given statuses and desired parameters. Changes will be reflected by PresenceUpdate signals being emitted.

Statuses whose Connection_Presence_Type is Offline, Error or Unknown MUST NOT be passed to this function. Connection managers SHOULD reject these statuses.

##### Rationale:

The same rationale as for SimplePresence.SetPresence applies.

On certain protocols, this method may be called on a newly-created connection which is still in the DISCONNECTED state, and will sign on with the requested status. If the requested status is not available after signing on, NotAvailable will be returned and the connection will remain offline, or if the protocol does not support signing on with a certain status, Disconnected will be returned.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Not Available
Raised when the requested functionality is temporarily unavailable.
- Invalid Argument
Raised when one of the provided arguments is invalid.
- Permission Denied
The user is not permitted to perform the requested operation.

# Signals

(Permalink)

## PresenceUpdate (a{u(ua{sa{sv}})}: Presence)

### Parameters

- Presence — a{u(ua{sa{sv}})} (Contact_Presences)
A dictionary of contact handles mapped to a struct containing a UNIX timestamp of the last activity time (in UTC), and a dictionary mapping the contact's current status identifiers to a dictionary of optional parameter names mapped to their variant-boxed values

This signal should be emitted when your own presence has been changed, or the presence of the member of any of the connection's channels has been changed, or when the presence requested by RequestPresence is available.

# Types

Mapping (Permalink)

## Multiple_Status_Map — a{sa{sv}}

Mapping used in Last_Activity_And_Statuses and passed to SetStatus, representing a collection of statuses. Use of this mapping with more than one member is deprecated.

- Status — s
- Parameters — a{sv} (String_Variant_Map)

Mapping (Permalink)

## Contact_Presences — a{u(ua{sa{sv}})}

Mapping returned by GetPresence and signalled by PresenceUpdate, where the keys are contacts and the values represent their presences.

- Contact — u (Contact_Handle)
- Presence — (ua{sa{sv}}) (Last_Activity_And_Statuses)

Mapping (Permalink)

## Status_Spec_Map — a{s(ubba{ss})}

- Identifier — s
- Spec — (ubba{ss}) (Status_Spec)

Struct (Permalink)

## Last_Activity_And_Statuses — (ua{sa{sv}})

Structure representing a contact's presence, containing a last-activity time (deprecated) and a Multiple_Status_Map.

- Last_Activity — u (Unix_Timestamp)
- Statuses — a{sa{sv}} (Multiple_Status_Map)

Struct (Permalink)

## Status_Spec — (ubba{ss})

- Type — u (Connection_Presence_Type)
- May_Set_On_Self — b
- Exclusive — b
- Parameter_Types — a{ss} (String_String_Map)