Interface Connection.Interface.ClientTypes1

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

im.telepathy1.Connection.Interface.ClientTypes1/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:

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:

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 Presence1 interface.

For example, if a contact has two resources:

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 im.telepathy1.Connection.Interface.Contacts interface.
(Permalink)

im.telepathy1.Connection.Interface.ClientTypes1/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.