This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

(draft 1)

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:

SimplePresence/presence
ContactCapabilities/capabilities
ClientTypes/client-types

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. The contacts whose resource attributes should be returned.

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.

The resource string is never human-readable. The resource string might be human-readable.

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.

Emitted when a contact has a resource added or removed, or any contact attribute for any resource changes. The contact. The contact's resource information. All resource information is given, not just the details which have changed. A map of a contact's resources to their resource-specific information.

The name of the resource.

A map of contact attributes whose data is specific to this resource. Mapping returned by GetResources, representing a collection of Contacts, their resources, and their resource-specific contact attributes. A contact. A map of the contact's resources to their resource-specific information.

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