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

# Interface Connection.Interface.ClientTypes

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

### Methods

GetClientTypes | (au: Contacts) | → | a{uas}: Client_Types |
RequestClientTypes | (u: Contact) | → | as: Client_Types |

### Signals

ClientTypesUpdated | (u: Contact, as: Client_Types) |

### Contact Attributes

org.freedesktop.Telepathy.Connection.Interface.ClientTypes/client-types | as (Contact_Client_Type_List)

### Types

Contact_Client_Type | Simple Type | s |
Contact_Client_Types | Mapping | a{uas} |

Added in 0.21.1. (as stable API)
Objects implementing this interface must also implement:

- org.freedesktop.Telepathy.Connection

### Description

An interface on connections to support protocols which allows users to subscribe to the client types of their contacts.

One can connect to instant messaging networks on a huge variety of devices, from PCs, to phones to consoles. It can be useful for users to know what kind of device a contact is using so that he or she can decide not to send that big file or start a video chat. This interface exposes exactly this information for clients to display.

The client types are represented in strings, using the values documented by the XMPP registrar with some additional types added for other protocols. A contact can set one or more client types so this interface returns a list of strings to denote client types for a contact. The well-known client types to be used are:

- bot
- console (minimal non-GUI client used on dumb terminals or text-only screens, not a games console)
- handheld
- pc
- phone
- web

If the empty list is given as the client types, this means that details about the contact's client types are unknown. If there are multiple resources of a contact online at one point in time, the client types of the most available resource will be returned. In other words, the returned client types are those for the resource whose presence will be retreived using the SimplePresence interface.

For example, if a contact has two resources:

- their phone, with presence "available"; and
- their pc, with presence "busy";

then the methods in this interface will return an array (with one element: "phone") as the client types because that is the more available resource. If at some later time the contact's phone's presence changes to "away", the ClientTypesUpdated signal will notify that the contact's client types attribute has changed from ["phone"] to ["pc"], because "busy" is a more available presence than "away".

# Methods

(Permalink)

## GetClientTypes (au: Contacts) → a{uas}: Client_Types

### Parameters

- Contacts — au (Contact_Handle_List)
The contacts whose client types should be returned or signalled.

### Returns

- Client_Types — a{uas} (Contact_Client_Types)
The contacts' client types, if already known. Contacts whose client types are not already known are omitted from the mapping; contacts known to have no client type information appear in the mapping with an empty list.

Return the client types of the given contacts, if they are already known. If any of the given contacts' client types are not known, request their current client types, but return immediately without waiting for a reply; if a reply with a non-empty client type array is later received for those contacts, the ClientTypesUpdated signal will be emitted for them.

##### Rationale:

This method is appropriate for "lazy" client type finding, for instance displaying the client types (if available) of everyone in your contact list.

### 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.

(Permalink)

## RequestClientTypes (u: Contact) → as: Client_Types

### Parameters

- Contact — u (Contact_Handle)
The contact whose client types should be returned.

### Returns

- Client_Types — as (Contact_Client_Type_List)
The contact's client types. It MAY be empty, indicating that no client type information was found.

Return the current client types of the given contact. If necessary, make a request to the server for up-to-date information, and wait for a reply.

##### Rationale:

This method is appropriate for use in a "Contact Information..." dialog; it can be used to show progress information (while waiting for the method to return), and can distinguish between various error conditions.

### 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 requested contact does not allow the local user to see their client type information.

# Signals

(Permalink)

## ClientTypesUpdated (u: Contact, as: Client_Types)

### Parameters

- Contact — u (Contact_Handle)
The contact.
- Client_Types — as (Contact_Client_Type_List)
The contact's client types, or an empty list to indicate that nothing is known about the contact's client types.

Emitted when a contact's client types change or become known.

# Contact Attributes

Attributes that a contact can have, accessed with the org.freedesktop.Telepathy.Connection.Interface.Contacts interface.
(Permalink)

## org.freedesktop.Telepathy.Connection.Interface.ClientTypes/client-types — as (Contact_Client_Type_List)

The same mapping that would be returned by GetClientTypes for this contact. Omitted from the result if the contact's client types are not known.

# Types

Simple Type (Permalink)

## Contact_Client_Type — s

A string representing a single client type of a contact.
Mapping (Permalink)

## Contact_Client_Types — a{uas}

A mapping from contact handle to client types.

- Contact — u (Contact_Handle)
A contact.
- Client_Types — as (Contact_Client_Type_List)
The contact's client types as documented earlier in this interface.