Interface Connection.Interface.Resources1

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

Methods

GetResources (au: Contacts) → a{ua{sa{sv}}}: Resources

Signals

ResourcesUpdated (u: Contact, a{sa{sv}}: Resources)

Properties

ResourcesHumanReadable u (Resources_Human_Readability) Read only

Contact Attributes

im.telepathy1.Connection.Interface.Resources1/resources a{sa{sv}} (Resource_Information_Map)

Types

Resources_Human_Readability Enum u
Resource_Information_Map Mapping a{sa{sv}}
Resources_Attributes_Map Mapping a{ua{sa{sv}}}
WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Added in 0.21.1. (draft 1)
Objects implementing this interface must also implement:

Description

An interface on connections to show contact attributes for specific resources of a contact, if the protocol supports multiple resources. Resources are most common in XMPP, hence the name of this interface, but they are also present in MSN, where they are called points of presence.

When a client requests some attribute of a contact using its handle on the connection, the CM uses an algorithm to choose the most appropriate resource for the job. If there is only one resource, then the choice is obvious. If, however, there is more than one resource connected at any one time, the CM either aggregates all appropriate information to return (in the case of capabilities), or chooses one specific resource (in the case of presence).

Resources in XMPP have names, and it can be extremely useful for the user to be able to know which resources of a contact are online, providing the names are human-readable. Before now, resources have not been exposed in Telepathy, but this interface attempts to change this.

When using this interface, it is a little like using the Contacts interface, but only resource-specific attributes are ever returned. The resource-specific contact attributes are decided on by the CM, but XMPP's are listed below:

Methods

(Permalink)

GetResources (au: Contacts) → a{ua{sa{sv}}}: Resources

Parameters

  • Contacts — au (Contact_Handle_List)
    • The contacts whose resource attributes should be returned.

Returns

  • Resources — a{ua{sa{sv}}} (Resources_Attributes_Map)

    • The contacts' resources and the contact attributes specific to each resource. 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.

    For every contact handle passed into this method, it is guaranteed that there will be a key in the returned map that corresponds to said handle. If there is no information regarding the contact the resource information map will be empty.

Return the resource information of the given contacts. If any of the contact attributes for specific resources of the given contacts' are not known return immediately without waiting for a reply.

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.

Signals

(Permalink)

ResourcesUpdated (u: Contact, a{sa{sv}}: Resources)

Parameters

  • Contact — u (Contact_Handle)
    • The contact.
  • Resources — a{sa{sv}} (Resource_Information_Map)
    • The contact's resource information. All resource information is given, not just the details which have changed.
Emitted when a contact has a resource added or removed, or any contact attribute for any resource changes.

Properties

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

ResourcesHumanReadable — u (Resources_Human_Readability)

Read only

Whether the resources returned from GetResources are human readable or not.

If the connection manager knows that all resource names are automatically generated, then the resource strings mean nothing to the user. Showing these strings in the UI would be confusing, so by setting this to Resources_Human_Readability_Never, the UI is advised not to show resources.

If on the other hand, all resources are set to nice names (such as "office" or "home") then it might be wise to expose these strings in the UI, so this property would be set to Resources_Human_Readability_Maybe. This is the case in XMPP -- most resources are set in a way that the user can deduce some information from them. The absence of an Always enum value is because in the case of XMPP, the resource string could be partially human-readable (as on Google Talk, where a resource of "home" is changed by the server to a unique string like "home_1234fdec") or not at all human-readable.

Contact Attributes

Attributes that a contact can have, accessed with the im.telepathy1.Connection.Interface.Contacts interface.
(Permalink)

im.telepathy1.Connection.Interface.Resources1/resources — a{sa{sv}} (Resource_Information_Map)

The same mapping that would be returned by GetResources for this contact.

Types

Enum (Permalink)

Resources_Human_Readability — u

  • Never (0)
    • The resource string is never human-readable.
  • Maybe (1)
    • The resource string might be human-readable.
Mapping (Permalink)

Resource_Information_Map — a{sa{sv}}

A map of a contact's resources to their resource-specific information.
  • Key — s

    • The name of the resource.

  • Contact_Attributes — a{sv} (Single_Contact_Attributes_Map)
    • A map of contact attributes whose data is specific to this resource.
Mapping (Permalink)

Resources_Attributes_Map — a{ua{sa{sv}}}

Mapping returned by GetResources, representing a collection of Contacts, their resources, and their resource-specific contact attributes.