Interface org.freedesktop.Telepathy.Connection.Interface.Contacts

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

Methods

GetContactAttributes (au: Handles, as: Interfaces, b: Hold) → a{ua{sv}}: Attributes

Properties

ContactAttributeInterfaces as (DBus_Interface_List) Read only

Types

Contact_Attribute Simple Type s
Single_Contact_Attributes_Map Mapping a{sv}
Contact_Attributes_Map Mapping a{ua{sv}}
Added in 0.17.9.
Objects implementing this interface must also implement:

Description

This interface allows many attributes of many contacts to be obtained in a single D-Bus round trip.

Each contact attribute has an string identifier (Contact_Attribute), which is namespaced by the D-Bus interface which defines it.

Methods

(Permalink)

GetContactAttributes (au: Handles, as: Interfaces, b: Hold) → a{ua{sv}}: Attributes

Parameters

  • Handles — au (Contact_Handle_List)
    • An array of handles representing contacts.
  • Interfaces — as (DBus_Interface_List)

    • A list of strings indicating which D-Bus interfaces the calling process is interested in. All supported attributes from these interfaces, whose values can be obtained without additional network activity, will be in the reply.

    It is an error to request interfaces that are not supported by this Connection (i.e. mentioned in the ContactAttributeInterfaces property).

    This makes it possible to distinguish between interfaces for which the Connection has nothing to say (e.g. we don't know the avatar tokens of any of the contacts, so we omitted them all), and interfaces for which this API isn't supported.

    Attributes from the interface org.freedesktop.Telepathy.Connection are always returned, and need not be requested explicitly.

    As well as returning cached information immediately, the connection MAY start asynchronous requests to obtain better values for the contact attributes. If better values are later obtained by this process, they will be indicated with the usual signals (such as AliasesChanged).

    For instance, an XMPP connection manager could download vCards in response to a request for Aliasing attributes.
  • Hold — b
    • If true, all handles in the result have been held on behalf of the calling process, as if by a call to Connection.HoldHandles.
    For further round-trip avoidance.

Returns

  • Attributes — a{ua{sv}} (Contact_Attributes_Map)

    • A dictionary mapping the contact handles to contact attributes. If any of the requested handles are in fact invalid, they are simply omitted from this mapping. If contact attributes are not immediately known, the behaviour is defined by the interface; the attribute should either be omitted from the result or replaced with a default value.

    Each contact's attributes will always include at least the identifier that would be obtained by inspecting the handle (org.freedesktop.Telepathy.Connection/contact-id).

Return any number of contact attributes for the given handles.

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.
    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 Argument
    • One of the requested interfaces is not supported (mentioned in ContactAttributeInterfaces).

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

ContactAttributeInterfaces — as (DBus_Interface_List)

Read only
A list of D-Bus interfaces for which GetContactAttributes is expected to work. This cannot change during the lifetime of the Connection.

Types

Simple Type (Permalink)

Contact_Attribute — s

A DBus_Interface, followed by a slash '/' character and an identifier for an attribute defined by that interface. The attribute identifier SHOULD be in lower case.
These aren't D-Bus core Properties, and we want them to look visibly different.
Mapping (Permalink)

Single_Contact_Attributes_Map — a{sv}

Some of the attributes of a single contact.
  • Attribute — s (Contact_Attribute)
    • The name of the attribute
  • Value — v
    • The value of the attribute
Mapping (Permalink)

Contact_Attributes_Map — a{ua{sv}}

Mapping returned by GetContactAttributes, representing a collection of Contacts and their requested attributes.