Interface Connection.Interface.Contacts

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

Methods

GetContactAttributes (au: Handles, as: Interfaces, b: Hold) → a{ua{sv}}: Attributes
GetContactByID (s: Identifier, as: Interfaces) → u: Handle, a{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)
    • Changed in 0.19.2. requesting information for interfaces not mentioned in ContactAttributeInterfaces is no longer an error. Be aware that older connection managers may still consider this an error.

    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.

    Connection managers SHOULD ignore interfaces requested which they do not support (i.e. those not mentioned in the ContactAttributeInterfaces property.)

    Rationale:

    This simplifies client-side code. Clients which care may distinguish between unsupported interfaces (e.g. this Connection does not support Avatars), and interfaces on which no information is known for these contacts (e.g. we don't know the avatar tokens of any of the contacts, so we omitted them all) by inspecting ContactAttributeInterfaces.

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

    Rationale:
    For instance, an XMPP connection manager could download vCards in response to a request for Aliasing attributes.
  • Hold — b

    • If true, all handles that appear as keys in the result have been held on behalf of the calling process, as if by a call to Connection.HoldHandles. (If HasImmortalHandles is true, which SHOULD be the case in all new connection managers, this has no effect.)

    Rationale:

    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.
    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.
(Permalink)

GetContactByID (s: Identifier, as: Interfaces) → u: Handle, a{sv}: Attributes

Added in 0.27.0.

Parameters

  • Identifier — s
    • An identifier representing a contact.
  • 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.

    See GetContactAttributes for details.

Returns

  • Handle — u (Contact_Handle)

    • The contact's handle, as returned by RequestHandles

  • Attributes — a{sv} (Single_Contact_Attributes_Map)

    • All supported attributes of the contact on the given interfaces that can be returned without network round-trips. 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.

    The 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 identifier.
Rationale:
This is for a single identifier to make it simpler to use for the most common use case. For multiple contacts case, GetContactAttributes should be used.

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.

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.
Rationale:
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.